Wan - Referência para Vídeo - API reference - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

O Wan-R2V aceita entrada multimodal (imagens, vídeos e áudio) para gerar vídeos com um ou mais personagens, preservando aparência e voz em diferentes cenas.

Referências: Guia do usuário

Disponibilidade

Para garantir chamadas de API bem-sucedidas, o modelo, a URL do endpoint e a chave de API devem pertencer à mesma região. Chamadas entre regiões falharão.

Selecione um modelo: Confirme a região do modelo.
Selecione uma URL: Escolha a URL do endpoint correspondente à região. URLs HTTP são suportadas.
Configure uma chave de API: Selecione uma região, obtenha uma chave de API e configure a chave de API como variável de ambiente.

ObservaçãoO código de exemplo neste tópico aplica-se à região de Singapura.

ImportanteO Model Studio lançou domínios específicos por workspace para as regiões China (Pequim) e Singapura. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:

China (Pequim): de https://dashscope.aliyuncs.com para https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapura: de https://dashscope-intl.aliyuncs.com para https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Model Studio. O domínio existente permanece totalmente funcional.

HTTP

ImportanteEsta API utiliza o novo protocolo e suporta o modelo wan2,7.

A geração de vídeo geralmente leva de 1 a 5 minutos; portanto, a API usa invocação assíncrona. O fluxo de trabalho possui duas etapas: crie uma tarefa e depois consultar o resultado.

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

Beijing

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Beijing

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Substitua {WorkspaceId} pelo seu ID do workspace real.

Observação

