Skip to main content
Wan

Wan - referência para vídeo API reference

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.
O código de exemplo neste tópico aplica-se à região de Singapura.
O 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

Esta 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
  • Singapore
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
  • Singapore
  • Beijing
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Substitua {WorkspaceId} pelo seu ID do workspace real.
  • 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)
  • Referência de imagem única (imagem multi-painel)
É 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
            }
        }'
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.
Se 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:
  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 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:
  1. URL pública:
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:
  1. URL pública:
parameters object (Optional)Os parâmetros de processamento de vídeo, como a resolução do vídeo.

Propriedades

resolution string (Optional)
A 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)
A 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_extendboolean (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
  • 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 objectAs informaçõ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 único da solicitação para rastreamento e solução de problemas.
code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.
message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.

Etapa 2: Consultar o resultado pelo ID da tarefa

  • Beijing
  • Singapore
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Singapore
  • Beijing
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Substitua {WorkspaceId} pelo seu ID do workspace real.
  • Recomendação de consulta periódica: A geração de vídeo leva vários minutos. 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
  • 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": "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"
    }
}
outputobjectAs informações de saída da tarefa.

Propriedades

task_id string (Required)O ID da tarefa.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.
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.video_url stringURL do vídeo gerado. Retornada apenas quando task_status é SUCCEEDED.Válida por 24 horas. O vídeo está no formato MP4 com codificação H.264.orig_prompt stringO prompt de entrada original, correspondente ao parâmetro de solicitação prompt.code stringCódigo de erro. Retornado apenas para solicitações com falha. Consulte Códigos de erro.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.
usage objectEstatísticas de saída. Preenchido apenas para tarefas bem-sucedidas.

Propriedades

input_video_duration integerA duração do vídeo de entrada, em segundos.output_video_duration integerA duração do vídeo de saída, em segundos.duration integerA duração total do vídeo. O custo é calculado com base neste valor.Fórmula: duration = input_video_duration + output_video_duration.SR integerA categoria de resolução do vídeo gerado. Exemplo: 720.ratio stringA proporção do vídeo gerado. Exemplo: 16:9.video_count integerO número de vídeos gerados. O valor é sempre 1.
request_id stringIdentificador ú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

Requer 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
  • Singapore
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'
  • Singapore
  • Beijing
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
Substitua {WorkspaceId} pelo seu ID do workspace real.
  • Chamada síncrona
  • Chamada assí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"
    }
}

Java SDK

Certifique-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
  • Singapore
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
  • Singapore
  • Beijing
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
Substitua {WorkspaceId} pelo seu ID do workspace real.
  • Chamada síncrona
  • Chamada assí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": ""
}

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