Saltar para o conteúdo principal
Este documento apresentará uma descrição da integração da Wan Videos Generation API, que pode gerar vídeos oficiais da Tongyi Wanxiang através da entrada de parâmetros personalizados.

​
Processo de Solicitação

Para usar a API, você precisa primeiro acessar a página correspondente da Wan Videos Generation API para solicitar o serviço correspondente. Após entrar na página, clique no botão “Acquire”, conforme mostrado na imagem: Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.

​
Uso Básico

Primeiro, entenda a forma básica de uso, que é inserir a palavra-chave prompt, a ação action, a imagem de referência do primeiro quadro image_url e o modelo model, para obter o resultado processado. Primeiro, é necessário passar um campo action, cujo valor é text2video. Ele contém duas ações principais: vídeo gerado por texto (text2video) e vídeo gerado por imagem (image2video). Em seguida, precisamos inserir o modelo model, que atualmente inclui os modelos wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v, conforme detalhado abaixo:

Podemos ver que aqui configuramos os Request Headers, incluindo:
  • accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
  • authorization: a chave de acesso à API, que pode ser selecionada diretamente após a solicitação.
Além disso, configuramos o Request Body, incluindo:
  • model: o modelo para gerar o vídeo, que inclui os modelos wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v.
  • action: a ação da tarefa de geração de vídeo, que inclui três ações principais: vídeo gerado por texto (text2video), vídeo gerado por imagem (image2video). Quando é vídeo gerado por texto, atualmente apenas o modelo wan2.6-t2v é suportado. Quando é vídeo gerado por imagem, atualmente apenas os modelos wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash são suportados.
  • image_url: quando a ação de vídeo gerado por imagem (image2video) é escolhida, é necessário fazer o upload do link da imagem de referência do primeiro quadro. Atualmente, apenas os modelos wan2.6-i2v e wan2.6-i2v-flash são suportados.
  • reference_video_urls: opcional ao gerar vídeo por imagem, especifica o link de vídeo de referência para a geração, atualmente apenas suportado pelo modelo wan2.6-r2v.
  • size: especifica a resolução do vídeo gerado, no formato largura*altura. O valor padrão e os valores enumerados disponíveis dependem do parâmetro model, as regras específicas podem ser consultadas na documentação oficial.
  • duration: a duração da geração do vídeo, suportando principalmente 5, 10, 15.
  • shot_type: opcional, especifica o tipo de cena do vídeo gerado, ou seja, se o vídeo é composto por uma cena contínua ou várias cenas alternadas. Condição de eficácia: apenas quando “prompt_extend”: true. Prioridade do parâmetro: shot_type > prompt. Por exemplo, se shot_type for definido como “single”, mesmo que o prompt contenha “gerar vídeo com múltiplas cenas”, o modelo ainda produzirá um vídeo de cena única, as regras específicas podem ser consultadas na documentação oficial.
  • negative_prompt: opcional, palavra-chave inversa, usada para descrever conteúdos que não se deseja ver na imagem do vídeo, podendo limitar a imagem do vídeo. Suporta chinês e inglês, com comprimento não superior a 500 caracteres, e o excesso será automaticamente truncado. Exemplos: baixa resolução, erro, pior qualidade, baixa qualidade, incompleto, dedos extras, proporção inadequada, etc.
  • resolution: especifica o nível de resolução do vídeo gerado, usado para ajustar a clareza do vídeo (total de pixels). O modelo ajusta automaticamente para um total de pixels próximo com base na resolução escolhida, e a proporção largura-altura do vídeo será mantida o mais próximo possível da proporção largura-altura da imagem de entrada img_url. Mais explicações podem ser encontradas na documentação oficial.
  • audio_url: URL do arquivo de áudio, o modelo usará esse áudio para gerar o vídeo. O uso pode ser consultado na documentação oficial.
  • audio: se o vídeo gerado deve ter som. Prioridade do parâmetro: audio > audio_url. Quando audio=false, mesmo que audio_url seja passado, a saída ainda será um vídeo sem som, e a cobrança será calculada como vídeo sem som, o valor padrão é true.
  • prompt_extend: se deve ativar a reescrita inteligente do prompt. Quando ativado, usa um modelo grande para reescrever inteligentemente o prompt de entrada. Para prompts mais curtos, o efeito de geração melhora significativamente, mas aumentará o tempo de processamento, o valor padrão é true.
  • prompt: palavra-chave.
  • callback_url: URL para onde os resultados devem ser retornados.
