Skip to main content
Wan

Wan - referência da API de substituição de personagem em vídeo

Substitui o personagem principal de um vídeo por um personagem de uma imagem, preservando a cena original, a iluminação e o tom para uma integração perfeita.

  • Recursos principais: Substitui o personagem de um vídeo por uma pessoa de uma imagem especificada, mantendo as ações, expressões e o ambiente do vídeo original.
  • Cenários: Ideal para substituição de personagens na criação de conteúdo derivado e pós-produção.
O Alibaba Cloud Model Studio lançou domínios específicos para workspaces nas regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Beijing): de https://dashscope.aliyuncs.com para https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de https://dashscope-intl.aliyuncs.com para https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.

Exemplos

O wan2.2-animate-mix suporta dois modos de service: modo padrão (wan-std) e modo profissional (wan-pro). Consulte Faturamento e limitação de taxa para diferenças de desempenho e faturamento.
Imagem do personagemVídeo de referênciaVídeo de saída (modo padrãowan-std)Vídeo de saída (modo profissionalwan-pro)
mix_input_image

HTTP

Obtenha uma chave de API e exporte a chave de API como variável de ambiente.
As regiões China (Beijing) e Singapore possuem chaves de API e endpoints de solicitação separados. Não é possível usá-los de forma intercambiável. Chamadas entre regiões resultam em falhas de autenticação ou erros de service.
A substituição de personagem é um processo demorado; portanto, a API utiliza invocação assíncrona: crie uma tarefa e depois consulte o resultado periodicamente.

Etapa 1: Criar uma tarefa

Singapore:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis Beijing:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis
  • Após criar a tarefa, use o task_id retornado para consultar o resultado. O task_id é válido por 24 horas. Não crie tarefas duplicadas. Em vez disso, utilize consultas periódicas para recuperar o resultado.
  • Para orientações destinadas a iniciantes, consulte Chamar APIs com Postman ou cURL.

Parâmetros da solicitação

  • Substituição de personagem em vídeo
A seguir está a URL da região Singapore. Substitua {WorkspaceId} pelo ID do seu workspace Bailian. As URLs variam conforme a região.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
        --header 'X-DashScope-Async: enable' \
        --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
        --header 'Content-Type: application/json' \
        --data '{
            "model": "wan2.2-animate-mix",
            "input": {
                "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg",
                "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4",
                "watermark": true
            },
            "parameters": {
                "mode": "wan-std"
            }
          }'
Headers
Content-Type string (Obrigatório)Tipo de conteúdo da solicitação. Deve ser application/json.
Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
X-DashScope-Async string (Obrigatório)Ativa o processamento assíncrono. Solicitações HTTP suportam apenas chamadas assíncronas. Deve ser enable.
Se este header de solicitação estiver ausente, o erro "current user api does not support synchronous calls" será retornado.
Corpo da solicitação
model string (Obrigatório)Nome do modelo. Defina como wan2.2-animate-mix.
input object (Obrigatório)Imagens e vídeo de entrada para a substituição de personagem.

Propriedades

image_url string (Obrigatório)URL HTTP ou HTTPS publicamente acessível para a imagem do personagem. A URL não deve conter caracteres não ASCII (por exemplo, chinês). Caso contenha, codifique a URL antes de passá-la.
  • Formato: JPG, JPEG, PNG, BMP ou WEBP.
  • Resolução: Largura e altura devem estar individualmente no intervalo [200, 4096] pixels. A proporção deve estar entre 1:3 e 3:1.
  • Tamanho do arquivo: Até 5 MB.
  • Exemplo: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg
video_url string (Obrigatório)URL HTTP ou HTTPS publicamente acessível para o vídeo de referência. A URL não deve conter caracteres não ASCII (por exemplo, chinês). Caso contenha, codifique a URL antes de passá-la.Dica: Maior resolução e taxa de quadros melhoram a qualidade da saída.
  • Formato: MP4, AVI ou MOV.
  • Resolução: Largura e altura devem estar individualmente no intervalo [200, 2048] pixels. A proporção deve estar entre 1:3 e 3:1.
  • Tamanho do arquivo: Até 200 MB.
  • Duração: De 2 a 30 segundos.
  • Exemplo: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4
