Skip to main content
Wan

Wan3.0 - Video Generation API Reference

O Wan3.0 é um modelo unificado de geração de vídeo baseado em referências que oferece suporte a Texto para Vídeo , Imagem para Vídeo (primeiro quadro/primeiro e último quadro) e Geração de Vídeo Baseada em Referência . Ele gera vídeos de até 30 segundos a 30 fps. Atualmente está em visualização .

Pré-requisitos

Para garantir o sucesso da chamada de API, certifique-se de que o modelo, a Endpoint URL e a API Key pertençam à mesma região. Chamadas entre regiões falharão.
Os códigos de exemplo neste tópico aplicam-se à região de Singapore.

Chamada HTTP

Como as tarefas de geração de vídeo demandam um tempo relativamente longo (geralmente de 1 a 5 minutos), a API utiliza chamadas assíncronas. Todo o processo consiste em duas etapas principais: "Criar uma tarefa -> Consultar resultados", conforme descrito abaixo:

Etapa 1: Criar uma tarefa e obter o ID da tarefa

  • Singapore
  • Beijing
  • US (Virginia)
  • China (Hong Kong)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
  • Após criar a tarefa, utilize o task_id retornado para consultar o resultado. O task_id permanece válido por 24 horas. Não crie tarefas duplicadas. Em vez disso, use consultas periódicas (polling) para recuperar o resultado.
  • Para orientações destinadas a iniciantes, consulte Call APIs with Postman or cURL.

Parâmetros da solicitação

  • Referência de Arquivo para Vídeo
  • Geração de Vídeo Baseada em Referência
  • Texto para Vídeo
  • Primeiro Quadro para Vídeo
  • Primeiro e Último Quadro para Vídeo
  • Edição de Vídeo
  • Extensão de Vídeo
Envie um arquivo por meio do tipo file, e o modelo compreenderá automaticamente o conteúdo do arquivo para gerar um vídeo.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
        -H 'X-DashScope-Async: enable' \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
        "model": "wan3.0-video",
        "input": {
            "prompt": "A high-end smart glasses product advertisement with a minimalist, futuristic, and fashionable style. The color palette features black, silver-gray, and ice-blue tones with subtle white light accents and parameter UI graphics. Opening in pure black background, a pair of smart glasses slowly emerges from darkness with refined highlights on the temple edges. The camera captures ultra-close details of lenses, nose pads, hinges, temples, and material textures, showcasing metal and high-performance composite materials. The product then rotates slowly in mid-air with minimalist motion graphics displaying core parameters. Then the camera pulls back as all parts precisely reassemble into the complete product, transitioning to a young model wearing demonstration in minimalist spaces and urban lighting environments.",
            "media": [
                {
                    "type": "file",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260806/ebapmr/glass.pptx"
                }
            ]
        },
        "parameters": {
            "resolution": "480P",
            "ratio": "adaptive",
            "duration": 10,
            "prompt_extend": true
        }
    }'
Cabeçalhos da solicitação (Headers)
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)Ativa o processamento assíncrono. As solicitações HTTP suportam apenas chamadas assíncronas. O valor deve ser enable.
Se este cabeçalho de solicitação estiver ausente, o erro "current user api does not support synchronous calls" será retornado.
Corpo da solicitação (Request Body)
model string (Obrigatório)Nome do modelo. Valor fixo: wan3.0-video.
input object (Obrigatório)Informações básicas de entrada. É necessário fornecer prompt ou media.

Propriedades

prompt string (Condicionalmente obrigatório)Prompt de texto usado para descrever o conteúdo desejado do vídeo. Este campo ou media deve ser fornecido.Suporta chinês e inglês. Cada caractere chinês ou letra conta como um caractere, com limite máximo de 20.000 caracteres. O conteúdo que exceder esse limite será truncado automaticamente.No modo de referência, você pode usar "Image 1", "Video 1", "Audio 1", etc. no prompt para se referir aos ativos de mídia na ordem correspondente dentro do array de mídia.media array (Condicionalmente obrigatório)Array de ativos de mídia que aceita imagens, vídeos, áudio, arquivos e páginas da web como entrada. Este campo ou prompt deve ser fornecido.
  • Cada elemento no array é um objeto de mídia contendo os campos type e url.
  • No modo de geração de vídeo baseada em referência, a ordem do array define a ordem de referência dos ativos no prompt. Imagens e vídeos são contados separadamente, ou seja, Image 1 e Video 1 podem coexistir.
    • O 1º reference_video no array corresponde ao Video 1, o 2º corresponde ao Video 2, e assim por diante.
    • A 1ª reference_image no array corresponde à Image 1, a 2ª corresponde à Image 2, e assim por diante.
    • O 1º reference_audio no array corresponde ao Audio 1, o 2º corresponde ao Audio 2, e assim por diante.