Após a seleção, você pode notar que o código correspondente também foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e assim obtemos o seguinte resultado: 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
O resultado retornado contém vários campos, descritos a seguir:
  • success, o estado atual da tarefa de geração de vídeo.
  • task_id, o ID da tarefa de geração de vídeo atual.
  • video_url, o link do vídeo gerado pela tarefa de geração de vídeo atual.
  • state, o estado atual da tarefa de geração de vídeo.
Podemos ver que obtivemos informações satisfatórias sobre o vídeo, e tudo o que precisamos fazer é acessar o link do vídeo gerado no video_url para obter o vídeo da Tongyi Wanxiang. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, por exemplo, o código CURL é o seguinte: 
curl -X POST 'https://api.acedata.cloud/wan/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "wan2.6-t2v",
  "prompt": "Astronautas se deslocam do espaço para um vulcão",
  "duration": 5
}'

​
Função de Vídeo Gerado por Imagem

Se você deseja gerar um vídeo a partir de uma imagem de referência ou vídeo de referência, pode definir o parâmetro action como image2video e inserir o link da imagem de referência ou do vídeo de referência. Em seguida, devemos preencher as palavras-chave que precisamos expandir para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo:
  • model: o modelo para gerar o vídeo, que inclui os modelos wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v.
  • image_url: ao escolher a ação de gerar vídeo a partir de imagem image2video, é necessário fazer o upload do link da imagem de referência da primeira frame, atualmente suportando apenas os modelos wan2.6-i2v, wan2.6-i2v-flash.
  • reference_video_urls: opcional ao gerar vídeo a partir de imagem, especifica o link do vídeo de referência para a geração, atualmente suportando apenas o modelo wan2.6-r2v.
  • prompt: palavras-chave.
Um exemplo de preenchimento é o seguinte:

Após o preenchimento, o código gerado automaticamente é o seguinte:

O código Python correspondente: 
import requests

url = "https://api.acedata.cloud/wan/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "image2video",
    "model": "wan2.6-i2v",
    "prompt": "Astronautas se deslocam do espaço para o vulcão",
    "duration": 5,
    "image_url": "https://cdn.acedata.cloud/r9vsv9.png",
    "callback_url": "https://www.baidu.com/"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Ao clicar em executar, você pode notar que um resultado é obtido, como abaixo: 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
Pode-se ver que o conteúdo do resultado é consistente com o acima, o que realiza a função de extensão de vídeo.

​
Callback Assíncrono

Como o tempo de geração da API Wan Videos Generation é relativamente longo, cerca de 1-2 minutos, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo callback_url adicional. Após o cliente fazer a solicitação à API, a API retornará imediatamente um resultado, incluindo um campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado do vídeo gerado será enviado ao callback_url especificado pelo cliente em formato JSON POST, incluindo também o campo task_id, permitindo que o resultado da tarefa seja associado pelo ID. Vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, e os desenvolvedores devem substituí-lo pela URL do servidor HTTP que construíram. Para facilitar a demonstração, usamos um site de exemplo de Webhook público https://webhook.site/, ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem: Copie esta URL para usá-la como Webhook, o exemplo aqui é https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Em seguida, podemos definir o campo callback_url para a URL do Webhook acima, ao mesmo tempo em que preenchemos os parâmetros correspondentes, conforme mostrado na imagem:

Ao clicar em executar, você pode notar que um resultado é obtido imediatamente, como abaixo: 
{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
Após um momento, podemos observar o resultado do vídeo gerado em https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, como mostrado na imagem: O conteúdo é o seguinte: 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
Pode-se ver que o resultado contém um campo task_id, e os outros campos são semelhantes aos mencionados anteriormente, permitindo a associação da tarefa através deste campo.

​
Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:
  • 400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
  • 429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
  • 500 api_error: Erro interno do servidor, algo deu errado no servidor.

​
Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusão

Através deste documento, você aprendeu como usar a API Wan Videos Generation para gerar vídeos através da entrada de palavras-chave e da imagem de referência da primeira frame. Esperamos que este documento ajude você a integrar e usar melhor esta API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.