O modelo de imagem para vídeo Wan 2.7 aceita entrada multimodal (texto, imagens, áudio e vídeo) e executa três tarefas: primeiro quadro para vídeo, primeiro e último quadro para vídeo e continuação de vídeo .
Referências: Guia do usuário
O modelo, a URL do endpoint e a chave de API devem pertencer à mesma região. Chamadas entre regiões falham.
As tarefas de imagem para vídeo geralmente levam de 1 a 5 minutos; portanto, a API usa invocação assíncrona. O fluxo de trabalho possui duas etapas: crie uma tarefa e, em seguida, consulte o resultado periodicamente.
Os nomes dos parâmetros do SDK correspondem aos da API HTTP. A estrutura dos parâmetros é encapsulada com base nas convenções da linguagem.
As tarefas de imagem para vídeo geralmente levam de 1 a 5 minutos. O SDK encapsula o processo de invocação assíncrona HTTP e suporta chamadas síncronas e assíncronas.
Defina dashscope.base_http_api_url com base na região do modelo:
Defina Constants.baseHttpApiUrl com base na região do modelo:
Se uma chamada de modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolver o problema.
R: A proporção de saída é determinada pelo material de entrada (imagem do primeiro quadro ou primeiro clipe de vídeo), mas não há garantia de correspondência exata. Pode ocorrer um pequeno desvio.
O exemplo a seguir explica a lógica usando uma imagem de primeiro quadro como entrada:
R: Os vídeos gerados pelos modelos são armazenados no OSS. A API retorna uma URL pública temporária. Para configurar uma lista de permissões de firewall para esta URL de download, observe o seguinte: O armazenamento subjacente pode mudar dinamicamente. Este tópico não fornece uma lista fixa de permissões 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 o gerente da sua conta para obter a lista mais recente de nomes de domínio do OSS.
A nova API de imagem para vídeo (modelo wan2.7) oferece suporte a todas as três tarefas. A API de imagem para vídeo a partir do primeiro quadro anterior (wan2.6 e versões anteriores) suporta apenas a geração de vídeo a partir do primeiro quadro.
Disponibilidade
O modelo, a URL do endpoint e a chave de API devem pertencer à mesma região. Chamadas entre regiões falham.
- Selecione um modelo: Verifique se o modelo está disponível na região de destino.
- Selecione uma URL: Escolha a URL do endpoint correspondente à região do seu modelo. Há suporte para URLs HTTP e do DashScope SDK.
- Configure uma chave de API: Obtenha uma chave de API para a região e, em seguida, configure a chave de API como uma variável de ambiente.
- Instale o SDK: Para fazer chamadas de API com o SDK, instale o DashScope SDK.
Os códigos de exemplo neste tópico aplicam-se à região de Singapura.
HTTP
As tarefas de imagem para vídeo geralmente levam de 1 a 5 minutos; portanto, a API usa invocação assíncrona. O fluxo de trabalho possui duas etapas: crie uma tarefa e, em seguida, consulte o resultado periodicamente.
Etapa 1: Crie uma tarefa e obter o ID da tarefa
- Pequim
- Singapura
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis- Singapura
- Pequim
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisSubstitua WorkspaceId pelo seu ID do Workspace real.- Após criar a tarefa, use o
task_idretornado para consultar o resultado. Otask_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 |
Gere um vídeo com base em uma imagem de primeiro quadro e áudio. |
Content-Type string (Obrigatório)O 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)Ative o processamento assíncrono. Solicitações HTTP suportam apenas chamadas assíncronas. Deve ser enable. | |
Corpo da solicitação | |
model string (Obrigatório)O nome do modelo. Para obter uma lista de modelos e seus preços, consulte Preços dos modelos.Exemplo: wan2.7-i2v-2026-04-25. | |
input object (Obrigatório)Informações básicas de entrada, incluindo o prompt.
Propriedades prompt string (Opcional)Prompt de texto que descreve os elementos e as características visuais do vídeo a ser gerado.Há suporte para chinês e inglês. Até 5.000 caracteres.Cada caractere chinês ou letra conta como um caractere. O texto que exceder o limite será truncado automaticamente.Exemplo: Um gatinho corre na grama.Para mais informações sobre como usar prompts, consulte o Guia de prompts para texto-para-vídeo/imagem-para-vídeo.negative_prompt string (Opcional)Descreve o conteúdo a ser excluído do vídeo.Há suporte para chinês e inglês. Máximo de 500 caracteres. O texto que exceder o limite será truncado automaticamente.Exemplo: baixa resolução, erro, melhor qualidade, baixa qualidade, deformado, dedos extras, proporções ruins.media array (Obrigatório)Materiais de referência (imagens, áudio e vídeo) para a geração de vídeo.Cada elemento é um objeto de mídia com os campos type e url.
Combinações de recursos Apenas as seguintes combinações de recursos são válidas. Combinações inválidas retornam um erro.
Propriedades type string (Obrigatório)O tipo de recurso de mídia. Valores válidos:
type pode aparecer no máximo uma vez no array media. Por exemplo, você não pode fornecer dois recursos first_frame.url string (Obrigatório)A URL do recurso de mídia (imagem, áudio ou vídeo).
Fornecer uma imagem (type=first_frame ou last_frame) URL ou dados codificados em Base64 para a imagem do primeiro ou último quadro.Limites de imagem:
Fornecer áudio (type=driving_audio) URL do arquivo de áudio.
Fornecer um vídeo (type=first_clip) URL do arquivo de vídeo. O modelo gera uma continuação com base no conteúdo do vídeo. O parâmetro duration controla a duração total máxima da saída.Por exemplo, se duration=15 e o vídeo de entrada tiver 3 s, o modelo gera uma continuação de 12 s. O vídeo final de saída terá 15 s e será faturado por 15 s.Limites de vídeo:
| |
parameters object (Opcional)Parâmetros de processamento de vídeo: resolução, duração, reescrita de prompt e marcas d'água.
Propriedades resolution string (Opcional)Nível de resolução para o vídeo gerado. Controla a contagem total de pixels.O modelo ajusta automaticamente o vídeo para uma contagem total de pixels próxima ao nível selecionado. A proporção da saída segue o material de entrada (primeiro quadro ou primeiro clipe de vídeo). Para detalhes, consulte as Perguntas frequentes.Os valores válidos são 720P e 1080P. Padrão: 1080P.duration integer (Opcional)Duração do vídeo gerado em segundos. O intervalo válido depende do modelo:Valores válidos: um número inteiro de 2 a 15. Padrão: 5.prompt_extendboolean (Opcional)Indica se a reescrita de prompt deve ser ativada. Quando ativado, um modelo reescreve o prompt de entrada para melhorar os resultados em prompts curtos, mas aumenta o tempo de processamento.
boolean (Opcional)Indica se deve ser adicionada uma marca d'água "AI Generated" no canto inferior direito do vídeo.
integer (Opcional)A semente de número aleatório deve ser um número inteiro no intervalo [0, 2147483647].Se não for especificada, uma semente aleatória será gerada. Uma semente fixa melhora a reprodutibilidade.Como a geração do modelo é probabilística, a mesma semente não garante resultados idênticos. |
Parâmetros de resposta |
Salve o task_id para consultar o status e o resultado da tarefa. |
output objectInformações de saída da tarefa.
Propriedades task_id stringO ID da tarefa. Válido para consultas por 24 horas.task_status stringO status da tarefa.
Valores de enumeração
| |
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas. | |
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. |
Etapa 2: Consultar o resultado pelo ID da tarefa
- Pequim
- Singapura
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}- Singapura
- Pequim
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}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 periódica com um 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 um 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 |
Substitua {task_id} pelo valor de task_id retornado pela chamada de API anterior. O task_id é válido para consultas por 24 horas. |
Cabeçalhos | |
Authorization string (Obrigatório)Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx. | |
Parâmetros de caminho | |
task_id string (Obrigatório)O ID da tarefa. |
Parâmetros de resposta |
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. |
outputobjectInformações de saída da tarefa.
Propriedades task_id stringO ID da tarefa. Válido para consultas por 24 horas.task_status stringO status da tarefa.
Valores de enumeração
stringO horá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 stringO horá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 stringO horá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.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.orig_prompt stringO prompt de entrada original, correspondente ao parâmetro de solicitação prompt.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 objectEstatísticas de uso. Calculadas apenas para tarefas bem-sucedidas.
Propriedades input_video_duration integerDuração do vídeo de entrada, em segundos.output_video_duration integerDuração do vídeo de saída, em segundos.duration integerDuração total do vídeo usada para faturamento.SR integerResolução do vídeo de saída. Exemplo: 720.video_count integerNúmero de vídeos de saída. Fixo em 1. | |
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas. |
DashScope SDK
Os nomes dos parâmetros do SDK correspondem aos da API HTTP. A estrutura dos parâmetros é encapsulada com base nas convenções da linguagem.
As tarefas de imagem para vídeo geralmente levam de 1 a 5 minutos. O SDK encapsula o processo de invocação assíncrona HTTP e suporta chamadas síncronas e assíncronas.
O tempo real de processamento depende da fila de tarefas e da carga do serviço. Aguarde o resultado.
Python SDK
Defina dashscope.base_http_api_url com base na região do modelo:
- Pequim
- Singapura
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'- Singapura
- Pequim
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'Substitua WorkspaceId pelo seu ID do Workspace real.- Chamada síncrona
- Chamada assíncrona
Exemplo de solicitação
Exemplo de resposta
A video_url é válida por 24 horas. Baixe o vídeo prontamente.
Java SDK
Defina Constants.baseHttpApiUrl com base na região do modelo:
- Pequim
- Singapura
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1"- Singapura
- Pequim
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"Substitua WorkspaceId pelo seu ID do Workspace real.- Chamada síncrona
- Chamada assíncrona
Uma chamada síncrona bloqueia a execução até que a geração do vídeo seja concluída e o resultado seja retornado.
Exemplo de solicitação
Exemplo de resposta
A video_url é válida por 24 horas. Baixe o vídeo prontamente.
Códigos de erro
Se uma chamada de modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolver o problema.
Perguntas frequentes
P: Como gero um vídeo com uma proporção específica, como 3:4?
R: A proporção de saída é determinada pelo material de entrada (imagem do primeiro quadro ou primeiro clipe de vídeo), mas não há garantia de correspondência exata. Pode ocorrer um pequeno desvio.
O exemplo a seguir explica a lógica usando uma imagem de primeiro quadro como entrada:
-
Por que ocorre desvio?
- Lógica de execução: O sistema usa a proporção da imagem de entrada como base, combinada com o total de pixels alvo para o nível de
resolution. Como a codificação de vídeo exige que largura e altura sejam múltiplos de 16, o sistema ajusta a saída para a resolução válida mais próxima. - Exemplo de cálculo: Uma imagem de entrada de 750 x 1.000 pixels (proporção 3:4 = 0,75) com resolução "720P" (~920.000 pixels totais) produz uma saída de 816 x 1.104 pixels (proporção ~0,739, ~900.000 pixels totais).
- Lógica de execução: O sistema usa a proporção da imagem de entrada como base, combinada com o total de pixels alvo para o nível de
-
Recomendações:
- Controle de entrada: Use um primeiro quadro ou clipe de vídeo que corresponda à sua proporção alvo.
- Pós-processamento: Para requisitos rigorosos de proporção, recorte o vídeo ou adicione barras pretas após a geração.