Propriedades

type string (Obrigatório)Tipo de ativo de mídia. Valores válidos:
  • first_frame: Imagem do primeiro quadro. Máximo de 1 imagem, usada estritamente como o primeiro quadro do vídeo.
  • last_frame: Imagem do último quadro. Máximo de 1 imagem, usada estritamente como o último quadro do vídeo.
  • reference_image: Imagem de referência. Máximo de 10 imagens.
  • reference_video: Vídeo de referência. Máximo de 5 clipes, com duração total não superior a 15 segundos.
  • reference_audio: Áudio de referência. Máximo de 5 clipes, com duração total não superior a 15 segundos.
  • file: Arquivo. Máximo de 1 arquivo, não pode ser usado junto com link.
  • link: Link da web. Máximo de 1 link, não pode ser usado junto com file.
Os tipos reference_xx/file/link e os tipos first_frame/last_frame são mutuamente exclusivos e não podem ser usados juntos na mesma solicitação.
url string (Obrigatório)URL do ativo de mídia ou dados codificados em Base64.

Imagem de entrada (type=first_frame / last_frame / reference_image)

URL da imagem ou dados codificados em Base64.Limites da imagem:
  • Formato: JPEG, JPG, PNG (canal transparente não suportado), BMP, WEBP.
  • Resolução: [240, 8000] pixels por lado.
  • Proporção: não superior a 8:1.
  • Tamanho do arquivo: não superior a 20 MB.
Formatos de entrada suportados:
  1. URL pública:
  2. String de imagem codificada em Base64:
    • Formato de dados: data:{MIME_type};base64,{base64_data}.
    • Exemplo: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (a string codificada é muito longa, apenas um fragmento é mostrado)
    • Para mais detalhes, consulte Input Image.

Vídeo de entrada (type=reference_video)

URL do vídeo de referência.Limites do vídeo:
  • Formato: mp4, mov.
  • Duração: [1, 15] segundos por clipe, com duração total não superior a 15 segundos.
  • Taxa de quadros: ≥16 fps.
  • Resolução: [240, 4096] pixels por lado.
  • Proporção: não superior a 8:1.
  • Tamanho do arquivo por clipe: não superior a 100 MB.
Formatos de entrada suportados:
  1. URL pública:

Áudio de entrada (type=reference_audio)

URL do áudio de referência.Limites do áudio:
  • Formato: wav, mp3.
  • Duração: [1, 15] segundos por clipe, com duração total não superior a 15 segundos.
  • Tamanho do arquivo: não superior a 15 MB.
Formatos de entrada suportados:
  1. URL pública:

Arquivo de entrada (type=file)

URL do arquivo.Limites do arquivo:
  • Formato: docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, md.
  • Tamanho do arquivo: não superior a 100 MB.
  • Limite de páginas: não superior a 50 páginas (validado para formatos pdf, docx, doc, pptx, ppt, key, pages).
Formatos de entrada suportados:
  1. URL pública:

Link da web de entrada (type=link)

parameters object (Opcional)Parâmetros de processamento de vídeo.

Propriedades

resolution string (Opcional)Nível de resolução do vídeo gerado. Valor padrão: 1080P. Valores válidos:
  • 1080P
  • 720P
  • 480P
ratio string (Opcional)Proporção do vídeo gerado. Valores válidos:
  • adaptive (Valor padrão): Proporção adaptativa que recomenda automaticamente uma proporção adequada com base nas dimensões da mídia de entrada e na intenção.
  • 21:9
  • 16:9
  • 4:3
  • 1:1
  • 3:4
  • 9:16