Após criar a tarefa, use o task_id retornado para consultar o resultado. O task_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	Referência multi-assunto (imagem + vídeo + voz) É possível passar vários ativos de referência (imagens e vídeos) e especifique uma voz 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": "wan2.7-r2v-2026-06-12", "input": { "prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, '\''The sunshine is so nice today.'\'' Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, '\''That sounds lovely. Can you sing it again?'\''", "media": [ { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg", "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3" }, { "type": "reference_video", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4", "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3" }, { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png" }, { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png" }, { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png" } ] }, "parameters": { "resolution": "720P", "ratio": "16:9", "duration": 10, "prompt_extend": false, "watermark": true } }' Referência de imagem única (imagem multi-painel) Forneça uma imagem de referência de nove painéis para controlar a história, a composição da câmera e o design dos personagens ao 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": "wan2.7-r2v-2026-06-12", "input": { "prompt": "Based on the reference image, in the style of a 3D cartoon adventure movie. The characters are in a cute Q-style but with detailed textures, smooth movements, and vibrant colors. Keep the characters and the forest scene consistent. Do not add text. Atmosphere: Adventurous, light-hearted, mysterious, whimsical. Characters: A young boy explorer with a round hat, backpack, and short cloak. His sidekick: a small flying robot with a round body and glowing blue eyes. Scene: A magical forest with giant tree roots, mushrooms, vines, a treasure cave entrance, and sunbeams. Storyboard: 1. Wide shot: Tall trees and intersecting sunbeams in the magical forest, creating a mysterious and bright environment. 2. Medium shot: The little boy pushes aside vines to explore forward. 3. Medium shot: The little robot flies beside him, scanning ahead with its blue light. 4. Close-up: An old treasure map unfolds in his hands. 5. Close-up: His face lights up with excitement. 6. Action shot: The two jump over tree roots and a small stream, venturing deeper into the forest. 7. Medium shot: A moss-covered treasure chest is revealed behind the vines. 8. Close-up: A golden glow emanates from the edge of the chest. 9. Final shot: The boy and the robot stand before the chest, looking at each other in surprise, filled with a sense of adventure.", "media": [ { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/wgjaxy/banana_storyboard_00000020.png" } ] }, "parameters": { "resolution": "720P", "duration": 10, "prompt_extend": false, "watermark": true } }'
Headers
Content-Type `string` (Required) O tipo de conteúdo da solicitação. Deve ser `application/json`.
Authorization `string` (Required) Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
X-DashScope-Async `string` (Required) Ative o processamento assíncrono. Solicitações HTTP suportam apenas chamadas assíncronas. Deve ser `enable`. ImportanteSe este header de solicitação estiver ausente, o erro "current user api does not support synchronous calls" será retornado.
Corpo da solicitação
model `string` (Required) O nome do modelo. Para obter uma lista de modelos e seus preços, consulte Preços dos modelos. Exemplo: wan2,7-r2v, wan2,7-r2v-2026-06-12.
input `object` (Required) As informações básicas de entrada, como o prompt. Propriedades prompt `string` (Required) O prompt de texto que descreve os elementos desejados e as características visuais do vídeo gerado. Suporta chinês e inglês. Cada caractere chinês, letra e sinal de pontuação conta como um caractere. O texto que exceder o limite será truncado automaticamente. wan2,7-r2v, wan2,7-r2v-2026-06-12: Até 5.000 caracteres. Identificadores de referência: Nos prompts, use identificadores como "Image 1, Image 2" para imagens e "Video 1, Video 2" para vídeos. Inclua um espaço entre a palavra e o número, e capitalize a primeira letra. A ordem dos identificadores deve corresponder à ordem dos ativos no array `media`. Imagens e vídeos são contados separadamente, então "Image 1" e "Video 1" podem coexistir. Se houver apenas uma imagem ou vídeo de referência, simplifique a referência para "the reference image" ou "the reference video". Descrição da cena: Por exemplo, se a imagem de referência 1 for um gato e a imagem 2 for uma sala. Para descrever o gato brincando na sala, use dois métodos. Um é usar diretamente os identificadores, como "Image 1 is playing in Image 2". O outro é complementar a descrição com o sujeito e a cena, como "The cat from Image 1 is playing in the room from Image 2". Quando a imagem de referência for um storyboard multi-painel, descreva a cena em formato de múltiplos planos no prompt. Não é necessário descrever cada painel — forneça os planos principais e o modelo reconhecerá automaticamente a lógica dos painéis e completará as cenas restantes. Para melhores resultados, use apenas uma imagem multi-painel por vez. Para dicas sobre o uso de prompts, consulte Guia de prompts texto-para-vídeo/imagem-para-vídeo. negative_prompt `string` (Optional) Um prompt negativo que descreve o conteúdo a ser excluído do vídeo gerado. Use-o para restringir a saída. Suporta chinês e inglês. Comprimento máximo: 500 caracteres. O texto que exceder o limite será truncado automaticamente. Exemplo: low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions. media `array` (Required) Um array de ativos de mídia (imagens, vídeos e áudio) usados como referências visuais e de áudio. As imagens podem incluir várias visualizações, comumente usadas para referenciar personagens, adereços e cenários. Cada elemento no array é um objeto de mídia que contém os campos `type` e `url`. A ordem dos elementos no array corresponde aos identificadores de referência no `prompt`. Imagens e vídeos são contados separadamente, então "Image 1" e "Video 1" podem coexistir. O primeiro `reference_video` no array corresponde ao Video 1, o segundo ao Video 2, e assim por diante. A primeira `reference_image` no array corresponde à Image 1, a segunda à Image 2, e assim por diante. Propriedades type `string` (Required) O tipo do ativo de mídia. Valores válidos: `reference_image`: Uma imagem de referência que fornece a referência visual para um personagem principal (pessoa, animal ou objeto) ou cenário. `reference_video`: Um vídeo de referência que fornece a referência visual e de voz para um personagem principal (pessoa, animal ou objeto). Evite usar vídeos de cenas vazias. `first_frame`: O primeiro quadro do vídeo. O vídeo gerado começa a partir deste quadro, que normalmente contém o personagem principal (pessoa, animal ou objeto). Combine um primeiro quadro com referências de assunto para controle conjunto. Casos de uso comuns: O assunto já aparece no primeiro quadro: Use uma referência de assunto para melhorar a consistência ou adicionar uma referência de voz. O assunto não aparece no primeiro quadro: Use uma referência de assunto para definir as características de um novo assunto que aparece durante o vídeo. Limites de ativos: Máximo de 1 imagem de primeiro quadro. Pelo menos 1 imagem de referência ou vídeo de referência. Imagens de referência + Vídeos de referência ≤ 5. Quando usado para um personagem principal, o ativo de referência deve conter apenas um único personagem. url `string` (Required) A URL do ativo de mídia. Cada valor pode apontar para uma imagem ou um vídeo. Passar uma imagem de referência (type=reference_image) A URL ou dados codificados em Base64 da imagem de referência. A imagem pode ser um assunto (pessoa, animal ou objeto) ou um fundo. Quando incluir um assunto, deve conter apenas um personagem. Limites de imagem: Formatos: JPEG, JPG, PNG (o canal alfa não é suportado), BMP ou WEBP. Resolução: A largura e a altura devem estar entre 240 e 8.000 pixels. Proporção: 1:8 a 8:1. Tamanho do arquivo: Até 20 MB. Formatos de entrada suportados: URL pública: Os protocolos HTTP e HTTPS são suportados. Exemplo: https://xxx/xxx.png. 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 e apenas um trecho é mostrado.) Para mais informações, consulte Passar uma imagem. Passar um vídeo de referência (type=reference_video) A URL do vídeo de referência. O vídeo deve incluir um assunto (pessoa, animal ou objeto). Evite usar vídeos de fundos ou cenas vazias. Quando o vídeo incluir um assunto, deve conter apenas um personagem. Se o vídeo tiver áudio, a voz também poderá ser referenciada. Limites de vídeo: Formatos: MP4 ou MOV. Duração: 1 a 30s. Resolução: A largura e a altura devem estar entre 240 e 4.096 pixels. Proporção: 1:8 a 8:1. Tamanho do arquivo: Até 100 MB. Formatos de entrada suportados: URL pública: Os protocolos HTTP e HTTPS são suportados. Exemplo: https://xxx/xxx.mp4. reference_voice `string` (Optional) A URL de áudio que especifica a voz para o personagem principal no ativo de referência (imagem ou vídeo). Use este parâmetro com `reference_image` ou `reference_video`. O áudio serve apenas como referência de voz e não determina o conteúdo falado. Para melhores resultados, faça o idioma do áudio de referência corresponder ao idioma do prompt. Lógica de áudio: Comportamento padrão: Se `reference_video` contiver áudio, mas `reference_voice` não for especificado, o áudio original do vídeo será usado. Prioridade: Se ambos `reference_video` (com áudio) e `reference_voice` forem fornecidos, `reference_voice` terá precedência e substituirá o áudio original do vídeo. Limites de áudio: Formatos: WAV ou MP3. Duração: 1 a 10s. Tamanho do arquivo: Até 15 MB. Formatos de entrada suportados: URL pública: Os protocolos HTTP e HTTPS são suportados. Exemplo: https://xxx/xxx.mp3.
parameters `object` (Optional) Os parâmetros de processamento de vídeo, como a resolução do vídeo. Propriedades resolution `string` (Optional) ImportanteA `resolution` afeta diretamente o custo. Confirme o preço no console do Model Studio antes de fazer a chamada. A categoria de resolução do vídeo gerado. Controla a contagem total de pixels. wan2,7-r2v, wan2,7-r2v-2026-06-12: Os valores válidos são 720P e 1080P. O valor padrão é `1080P`. ratio `string` (Optional) A proporção do vídeo gerado. Comportamento: Nenhuma imagem de primeiro quadro fornecida: O vídeo usa a `ratio` especificada. Imagem de primeiro quadro fornecida: O parâmetro `ratio` é ignorado. O vídeo corresponde à proporção da imagem de primeiro quadro. Valores válidos: `16:9` (padrão) `9:16` `1:1` `4:3` `3:4` duration `integer` (Optional) ImportanteA duração afeta diretamente o custo. Confirme os preços dos modelos antes de chamar a API. A duração do vídeo gerado em segundos. wan2,7-r2v, wan2,7-r2v-2026-06-12: O valor padrão é 5. Se o material de referência incluir um vídeo, o valor deve ser um inteiro de 2 a 10. Se o material de referência não incluir um vídeo, o valor deve ser um inteiro de 2 a 15. prompt_extend`boolean` (Optional) Ative a reescrita de prompt. Quando ativado, um modelo reescreve o prompt de entrada antes da geração. Isso melhora significativamente a qualidade para prompts mais curtos, mas aumenta o tempo de processamento. true (padrão) false watermark `boolean` (Optional) Adiciona uma marca d'água. O texto da marca d'água é "AI Generated", posicionado no canto inferior direito do vídeo. `false` (padrão) `true` seed `integer` (Optional) A semente de número aleatório deve ser um 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

