O modelo de texto para vídeo Wan gera vídeos fluidos a partir de prompts de texto.
Referências: Guia do usuário
A região do seu modelo, a URL do endpoint e a chave de API devem corresponder. Chamadas entre regiões falham.
As tarefas de texto para vídeo levam de 1 a 5 minutos. A API usa invocação assíncrona: Criar uma tarefa → Consultar o resultado.
Substitua
Substitua
As tarefas de texto para vídeo levam de 1 a 5 minutos, portanto a API usa invocação assíncrona: Criar uma tarefa → Consultar o resultado.
Substitua
Substitua
Os nomes dos parâmetros do SDK correspondem principalmente à API HTTP, com estruturas seguindo as convenções específicas de cada linguagem.
As tarefas de texto para vídeo levam de 1 a 5 minutos. O SDK encapsula o fluxo de chamadas HTTP assíncronas e suporta invocação síncrona e assíncrona.
Defina region de acordo com a região do modelo (passada ao construir o Client; o valor de region varia conforme a região):
Substitua
Defina Constants.baseHttpApiUrl para o endpoint da região:
Substitua
Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolução.
R: Duas alterações são necessárias:
R: A conversão direta não é possível. Baixe o vídeo da URL e faça o upload para um armazenamento persistente (como o Alibaba Cloud OSS) para gerar um link permanente.
R: Não. O link expira após 24 horas. Baixe o vídeo, armazene-o de forma persistente e use um link permanente para reprodução.
Disponibilidade
A região do seu modelo, a URL do endpoint e a chave de API devem corresponder. Chamadas entre regiões falham.
- Selecione um modelo: Acesse Model Gallery para selecionar um modelo e verificar sua região.
- Selecione uma URL: Use a URL do endpoint para a região correspondente. HTTP e HTTPS são suportados.
- Configurar uma chave de API: Selecione uma região, obtenha uma chave de API e configure-a nas variáveis de ambiente.
- Instalar o SDK: Para chamar a API por meio de um SDK, instale o SDK do DashScope.
O código de exemplo neste tópico usa a região de Singapura.
HTTP (wan2.7)
As tarefas de texto para vídeo levam de 1 a 5 minutos. A API usa invocação assíncrona: Criar uma tarefa → Consultar o resultado.
Etapa 1: Criar uma tarefa
- Pequim
- Singapore
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis- Singapore
- Pequim
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis{WorkspaceId} pelo seu ID do espaço de trabalho.
- Após a criação da 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 polling para recuperar o resultado. - Para orientações para iniciantes, consulte Chamar APIs com Postman ou cURL.
Parâmetros de solicitação |
Controle a estrutura de planos com linguagem natural no prompt. O parâmetro shot_type não tem efeito.
| ||||||||||||||||||||||||
Cabeçalhos | |||||||||||||||||||||||||
Content-Type string (Obrigatório)O tipo de conteúdo da requisição. Deve ser application/json. | |||||||||||||||||||||||||
Authorization string (Obrigatório)Autentica a requisição com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx. | |||||||||||||||||||||||||
X-DashScope-Async string (Obrigatório)Habilita o processamento assíncrono. Requisições HTTP suportam apenas chamadas assíncronas. Deve ser enable. | |||||||||||||||||||||||||
Corpo da requisição | |||||||||||||||||||||||||
model string (Obrigatório)Nome do modelo. Para modelos e preços, consulte Preços dos modelos.Exemplo: wan2.7-t2v, wan2.7-t2v-2026-06-12. | |||||||||||||||||||||||||
input object (Obrigatório)Dados de entrada, incluindo o prompt.
Propriedades prompt string (Obrigatório)Prompt de texto descrevendo o conteúdo do vídeo e o estilo visual.Suporta chinês e inglês. Cada caractere ou letra conta como um. O texto além do limite é truncado automaticamente. Comprimento máximo por modelo:
string (Opcional)Elementos a serem excluídos do vídeo gerado.Suporta chinês e inglês. Máximo de 500 caracteres; textos mais longos são truncados automaticamente.Exemplo: baixa resolução, erro, pior qualidade, baixa qualidade, deformado, dedos extras, proporções ruins.audio_url string (Opcional)URL do arquivo de áudio para geração de vídeo.Formatos suportados:
| |||||||||||||||||||||||||
parameters object (Opcional)Parâmetros de geração de vídeo: resolução, reescrita de prompt e marca d'água.
Propriedades resolution string (Opcional)Nível de resolução do vídeo gerado. Controla a clareza da saída (contagem total de pixels).
string (Opcional)Proporção de aspecto do vídeo de saída.
integer (Opcional)Duração do vídeo de saída, em segundos.
boolean (Opcional)Ativa a reescrita de prompt. Quando ativado, um LLM reescreve o prompt de entrada para melhorar a qualidade da geração. Ideal para prompts curtos, mas adiciona latência.
boolean (Opcional)Adiciona uma marca d'água no canto inferior direito com o texto "AI Generated".
integer (Opcional)A semente de número aleatório deve ser um inteiro no intervalo [0, 2147483647].Se não for especificado, uma semente aleatória é 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 objectSaí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 requisição para rastreamento e solução de problemas. | |
code stringCódigo de erro. Retornado apenas para requisiçõ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
- Pequim
- Singapore
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}- Singapore
- Pequim
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}{WorkspaceId} pelo seu ID do espaço de trabalho.
- Recomendação de polling: A geração de vídeo leva vários minutos. Use um mecanismo de polling 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 de uma 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.
task_idvalidade: 24 horas. Após esse período, as consultas retornam o status da tarefa comoUNKNOWN.
Parâmetros de 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. Substitua {WorkspaceId} pelo seu ID do espaço de trabalho real. |
Cabeçalhos | |
Authorization string (Obrigatório)Autentica a requisiçã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 por apenas 24 horas e depois são removidas automaticamente. Salve os vídeos gerados prontamente. |
outputobjectSaí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 é AAAA-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 é AAAA-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 é AAAA-MM-DD HH:mm:ss.SSS.video_url stringURL do vídeo gerado. Retornado apenas quando task_status for SUCCEEDED.Válido 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 requisição prompt.code stringCódigo de erro. Retornado apenas para requisiçõ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 saída. Retornado apenas para tarefas bem-sucedidas.
Propriedades duration floatDuração total do vídeo, usada para cobrança.Igual a output_video_duration.input_video_duration integerValor fixo: 0.output_video_duration integerDuração do vídeo de saída em segundos. Corresponde ao valor de input.duration.SR integerNível de resolução do vídeo de saída. Exemplo: 720.ratio stringProporção de aspecto do vídeo de saída. Exemplo: 16:9.video_count integerNúmero de vídeos gerados. Sempre 1. | |
request_id stringIdentificador exclusivo da requisição para rastreamento e solução de problemas. |
HTTP (wan2.6 e anteriores)
As tarefas de texto para vídeo levam de 1 a 5 minutos, portanto a API usa invocação assíncrona: Criar uma tarefa → Consultar o resultado.
Etapa 1: Criar uma tarefa
- Singapore
- Virgínia
- Pequim
- Frankfurt
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis{WorkspaceId} pelo seu ID do espaço de trabalho.
- Após a criação da 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 polling para recuperar o resultado. - Para orientações para iniciantes, consulte Chamar APIs com Postman ou cURL.
Parâmetros de solicitação |
|
Cabeçalhos da requisição | |
Content-Type string (Obrigatório)O tipo de conteúdo da requisição. Deve ser application/json. | |
Authorization string (Obrigatório)Autentica a requisição com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx. | |
X-DashScope-Async string (Obrigatório)Habilita o processamento assíncrono. Requisições HTTP suportam apenas chamadas assíncronas. Deve ser enable. | |
Corpo da requisição | |
model string (Obrigatório)Nome do modelo. Para modelos e preços, consulte Preços dos modelos.Exemplo: wan2.6-t2v. | |
input object (Obrigatório)Dados de entrada, incluindo o prompt.
Propriedades prompt string (Obrigatório)Prompt de texto descrevendo o conteúdo do vídeo e o estilo visual.Suporta chinês e inglês. Cada caractere ou letra conta como um. O texto além do limite é truncado automaticamente. Comprimento máximo por modelo:
string (Opcional)Elementos a serem excluídos do vídeo gerado.Suporta chinês e inglês. Máximo de 500 caracteres; textos mais longos são truncados automaticamente.Exemplo: baixa resolução, erro, pior qualidade, baixa qualidade, desfigurado, dedos extras, proporções ruins.audio_url string (Opcional)Modelos suportados: séries wan2.6 e wan2.5.URL do arquivo de áudio para geração de vídeo.Formatos suportados:
| |
parameters object (Opcional)Parâmetros de geração de vídeo: resolução, reescrita de prompt e marca d'água.
Propriedades size string (Opcional)Resolução do vídeo de saída no formato width*height. Os padrões e valores válidos dependem do modelo:
integer (Opcional)Duração do vídeo de saída em segundos. Os valores válidos dependem do modelo:
boolean (Opcional)Ativa a reescrita de prompt. Quando ativado, um LLM reescreve o prompt de entrada para melhorar a qualidade. Ideal para prompts curtos, mas adiciona latência.
string (Opcional)Modelos suportados: modelos wan2.6.Estrutura de planos para o vídeo de saída: um plano contínuo ou múltiplos planos com transições.Valores válidos:
"prompt_extend": true está definido.Prioridade: shot_type substitui o prompt. Definir shot_type como single produz um vídeo de plano único mesmo que o prompt solicite múltiplos planos.watermark boolean (Opcional)Adiciona uma marca d'água no canto inferior direito com o texto "AI Generated".
integer (Opcional)A semente de número aleatório deve ser um inteiro no intervalo [0, 2147483647].Se não for especificado, uma semente aleatória é 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 objectSaí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 requisição para rastreamento e solução de problemas. | |
code stringCódigo de erro. Retornado apenas para requisiçõ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
- Singapore
- Virgínia
- Pequim
- Frankfurt
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}{WorkspaceId} pelo seu ID do espaço de trabalho.
- Recomendação de polling: A geração de vídeo leva vários minutos. Use um mecanismo de polling 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 de uma 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.
task_idvalidade: 24 horas. Após esse período, as consultas retornam o status da tarefa comoUNKNOWN.
Parâmetros de 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. Substitua {WorkspaceId} pelo seu ID do espaço de trabalho real. |
Cabeçalhos | |
Authorization string (Obrigatório)Autentica a requisiçã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 por apenas 24 horas e depois são removidas automaticamente. Salve os vídeos gerados prontamente. |
outputobjectSaí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 é AAAA-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 é AAAA-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 é AAAA-MM-DD HH:mm:ss.SSS.video_url stringURL do vídeo gerado. Retornado apenas quando task_status for SUCCEEDED.Válido 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 requisição prompt.actual_prompt stringQuando prompt_extend=true, o sistema reescreve o prompt de entrada. Este campo contém o prompt reescrito usado para a geração.
stringCódigo de erro. Retornado apenas para requisiçõ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 saída. Retornado apenas para tarefas bem-sucedidas.
Propriedades video_duration integerRetornado apenas para wan2.5 e anteriores (usado para cobrança).Duração do vídeo de saída em segundos. Valores válidos: 5, 10.duration floatRetornado apenas para wan2.6 (usado para cobrança).Duração total do vídeo. Fórmula: duration=input_video_duration+output_video_duration.input_video_duration integerRetornado apenas para wan2.6. Valor fixo: 0.output_video_duration integerRetornado apenas para wan2.6.Duração do vídeo de saída em segundos. Corresponde ao valor de input.duration.SR integerRetornado apenas para wan2.6. Nível de resolução do vídeo de saída. Exemplo: 720.size stringRetornado apenas para wan2.6. Resolução de saída no formato "largura×altura". Exemplo: 1920×1080.video_ratio stringRetornado apenas para wan2.5 e anteriores. Resolução de saída no formato "largura×altura". Exemplo: 832×480.video_count integerNúmero de vídeos gerados. Sempre 1. | |
request_id stringIdentificador exclusivo da requisição para rastreamento e solução de problemas. |
DashScope SDK
Os nomes dos parâmetros do SDK correspondem principalmente à API HTTP, com estruturas seguindo as convenções específicas de cada linguagem.
As tarefas de texto para vídeo levam de 1 a 5 minutos. O SDK encapsula o fluxo de chamadas HTTP assíncronas e suporta invocação síncrona e assíncrona.
O tempo real de processamento depende da profundidade da fila e da carga do serviço.
Python SDK
Defina region de acordo com a região do modelo (passada ao construir o Client; o valor de region varia conforme a região):
- Pequim
- Singapore
- Virgínia
region="cn-beijing"{WorkspaceId} pelo seu ID do espaço de trabalho.
- Invocação síncrona
- Invocação assíncrona
Exemplo de solicitação
Exemplo de resposta
O video_url expira após 24 horas. Faça o download imediatamente.
Java SDK
Defina Constants.baseHttpApiUrl para o endpoint da região:
- Singapore
- Virgínia
- Pequim
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";{WorkspaceId} pelo seu ID do espaço de trabalho.
- Invocação síncrona
- Invocação assíncrona
Exemplo de solicitação
Exemplo de resposta
O video_url expira após 24 horas. Faça o download imediatamente.
Limitações
- Retenção de dados: O ID da tarefa (
task_id) e a URL do vídeo (video_url) expiram após 24 horas. Após a expiração, eles não podem ser consultados ou baixados. - Moderação de conteúdo: A entrada e a saída passam por moderação de conteúdo. Conteúdo proibido aciona erros "IPInfringementSuspect" ou "DataInspectionFailed". Consulte Códigos de erro.
Códigos de erro
Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolução.
FAQ
P: Quais alterações de código são necessárias para atualizar de wan2.6 para wan2.7?
R: Duas alterações são necessárias:
- Controle de resolução: wan2.7 substitui o campo
size. Em vez disso, usa uma combinação deresolution(nível de resolução) eratio(proporção de tela) para definir a resolução de saída. Modelos anteriores usavam o camposize. - Remoção do tipo de plano: wan2.7 remove o campo
shot_type. Em vez disso, descreva a estrutura de planos diretamente no prompt.
P: Como converto um link de vídeo temporário em um permanente?
R: A conversão direta não é possível. Baixe o vídeo da URL e faça o upload para um armazenamento persistente (como o Alibaba Cloud OSS) para gerar um link permanente.
Código de exemplo: Baixar um vídeo para um dispositivo local
Código de exemplo: Baixar um vídeo para um dispositivo local