duration integer (Opcional)Duração do vídeo gerado, em segundos. Valor padrão: 5.
  • Sem entrada de vídeo: um número inteiro no intervalo [2, 30].
  • Com entrada de vídeo: a duração total do vídeo de entrada + a duração do vídeo de saída não deve exceder 30 segundos.
  • Quando definido como -1: Modo de duração inteligente, onde o modelo recomenda automaticamente uma duração adequada com base no prompt de entrada, no conteúdo e na rich media.
audio boolean (Opcional)Define se o vídeo de saída contém áudio.
  • true: Valor padrão, o vídeo de saída contém áudio.
  • false: O vídeo de saída não contém faixa de áudio.
Ativar ou desativar o áudio não afeta o preço.seed integer (Opcional)Semente aleatória. Usada para reproduzir resultados de geração. Intervalo de valores: [0, 2147483647].prompt_extend boolean (Opcional)Define se a reescrita inteligente de prompt está ativada. Quando ativada, um modelo de linguagem grande reescreve o prompt de entrada. Isso melhora significativamente a qualidade da geração para prompts mais curtos, mas aumenta a latência.
  • true: Valor padrão, a reescrita inteligente está ativada.
  • false: A reescrita inteligente está desativada.
Quando um documento (file) ou página da web (link) é fornecido como entrada, prompt_extend deve ser definido como true.
watermark boolean (Opcional)Define se uma marca d'água será adicionada.
  • false: Valor padrão, nenhuma marca d'água é adicionada.
  • true: Uma marca d'água é adicionada.

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 stringO ID da tarefa. Válido para consultas por 24 horas.task_status stringO status da tarefa.

Valores de enumeração

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: A tarefa não existe ou seu status é desconhecido.
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 Error codes.
message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Error codes.

Etapa 2: Consultar resultados pelo ID da tarefa

  • Singapore
  • Beijing
  • US (Virginia)
  • China (Hong Kong)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Recomendação de polling: 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 armazenamento permanente, como OSS.
  • Validade do task_id: 24 horas. Após esse período, as consultas retornarão o status da tarefa como UNKNOWN.

Parâmetros da solicitação

  • Consultar resultados da tarefa
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 workspace ID real.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"
Cabeçalhos da solicitação (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 (Path parameters)
task_id string (Obrigatório)O ID da tarefa.

Parâmetros da resposta

  • Tarefa bem-sucedida
  • Tarefa falhou
  • Consulta de tarefa expirada
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": "78c9b768-0285-996c-b682-xxxxxx",
    "output": {
        "task_id": "17ed7e50-00cf-4509-aea1-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-06 10:01:35.452",
        "scheduled_time": "2026-08-06 10:01:35.507",
        "end_time": "2026-08-06 10:13:33.838",
        "orig_prompt": "A golden retriever running on a sunny beach, waves crashing in the background, cinematic lighting",
        "video_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/video.mp4"
    },
    "usage": {
        "video_count": 1,
        "duration": 5,0,
        "input_video_duration": 0,0,
        "output_video_duration": 5,0,
        "fps": 30,
        "SR": 720,
        "ratio": "16:9"
    }
}
output objectInformações de saída da tarefa.

Propriedades

task_id string (Obrigatório)O ID da tarefa.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 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.orig_prompt stringO prompt de entrada original.video_url stringURL do vídeo gerado. Retornada quando a tarefa é bem-sucedida.code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Error codes.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Error codes.
usage objectEstatísticas de saída. Conta apenas resultados bem-sucedidos.

Propriedades

video_count integerNúmero de vídeos gerados. Fixo em 1.duration floatDuração do vídeo gerado, em segundos.input_video_duration floatDuração do vídeo de entrada, em segundos. Retorna 0,0 quando nenhum vídeo é fornecido como entrada.output_video_duration floatDuração do vídeo de saída, em segundos.fps integerTaxa de quadros do vídeo gerado. Valor padrão: 30.SR integerResolução do vídeo gerado. Exemplo: 720.ratio stringProporção do vídeo gerado. Exemplo: 16:9.
request_id stringIdentificador exclusivo da solicitação para rastreamento e solução de problemas.
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