watermark boolean (Opcional)Adiciona uma marca d'água "AI Generated" no canto inferior direito do vídeo de saída.
  • false (padrão): Sem marca d'água.
  • true: Marca d'água adicionada.
parameters object (Obrigatório)

Propriedades

check_image boolean (Opcional)Controla se a imagem de entrada é verificada antes do processamento.
  • true (padrão): Verifica a imagem de entrada antes do processamento.
  • false: Ignora a verificação e processa a imagem diretamente.
mode string (Obrigatório)Modo de service. Dois modos estão disponíveis:
  • wan-std: Modo padrão. Geração mais rápida com menor custo. Mais indicado para visualizações rápidas e animações básicas.
  • wan-pro: Modo profissional. Animações mais suaves e melhor qualidade visual, com tempo de processamento maior e custo mais elevado.
Para detalhes, consulte Exemplos e Faturamento e limitação de taxa.

Parâmetros da resposta

  • Resposta bem-sucedida
  • Resposta de erro
Salve o task_id para consultar o status e o resultado da tarefa.
{
        "output": {
            "task_status": "PENDING",
            "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
        },
        "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
    }
output objectInformações de saída da tarefa.

Propriedades

task_id stringID da tarefa. Válido para consultas por 24 horas.task_status stringStatus da tarefa.

Valores de enumeração

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: A tarefa não existe ou seu status é desconhecido.
request_id stringIdentificador único da solicitação para rastreamento e solução de problemas.
message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.
code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.

Etapa 2: Consultar o resultado pelo ID da tarefa

  • China (Beijing)
  • Singapore
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}Ao chamar, substitua {WorkspaceId} pelo seu ID do workspace real.
  • Singapore
  • China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Ao chamar, substitua {WorkspaceId} pelo seu ID do workspace real.
  • Recomendação de consulta periódica: A geração de vídeo leva vários minutos. Utilize um mecanismo de consulta com intervalo razoável, como 15 segundos.
  • Transição de estado da tarefa: PENDING → RUNNING → SUCCEEDED ou FAILED.
  • Link do resultado: Após o sucesso da tarefa, uma URL de vídeo válida por 24 horas é retornada. Baixe e salve o vídeo em armazenamento permanente, como o OSS.
  • Validade do task_id: 24 horas. Após esse período, as consultas retornam o status da tarefa como UNKNOWN.

Parâmetros da solicitação

  • Consultar resultado da tarefa
Substitua 0385dc79-5ff8-4d82-bcb6-xxxxxx pelo seu task_id real.
A seguir está a URL da região Singapore. Substitua {WorkspaceId} pelo ID do seu workspace Bailian. As URLs variam conforme a região. 
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
        --header "Authorization: Bearer $DASHSCOPE_API_KEY"
Headers
Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
Parâmetros de caminho da URL
task_id string (Obrigatório)ID da tarefa.

Parâmetros da resposta

  • Tarefa bem-sucedida
  • Tarefa com falha
As URLs de vídeo são válidas apenas por 24 horas e depois são removidas automaticamente. Salve os vídeos gerados prontamente.
{
    "request_id": "a67f8716-18ef-447c-a286-xxxxxx",
    "output": {
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-18 15:32:00.105",
        "scheduled_time": "2025-09-18 15:32:15.066",
        "end_time": "2025-09-18 15:34:41.898",
        "results": {
            "video_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx"
        }
    },
    "usage": {
        "video_duration": 5,2,
        "video_ratio": "standard"
    }
}
output objectInformações de saída da tarefa.

Propriedades

task_id stringID da tarefa. Válido para consultas por 24 horas.task_status stringStatus da tarefa.