Resposta bem-sucedida

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"
    }

Resposta de erro

Falha na criação da tarefa. Consulte Códigos de erro.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

output object

As informações de saída da tarefa.

Propriedades

task_id string

O ID da tarefa. Válido para consultas por 24 horas.

task_status string

O status da tarefa.

Valores de enumeração

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: A tarefa não existe ou seu status é desconhecido.

request_id string

Identificador único da solicitação para rastreamento e solução de problemas.

code string

Código de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.

message string

Mensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.

Etapa 2: Consultar o resultado pelo ID da tarefa

Beijing

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Beijing

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Substitua {WorkspaceId} pelo seu ID do workspace real.

Observação

Recomendação de consulta periódica: A geração de vídeo leva vários minutos. Utilize um mecanismo de consulta 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 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	Consultar o resultado 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. `curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
Headers
Authorization `string` (Required) Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
Parâmetros de caminho
task_id `string` (Required) O ID da tarefa.

Parâmetros de resposta

Tarefa bem-sucedida

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": "52cade0d-905e-9b7d-a01e-xxxxxx",
    "output": {
        "task_id": "18814247-f944-4102-aa4a-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-02 22:53:19.537",
        "scheduled_time": "2026-04-02 22:53:30.427",
        "end_time": "2026-04-02 23:00:39.287",
        "orig_prompt": "Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop, while Video 1 smiles, watches Video 2, and slowly walks towards him",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

Tarefa falhou

Quando uma tarefa falha, task_status é FAILED com um código de erro e mensagem. Consulte Códigos de erro.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

Consulta de tarefa expirada

O task_id é válido por 24 horas. Após esse período, as consultas retornam o seguinte erro.

{
        "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
        "output": {
            "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
            "task_status": "UNKNOWN"
        }
    }

outputobject

As informações de saída da tarefa.

Propriedades

task_id string (Required)

O ID da tarefa.

task_status string

O status da tarefa.

Valores de enumeração

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: A tarefa não existe ou seu status é desconhecido.

submit_time string

O 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 string

O 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 string

O 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 string

URL 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 string

O prompt de entrada original, correspondente ao parâmetro de solicitação prompt.

code string

Código de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.

message string

Mensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.

usage object

Estatísticas de saída. Preenchido apenas para tarefas bem-sucedidas.

Propriedades

input_video_duration integer

A duração do vídeo de entrada, em segundos.

output_video_duration integer

A duração do vídeo de saída, em segundos.

duration integer

A duração total do vídeo. O custo é calculado com base neste valor.

Fórmula: duration = input_video_duration + output_video_duration.

SR integer

A categoria de resolução do vídeo gerado. Exemplo: 720.

ratio string

A proporção do vídeo gerado. Exemplo: 16:9.

video_count integer

O número de vídeos gerados. O valor é sempre 1.

request_id string

Identificador único da solicitação para rastreamento e solução de problemas.

DashScope SDK

Os nomes dos parâmetros do SDK são amplamente consistentes com a API HTTP. A estrutura de parâmetros é encapsulada com base nos recursos da linguagem.

As tarefas de referência para vídeo geralmente levam de 1 a 5 minutos. O SDK encapsula o fluxo assíncrono HTTP e suporta chamadas síncronas e assíncronas.

O tempo real de processamento depende do tamanho da fila e do status do serviço.

Python SDK

ImportanteRequer DashScope Python SDK 1.25.16 ou posterior.

Versões mais antigas podem acionar erros como "url error, please check url!". Para instruções de atualização, consulte Instale o SDK.

Defina base_http_api_url com base na região do modelo:

Beijing

dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

Singapore

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

Singapore

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

Beijing

dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

Substitua {WorkspaceId} pelo seu ID do workspace real.

Chamada síncrona

Uma chamada síncrona bloqueia até que a geração do vídeo seja concluída e retorna o resultado diretamente.

Exemplo de solicitação

from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_sync_call_r2v():
    # Synchronous call, returns the result directly.
    print('please wait...')
    rsp = VideoSynthesis.call(
        api_key=api_key,
        model='wan2.7-r2v-2026-06-12',
        prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
        media=[
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        resolution='720P',
        ratio='16:9',
        duration=10,
        prompt_extend=False,
        watermark=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_sync_call_r2v()

Exemplo de resposta

A video_url é válida por 24 horas. Baixe o vídeo prontamente.

{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

Chamada assíncrona

Uma chamada assíncrona retorna um ID de tarefa imediatamente. Consulte periodicamente ou aguarde a conclusão separadamente.

Exemplo de solicitação

import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope

# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_async_call_r2v():
    # Asynchronous call, returns a task_id.
    rsp = VideoSynthesis.async_call(
        api_key=api_key,
        model='wan2.7-r2v-2026-06-12',
        prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
        media=[
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        resolution='720P',
        ratio='16:9',
        duration=10,
        prompt_extend=False,
        watermark=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print("task_id: %s" % rsp.output.task_id)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

    # Get asynchronous task information.
    status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # Wait for the asynchronous task to complete.
    rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_async_call_r2v()

Exemplo de resposta

Exemplo de resposta para criação de tarefa:

{
    "status_code": 200,
    "request_id": "6dc3bf6c-be18-9268-9c27-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "task_id": "686391d9-7ecf-4290-a8e9-xxxxxx",
        "task_status": "PENDING",
        "video_url": ""
    },
    "usage": null
}

Exemplo de resposta para consulta do resultado da tarefa:

A video_url é válida por 24 horas. Baixe o vídeo prontamente.

{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

Java SDK

ImportanteCertifique-se de que a versão do DashScope Java SDK seja pelo menos 2.22.14 antes de executar o código abaixo.

Versões mais antigas podem acionar erros como "url error, please check url!". Para instruções de atualização, consulte Instale o SDK.

Defina baseHttpApiUrl com base na região do modelo:

Beijing

Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

Singapore

Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Singapore

Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Beijing

Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

Substitua {WorkspaceId} pelo seu ID do workspace real.

Chamada síncrona

Uma chamada síncrona bloqueia até que a geração do vídeo seja concluída e retorna o resultado diretamente.

Exemplo de solicitação

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2Video {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void ref2video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .parameters(parameters)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            ref2video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Exemplo de resposta

A video_url é válida por 24 horas. Baixe o vídeo prontamente.

{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Chamada assíncrona

Uma chamada assíncrona retorna um ID de tarefa imediatamente. Consulte periodicamente ou aguarde a conclusão separadamente.

Exemplo de solicitação

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisListResult;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2VideoAsync {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API key varies by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void asyncRef2video() throws ApiException, NoApiKeyException, InputRequiredException, InterruptedException {
        VideoSynthesis vs = new VideoSynthesis();
        List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .parameters(parameters)
                        .build();
        // Submit the asynchronous task.
        VideoSynthesisResult result = vs.asyncCall(param);
        System.out.println("task_id: " + result.getOutput().getTaskId());
        System.out.println(JsonUtils.toJson(result));

        // Wait for the task to complete.
        result = vs.wait(result, null);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            asyncRef2video();
        } catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Exemplo de resposta

Exemplo de resposta para criação de tarefa:

{
    "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
    "output": {
        "task_id": "7277e20e-aa01-4709-xxxxxxxx",
        "task_status": "PENDING"
    }
}

Exemplo de resposta para consulta do resultado da tarefa:

A video_url é válida por 24 horas. Baixe o vídeo prontamente.

{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

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

Como adiciono uma voz a um assunto (referência de voz)?

Apenas o wan2,7 suporta referência de voz. No objeto media, passe uma URL de áudio no parâmetro reference_voice para especificar uma voz de referência para uma imagem ou vídeo de referência.

{
    "media": [
        {
            "type": "reference_image",
            "url": "<URL of the reference image>",
            "reference_voice": "<URL of the audio>"
        },
        {
            "type": "reference_video",
            "url": "<URL of the reference video>",
            "reference_voice": "<URL of the audio>"
        }
    ]
}

Disponibilidade

HTTP

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

Beijing

Singapore

Singapore

Beijing

Parâmetros da solicitação

Referência multi-assunto (imagem + vídeo + voz)

Referência de imagem única (imagem multi-painel)

Headers

Corpo da solicitação

Parâmetros de resposta

Resposta bem-sucedida

Resposta de erro

Etapa 2: Consultar o resultado pelo ID da tarefa

Beijing

Singapore

Singapore

Beijing

Parâmetros da solicitação

Consultar o resultado da tarefa

Headers

Parâmetros de caminho

Parâmetros de resposta

Tarefa bem-sucedida

Tarefa falhou

Consulta de tarefa expirada

DashScope SDK

Python SDK

Beijing

Singapore

Singapore

Beijing

Chamada síncrona

Exemplo de solicitação

Exemplo de resposta

Chamada assíncrona

Exemplo de solicitação

Exemplo de resposta

Java SDK

Beijing

Singapore

Singapore

Beijing

Chamada síncrona

Exemplo de solicitação

Exemplo de resposta

Chamada assíncrona

Exemplo de solicitação

Exemplo de resposta

Códigos de erro

FAQ

Como adiciono uma voz a um assunto (referência de voz)?