O modelo Wan 2,2 gera um vídeo com transições suaves a partir de um primeiro quadro , um último quadro e um prompt de texto .
Documentos relacionados: Guia do usuário
Para garantir chamadas de API bem-sucedidas, o modelo, a URL do endpoint e a chave de API devem estar na mesma região. Chamadas entre regiões falharão.
Como as tarefas de imagem para vídeo são operações de longa duração que geralmente levam de 1 a 5 minutos, a API utiliza chamada assíncrona. O processo envolve duas etapas principais: crie uma tarefa e consulte o resultado periodicamente.
Os nomes dos parâmetros do SDK são amplamente consistentes com a API HTTP, e a estrutura segue as convenções de cada linguagem de programação.
Como as tarefas de imagem para vídeo são de longa duração (geralmente 1–5 minutos), o SDK lida internamente com as chamadas HTTP assíncronas, suportando métodos síncronos e assíncronos.
Defina o base_http_api_url com base na região do modelo:
Se uma chamada de modelo falhar, consulte Códigos de erro para solução de problemas.
R: A proporção de aspecto do vídeo de saída depende da imagem do primeiro quadro (first_frame_url). No entanto, não é possível garantir uma proporção exata (como 3:4 estrito), podendo haver pequenos desvios.
R: Os vídeos gerados pelos modelos são armazenados no OSS. A API retorna uma URL pública temporária. Para configure uma lista de permissões de firewall para esta URL de download, observe: o armazenamento subjacente pode mudar dinamicamente. Este tópico não fornece uma lista fixa de permissões de nomes de domínio do OSS para evitar problemas de acesso causados por informações desatualizadas. Se 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.
Observações de uso
Para garantir chamadas de API bem-sucedidas, o modelo, a URL do endpoint e a chave de API devem estar na mesma região. Chamadas entre regiões falharão.
- Selecione um modelo: Confirme a região onde o modelo está disponível.
- Selecione uma URL: Escolha a URL do endpoint correspondente à sua região. Há suporte tanto para URLs HTTP quanto para URLs do DashScope SDK.
- Configure sua chave de API: Selecione uma região, obtenha sua chave de API e defina-a como variável de ambiente.
- Instale o SDK: Para fazer chamadas de API com o SDK, instale o DashScope SDK.
Os exemplos de código neste tópico aplicam-se a Singapura.
Chamada HTTP
Como as tarefas de imagem para vídeo são operações de longa duração que geralmente levam de 1 a 5 minutos, a API utiliza chamada assíncrona. O processo envolve duas etapas principais: crie uma tarefa e consulte o resultado periodicamente.
Etapa 1: Crie uma tarefa
- China (Pequim)
- Singapura
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis- Singapura
- China (Pequim)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/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, use consultas periódicas para recuperar o resultado. - Para orientações a iniciantes, consulte Chamar APIs com Postman ou cURL.
Parâmetros da solicitação |
Gera um vídeo com base em um primeiro quadro, um último quadro e um prompt. |
Cabeçalhos da solicitação | |
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)Ative o processamento assíncrono. Solicitações HTTP suportam apenas chamadas assíncronas. Deve ser enable. | |
Corpo da solicitação | |
model string (Obrigatório)Nome do modelo. Exemplo: wan2.2-kf2v-flash.Para mais detalhes, consulte o console do Model Studio. | |
input object (Obrigatório)Contém a entrada principal da tarefa, como o prompt.
Propriedades prompt string (Opcional)Prompt de texto. Suporta chinês e inglês. Comprimento máximo de 800 caracteres. Caracteres chineses e letras contam como um único caractere. Textos que excederem esse limite serão truncados.Se houver mudanças significativas no assunto ou na cena entre o primeiro e o último quadros, recomendamos descrever o processo de transição, como movimento de câmera (por exemplo, "a câmera se move para a esquerda") ou movimento do assunto (por exemplo, "uma pessoa corre para frente").Exemplo: "Um pequeno gato preto olha curiosamente para o céu. A câmera sobe gradualmente do nível dos olhos e finalmente captura seu olhar curioso de uma vista de cima para baixo."Para dicas sobre como escrever prompts eficazes, consulte o Guia de prompts para texto para vídeo e imagem para vídeo.negative_prompt string (Opcional)Prompt negativo que descreve o conteúdo a ser excluído do vídeo, ajudando a restringir a saída.Suporta chinês e inglês. Comprimento máximo de 500 caracteres. Textos que excederem esse limite serão truncados.Exemplo: "baixa resolução, erro, pior qualidade, baixa qualidade, deformado, dedos extras, proporções ruins".first_frame_url string (Obrigatório)URL da imagem do primeiro quadro. A proporção de aspecto do vídeo de saída corresponderá à da imagem do primeiro quadro.A URL deve ser um endereço publicamente acessível que suporte HTTP ou HTTPS.Requisitos da imagem:
string (Obrigatório)URL da imagem do último quadro.A URL deve ser um endereço publicamente acessível que suporte HTTP ou HTTPS.Requisitos da imagem:
| |
parameters object (Opcional)Parâmetros de processamento de vídeo.
Propriedades resolution string (Opcional)Resolução do vídeo gerado. Este parâmetro ajusta a definição (total de pixels) sem alterar a proporção de aspecto.O valor padrão e os valores disponíveis dependem do parâmetro model, conforme descrito abaixo:
integer (Opcional)Valor fixo em 5.prompt_extendbool (Opcional)Defina se a reescrita de prompt deve ser ativada. Quando ativado, um modelo de linguagem grande (LLM) reescreve inteligentemente o prompt de entrada. Isso pode melhorar significativamente os resultados para prompts curtos, mas aumenta a latência.
bool (Opcional)Defina se uma marca d'água com o texto "AI-generated" deve ser adicionada ao canto inferior direito do vídeo.
integer (Opcional)A semente de número aleatório deve ser um inteiro no intervalo [0, 2147483647].Se não 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 da 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 stringID da tarefa. Válido para consultas por 24 horas.task_status stringStatus da tarefa.
Valores de enumeração
| |
request_id stringIdentificador único 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
- China (Pequim)
- Singapura
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}- Singapura
- China (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. Use um mecanismo de consulta periódica 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 |
Substitua 86ecf553-d340-4e21-xxxxxxxxx pelo seu task_id real.As chaves de API diferem por região. Para mais informações, consulte Obter uma chave de API. Se você usar um modelo na região China (Pequim), substitua |
Cabeçalhos da solicitação | |
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)ID da tarefa. |
Parâmetros da resposta |
As URLs de vídeo são válidas apenas por 24 horas e depois removidas automaticamente. Salve os vídeos gerados prontamente. |
outputobjectInformaçõ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
stringHorário de envio da tarefa. O horário está em UTC+8 e o formato é AAAA-MM-DD HH:mm:ss.SSS.scheduled_time stringHorário de execução da tarefa. O horário está em UTC+8 e o formato é AAAA-MM-DD HH:mm:ss.SSS.end_time stringHorário de conclusão da tarefa. O horário está em UTC+8 e o formato é AAAA-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 stringPrompt de entrada original, correspondente ao parâmetro de solicitação prompt.actual_prompt stringPrompt otimizado usado quando a reescrita de prompt está ativada. Não retornado quando desativado.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 da tarefa. Apenas tarefas bem-sucedidas são cobradas.
Propriedades video_duration integerDuração do vídeo gerado em segundos, sempre 5. Fórmula de cobrança: Custo = Segundos de vídeo × Preço unitário.video_count integerNúmero de vídeos gerados. Valor fixo em 1.video_ratio stringValor retornado atualmente apenas pelo modelo 2,1. Proporção de aspecto do vídeo gerado, fixa em standard.SR integerValor retornado atualmente apenas pelo modelo 2,2. Nível de resolução do vídeo gerado. Valores possíveis: 480, 720 e 1080. | |
request_id stringIdentificador único da solicitação para rastreamento e solução de problemas. |
Chamadas do DashScope SDK
Os nomes dos parâmetros do SDK são amplamente consistentes com a API HTTP, e a estrutura segue as convenções de cada linguagem de programação.
Como as tarefas de imagem para vídeo são de longa duração (geralmente 1–5 minutos), o SDK lida internamente com as chamadas HTTP assíncronas, suportando métodos síncronos e assíncronos.
O tempo real de processamento depende do número de tarefas na fila e do desempenho do serviço. Aguarde.
Chamadas do SDK Python
Defina o 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.Código de exemplo
- Chamada síncrona
- Chamada assíncrona
Este exemplo demonstra três métodos de entrada de imagem: URL pública, codificação Base64 e caminho de arquivo local.
Exemplo de solicitação
Exemplo de resposta
A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.
- Chamada síncrona
- Chamada assíncrona
Este exemplo demonstra uma chamada síncrona com dois métodos de entrada de imagem: URL pública e caminho de arquivo local.
Exemplo de solicitação
Exemplo de resposta
A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.
Chamadas do SDK Java
Código de exemplo
- Chamada síncrona
- Chamada assíncrona
Este exemplo demonstra uma chamada síncrona e suporta três métodos de entrada de imagem: URL pública, codificação Base64 e caminho de arquivo local.
Exemplo de solicitação
Exemplo de resposta
A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.
- Chamada síncrona
- Chamada assíncrona
Este exemplo demonstra uma chamada síncrona com dois métodos de entrada de imagem: URL pública e caminho de arquivo local.
Exemplo de solicitação
Exemplo de resposta
A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.
Limitações
- Retenção de dados: O
task_ide avideo_urlsão retidos por 24 horas. Após esse período, não podem ser consultados ou baixados. - Suporte a áudio: O serviço gera apenas vídeos silenciosos. Para gerar áudio, use a síntese de fala.
- Moderação de Conteúdo: A Moderação de Conteúdo analisa todos os prompts de entrada, imagens e vídeos de saída. Se qualquer conteúdo violar as políticas de uso, o serviço retornará um erro "IPInfringementSuspect" ou "DataInspectionFailed". Para mais detalhes, consulte Códigos de erro.
Códigos de erro
Se uma chamada de modelo falhar, consulte Códigos de erro para solução de problemas.
FAQ
P: Como gerar uma proporção de aspecto específica?
R: A proporção de aspecto do vídeo de saída depende da imagem do primeiro quadro (first_frame_url). No entanto, não é possível garantir uma proporção exata (como 3:4 estrito), podendo haver pequenos desvios.
-
Por que a proporção de aspecto apresenta desvios?
O modelo usa a proporção de aspecto da imagem de entrada como base e calcula a resolução válida mais próxima com base no total de pixels da configuração de
resolutionselecionada. Como a largura e a altura do vídeo devem ser múltiplos de 16, o modelo faz pequenos ajustes na resolução final.- Por exemplo, se você fornecer uma imagem de entrada de 750×1000 (proporção de 3:4 ou 0,75) e definir
resolutioncomo "720P" (visando aproximadamente 920.000 pixels), a saída real poderá ser 816×1104 (proporção de aproximadamente 0,739, com cerca de 900.000 pixels).
- Por exemplo, se você fornecer uma imagem de entrada de 750×1000 (proporção de 3:4 ou 0,75) e definir
-
Recomendações:
- Imagem de Entrada: Para melhores resultados, use uma imagem de primeiro quadro que corresponda à proporção de aspecto desejada.
- Pós-processamento: Se uma proporção de aspecto estrita for necessária, use uma ferramenta de edição de vídeo para cortar o vídeo gerado ou adicionar barras pretas.