Valores de enumeração

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: A tarefa não existe ou seu status é desconhecido.
submit_time stringHorário em que a tarefa foi enviada. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringHorário em que a tarefa foi executada. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.end_time stringHorário em que a tarefa foi concluída. O horário está em UTC+8 e o formato é YYYY-MM-DD HH:mm:ss.SSS.results object

Propriedades

video_url stringURL do vídeo gerado. Retornada apenas quando task_status é SUCCEEDED.Válida por 24 horas. O vídeo está no formato MP4 com codificação H.264.
code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.
usage objectRetornado apenas para tarefas bem-sucedidas.

Propriedades

video_duration floatDuração do vídeo gerado, em segundos.video_ratio stringModo de service usado para esta solicitação. Retorna standard para o modo wan-std, ou pro para o modo wan-pro.
request_id stringIdentificador único da solicitação para rastreamento e solução de problemas.

Limitações

Retenção de dados: IDs de tarefas e URLs de vídeo são retidos por 24 horas. Baixe o vídeo para o seu dispositivo local antes que expirem. Moderação de conteúdo: Todo o conteúdo de entrada e saída está sujeito a moderação. Conteúdo proibido retorna erros IPInfringementSuspect ou DataInspectionFailed. Para detalhes, consulte Códigos de erro.

Faturamento e limitação de taxa

  • Para cota gratuita e preço unitário, consulte preços do modelo.
  • Para limites de taxa, consulte Série Wan.
  • Detalhes de faturamento:
    • O faturamento baseia-se na duração do vídeo de saída (em segundos) apenas para vídeos gerados com sucesso. A entrada não é cobrada.
    • Chamadas com falha e erros de processamento não incorrem em taxas nem consomem cota gratuita.

Códigos de erro

Se uma chamada falhar, consulte Códigos de erro.

Perguntas frequentes

P: Como visualizo o uso de chamadas do modelo?

R: Os dados de invocação têm atraso aproximado de 1 hora. Visualize as métricas (volume de invocações, contagem e taxa de sucesso) na página Monitoring (Singapore ou Beijing). Para mais informações, consulte Como visualizo registros de invocação de modelo?

P: Como posso melhorar a qualidade dos vídeos gerados?

R: Para obter melhores resultados:
  1. Enquadre o personagem consistentemente tanto na imagem de entrada quanto no vídeo de referência.
  2. Mantenha as proporções corporais consistentes entre a imagem e o vídeo.
  3. Use material de source em alta definição — imagens desfocadas ou vídeos com baixa taxa de quadros reduzem a precisão dos detalhes.
R: A conversão direta não é suportada. Configure seu backend para baixar o vídeo e carregá-lo no Object Storage Service (OSS) para obter um link de acesso permanente. 
import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # Set timeout
        response.raise_for_status() # Raise an exception if the HTTP status code is not 200
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"Video successfully downloaded to: {save_path}")
        # Logic for uploading to permanent storage can be added here
    except requests.exceptions.RequestException as e:
        print(f"Failed to download video: {e}")

if __name__ == '__main__':
    video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
    save_path = "video.mp4"
    download_and_save_video(video_url, save_path)
R: Isso não é recomendado — os links expiram após 24 horas. Baixe e armazene o vídeo em seu backend e, em seguida, sirva-o por meio de um link permanente.

P: Como obtenho a lista de permissões de nomes de domínio para armazenamento de vídeo?

R: Os vídeos gerados pelos modelos são armazenados no OSS. A API retorna uma URL pública temporária. Para configurar uma whitelist de firewall para esta URL de download, observe o seguinte: O armazenamento subjacente pode mudar dinamicamente. Este tópico não fornece uma whitelist fixa de nomes de domínio do OSS para evitar problemas de acesso causados por informações desatualizadas. Se você tiver requisitos de controle de segurança, entre em contato com seu gerente de conta para obter a lista mais recente de nomes de domínio do OSS.
Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais