Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Wan 2.7 - API de imagem para vídeo

Última atualização: Jul 02, 2026

O modelo de imagem para vídeo Wan 2.7 aceita entrada multimodal (texto, imagens, áudio e vídeo) e executa três tarefas: primeiro quadro para vídeo, primeiro e último quadro para vídeo e continuação de vídeo.

Referências: Guia do usuário

Nota

A nova API de imagem para vídeo (modelo wan2.7) oferece suporte a todas as três tarefas. A API de imagem para vídeo a partir do primeiro quadro anterior (wan2.6 e versões anteriores) suporta apenas a geração de vídeo a partir do primeiro quadro.

Disponibilidade

O modelo, a URL do endpoint e a chave de API devem pertencer à mesma região. Chamadas entre regiões falham.

Nota

Os códigos de exemplo neste tópico aplicam-se à região de Singapura.

Importante

O Model Studio lançou domínios específicos para workspaces nas regiões China (Pequim) e Singapura. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos a migração 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, encontrado na página Workspace Details no console do Model Studio. O domínio existente permanece totalmente funcional.

HTTP

Importante

Esta API utiliza o novo protocolo de imagem para vídeo e suporta apenas o modelo wan2.7.

As tarefas de imagem para vídeo geralmente levam de 1 a 5 minutos; portanto, a API usa invocação assíncrona. O fluxo de trabalho possui duas etapas: crie uma tarefa e, em seguida, consulte o resultado periodicamente.

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

Pequim

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Singapura

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.

Singapura

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.

Pequim

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Nota
  • 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

Geração de vídeo a partir do primeiro quadro

Gere um vídeo com base em uma imagem de primeiro quadro e áudio.

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-i2v-2026-04-25",
            "input": {
                "prompt": "A scene of urban fantasy art. A dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He sings an English rap song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere full of high energy and amazing detail. The audio of the video consists entirely of the rap, with no other dialogue or noise.",
                "media": [
                    {
                        "type": "first_frame",
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
                    },
                    {
                        "type": "driving_audio",
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"

                    }
                ]
            },
            "parameters": {
                "resolution": "720P",
                "duration": 10,
                "prompt_extend": true,
                "watermark": true
            }
        }'

Geração de vídeo a partir do primeiro e último quadros

Forneça um primeiro quadro e um último quadro 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-i2v-2026-04-25",
            "input": {
                "prompt": "Realistic style, a small black cat looks up at the sky curiously. The camera angle gradually rises from eye level, finally capturing its curious gaze from a top-down view.",
                "media": [
                    {
                        "type": "first_frame",
                        "url": "https://wanx.alicdn.com/material/20250318/first_frame.png"
                    },
                    {
                        "type": "last_frame",
                        "url": "https://wanx.alicdn.com/material/20250318/last_frame.png"
                    }
                ]
            },
            "parameters": {
                "resolution": "720P",
                "duration": 10,
                "prompt_extend": false,
                "watermark": true
            }
        }'

Continuação de vídeo

Gere conteúdo subsequente com base em um clipe de vídeo inicial.

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-i2v-2026-04-25",
            "input": {
                "prompt": "A girl takes a selfie in the mirror, then leaves with her backpack.",
                "media": [
                    {
                        "type": "first_clip",
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4"
                    }
                ]
            },
            "parameters": {
                "resolution": "720P",
                "duration": 10,
                "prompt_extend": true,
                "watermark": true
            }
        }'

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)

Ative o processamento assíncrono. Solicitações HTTP suportam apenas chamadas assíncronas. Deve ser enable.

Importante

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

model string (Obrigatório)

O nome do modelo. Para obter uma lista de modelos e seus preços, consulte Preços dos modelos.

Exemplo: wan2.7-i2v-2026-04-25.

input object (Obrigatório)

Informações básicas de entrada, incluindo o prompt.

Propriedades

prompt string (Opcional)

Prompt de texto que descreve os elementos e as características visuais do vídeo a ser gerado.

Há suporte para chinês e inglês. Até 5.000 caracteres.

Cada caractere chinês ou letra conta como um caractere. O texto que exceder o limite será truncado automaticamente.

Exemplo: Um gatinho corre na grama.

Para mais informações sobre como usar prompts, consulte o Guia de prompts para texto-para-vídeo/imagem-para-vídeo.

negative_prompt string (Opcional)

Descreve o conteúdo a ser excluído do vídeo.

Há suporte para chinês e inglês. Máximo de 500 caracteres. O texto que exceder o limite será truncado automaticamente.

Exemplo: baixa resolução, erro, melhor qualidade, baixa qualidade, deformado, dedos extras, proporções ruins.

media array (Obrigatório)

Materiais de referência (imagens, áudio e vídeo) para a geração de vídeo.

Cada elemento é um objeto de mídia com os campos type e url.

Combinações de recursos

Apenas as seguintes combinações de recursos são válidas. Combinações inválidas retornam um erro.

  • Geração de vídeo a partir do primeiro quadro:

    • Primeiro quadro: first_frame

    • Primeiro quadro + áudio: first_frame+driving_audio

  • Geração de vídeo a partir do primeiro e último quadros:

    • Primeiro quadro + último quadro: first_frame+last_frame

    • Primeiro quadro + último quadro + áudio: first_frame+last_frame+driving_audio

  • Continuação de vídeo:

    • Continuação do primeiro clipe de vídeo: first_clip

    • Continuação do primeiro clipe de vídeo + último quadro: first_clip+last_frame

Propriedades

type string (Obrigatório)

O tipo de recurso de mídia. Valores válidos:

  • first_frame

  • last_frame

  • driving_audio

  • first_clip

Limite: Cada type pode aparecer no máximo uma vez no array media. Por exemplo, você não pode fornecer dois recursos first_frame.

url string (Obrigatório)

A URL do recurso de mídia (imagem, áudio ou vídeo).

Fornecer uma imagem (type=first_frame ou last_frame)

URL ou dados codificados em Base64 para a imagem do primeiro ou último quadro.

Limites de imagem:

  • Formato: JPEG, JPG, PNG (canal alfa não suportado), BMP, WEBP.

  • Resolução: A largura e a altura devem estar no intervalo de [240, 8000] pixels.

  • Proporção: 1:8 a 8:1.

  • Tamanho do arquivo: até 20 MB.

Formatos de entrada suportados:

  1. URL pública:

    • Há suporte para os protocolos HTTP e HTTPS.

    • Exemplo: https://xxx/xxx.png.

  2. Uma string de imagem codificada em Base64:

    • Formato de dados: data:{MIME_type};base64,{base64_data}.

    • Exemplo: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (O exemplo foi truncado para fins de demonstração).

      Formato de dados codificados em Base64

      Formato: data:{MIME_type};base64,{base64_data} .

      • {base64_data}: A string codificada em Base64 do arquivo de imagem.

      • {MIME_type}: O tipo MIME (Multipurpose Internet Mail Extensions) da imagem, que deve corresponder ao formato do arquivo.

Fornecer áudio (type=driving_audio)

URL do arquivo de áudio.

  • Com áudio: O modelo o utiliza como fonte condutora para sincronia labial e tempo de ação.

  • Sem áudio: O modelo gera automaticamente música de fundo ou efeitos sonoros correspondentes.

Limites de áudio:

  • Formato: wav, mp3.

  • Duração: 2 s a 30 s.

  • Tamanho do arquivo: até 15 MB.

  • Truncamento: Se a duração do áudio exceder o valor de duration (por exemplo, 5 s), o áudio será truncado automaticamente para os primeiros 5 segundos, e o restante será descartado. Se a duração do áudio for menor que a duração do vídeo, a parte do vídeo que exceder a duração do áudio ficará silenciosa. Por exemplo, se o áudio tiver 3 s e o vídeo tiver 5 s, os primeiros 3 segundos do vídeo de saída terão som, e os últimos 2 segundos serão silenciosos.

Formatos de entrada suportados:

  1. URL pública:

    • Há suporte para os protocolos HTTP e HTTPS.

    • Exemplo: https://xxx/xxx.mp3.

Fornecer um vídeo (type=first_clip)

URL do arquivo de vídeo. O modelo gera uma continuação com base no conteúdo do vídeo. O parâmetro duration controla a duração total máxima da saída.

Por exemplo, se duration=15 e o vídeo de entrada tiver 3 s, o modelo gera uma continuação de 12 s. O vídeo final de saída terá 15 s e será faturado por 15 s.

Limites de vídeo:

  • Formato: mp4, mov.

  • Duração: 2 s a 10 s.

  • Resolução: A largura e a altura devem estar no intervalo de [240, 4096] pixels.

  • Proporção: 1:8 a 8:1.

  • Tamanho do arquivo: até 100 MB.

Formatos de entrada suportados:

  1. URL pública:

    • Há suporte para os protocolos HTTP e HTTPS.

    • Exemplo: https://xxx/xxx.mp4.

parameters object (Opcional)

Parâmetros de processamento de vídeo: resolução, duração, reescrita de prompt e marcas d'água.

Propriedades

resolution string (Opcional)

Importante

A resolução afeta diretamente o custo. Antes de chamar, verifique os Preços dos modelos.

Nível de resolução para o vídeo gerado. Controla a contagem total de pixels.

O modelo ajusta automaticamente o vídeo para uma contagem total de pixels próxima ao nível selecionado. A proporção da saída segue o material de entrada (primeiro quadro ou primeiro clipe de vídeo). Para detalhes, consulte as Perguntas frequentes.

Os valores válidos são 720P e 1080P. Padrão: 1080P.

duration integer (Opcional)

Importante

A duração afeta diretamente o custo. O faturamento é por segundo. Antes de chamar, verifique os Preços dos modelos.

Duração do vídeo gerado em segundos. O intervalo válido depende do modelo:

Valores válidos: um número inteiro de 2 a 15. Padrão: 5.

prompt_extend boolean (Opcional)

Indica se a reescrita de prompt deve ser ativada. Quando ativado, um modelo reescreve o prompt de entrada para melhorar os resultados em prompts curtos, mas aumenta o tempo de processamento.

  • true (padrão)

  • false

watermark boolean (Opcional)

Indica se deve ser adicionada uma marca d'água "AI Generated" no canto inferior direito do vídeo.

  • false (padrão)

  • true

seed integer (Opcional)

A semente de número aleatório deve ser um número 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

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 exclusivo 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

Pequim

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Singapura

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

Substitua WorkspaceId pelo seu ID do Workspace real.

Singapura

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

Substitua WorkspaceId pelo seu ID do Workspace real.

Pequim

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Nota
  • Recomendação de consulta periódica: 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 um 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 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"
Cabeçalhos

Authorization string (Obrigatório)

Autentica a solicitação com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.

Parâmetros de caminho

task_id string (Obrigatório)

O ID da tarefa.

Parâmetros de resposta

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": "2ca1c497-f9e0-449d-9a3f-xxxxxx",
    "output": {
        "task_id": "af6efbc0-4bef-4194-8246-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-25 11:07:28.590",
        "scheduled_time": "2025-09-25 11:07:35.349",
        "end_time": "2025-09-25 11:17:11.650",
        "orig_prompt": "A scene of urban fantasy art. A dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He sings an English rap song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere full of high energy and amazing detail. The audio of the video consists entirely of his rap, with no other dialogue or noise.",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 15,
        "input_video_duration": 0,
        "output_video_duration": 15,
        "video_count": 1,
        "SR": 720
    }
}

Tarefa falhou

Quando uma tarefa falha, task_status é FAILED com um código e mensagem de erro. 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"
        }
    }

output object

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.

Transições de estado durante a consulta periódica:

  • PENDING → RUNNING → SUCCEEDED ou FAILED.

  • O status da consulta inicial geralmente é PENDING ou RUNNING.

  • Quando o status muda para SUCCEEDED, a resposta contém a URL do vídeo gerado.

  • Se o status for FAILED, verifique a mensagem de erro e tente executar a tarefa novamente.

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 uso. Calculadas apenas para tarefas bem-sucedidas.

Propriedades

input_video_duration integer

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

output_video_duration integer

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

duration integer

Duração total do vídeo usada para faturamento.

SR integer

Resolução do vídeo de saída. Exemplo: 720.

video_count integer

Número de vídeos de saída. Fixo em 1.

request_id string

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

DashScope SDK

Os nomes dos parâmetros do SDK correspondem aos da API HTTP. A estrutura dos parâmetros é encapsulada com base nas convenções da linguagem.

As tarefas de imagem para vídeo geralmente levam de 1 a 5 minutos. O SDK encapsula o processo de invocação assíncrona HTTP e suporta chamadas síncronas e assíncronas.

O tempo real de processamento depende da fila de tarefas e da carga do serviço. Aguarde o resultado.

Python SDK

Importante

Certifique-se de que a versão do DashScope Python SDK seja igual ou superior a 1.25.16 antes de executar o código abaixo.

Se a versão for muito antiga, erros como "url error, please check url!" podem ocorrer. Para mais informações, consulte Instalar SDK para atualizá-lo.

Defina dashscope.base_http_api_url com base na região do modelo:

Pequim

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

Singapura

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

Substitua WorkspaceId pelo seu ID do Workspace real.

Singapura

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

Substitua WorkspaceId pelo seu ID do Workspace real.

Pequim

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

Chamada síncrona

Exemplo de solicitação
# -*- coding: utf-8 -*-
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# This is the URL for the Singapore region. The URL varies by region. For more information, see https://www.alibabacloud.com/help/en/model-studio/image-to-video-general-api-reference
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# If you have not configured the environment variable, replace the following line with: api_key="sk-xxx"
# API keys vary by region. For more information, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

media = [
    {
        "type": "first_frame",
        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
    },
    {
        "type": "driving_audio",
        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
    }
]

def sample_sync_call():
    print('----Synchronous call, please wait a moment----')
    rsp = VideoSynthesis.call(
        api_key=api_key,
        model="wan2.7-i2v-2026-04-25",
        media=media,
        resolution="720P",
        duration=10,
        watermark=True,
        prompt="An urban fantasy art scene featuring a dynamic graffiti character. A boy made of spray paint comes to life on a concrete wall. He sings an English rap song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night, lit by a single street lamp. This creates a cinematic atmosphere with high energy and amazing detail. The video's audio consists entirely of the rap, with no other dialogue or noise.",
    )
    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()
Exemplo de resposta
A video_url é válida por 24 horas. Baixe o vídeo prontamente.
{
    "status_code": 200,
    "request_id": "ac5faf37-ddfa-9720-a0c5-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "b97c6d86-ad73-4bb7-80ff-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-13 10:45:47.597",
        "scheduled_time": "2026-04-13 10:45:56.342",
        "end_time": "2026-04-13 10:47:26.273",
        "orig_prompt": "An urban fantasy art scene. A dynamic graffiti character. A boy made of spray paint comes to life on a concrete wall. He performs a fast-paced English rap song while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere with high energy and incredible detail. The audio consists solely of the rap, with no other dialogue or background noise."
    },
    "usage": {
        "video_count": 1,
        "duration": 10,
        "input_video_duration": 0,
        "output_video_duration": 10,
        "SR": 720
    }
}

Chamada assíncrona

Exemplo de solicitação
# -*- coding: utf-8 -*-
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# This is the URL for the Singapore region. The URL varies by region. To obtain the URL for your region, see https://www.alibabacloud.com/help/en/model-studio/image-to-video-general-api-reference
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# If the environment variable is not set, replace the following line with: api_key="sk-xxx"
# API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

media = [
    {
        "type": "first_frame",
        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
    },
    {
        "type": "driving_audio",
        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
    }
]

def sample_async_call():
    # Submit an asynchronous task. Information about the task is returned immediately.
    rsp = VideoSynthesis.async_call(
        api_key=api_key,
        model="wan2.7-i2v-2026-04-25",
        media=media,
        resolution="720P",
        duration=10,
        watermark=True,
        prompt="A scene of urban fantasy art. A dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He sings an English rap song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere full of high energy and amazing detail. The audio of the video consists entirely of the rap, with no other dialogue or noise.",
    )
    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))

    # Query the task status.
    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 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()
Exemplo de resposta
  1. Exemplo de resposta para criação de uma 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
    }
  2. Exemplo de resposta para consulta do resultado de uma tarefa

    A video_url é válida por 24 horas. Baixe o vídeo prontamente.
    {
        "status_code": 200,
        "request_id": "ac5faf37-ddfa-9720-a0c5-xxxxxx",
        "code": null,
        "message": "",
        "output": {
            "task_id": "b97c6d86-ad73-4bb7-80ff-xxxxxx",
            "task_status": "SUCCEEDED",
            "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
            "submit_time": "2026-04-13 10:45:47.597",
            "scheduled_time": "2026-04-13 10:45:56.342",
            "end_time": "2026-04-13 10:47:26.273",
            "orig_prompt": "An urban fantasy art scene. A dynamic graffiti character. A boy made of spray paint comes to life on a concrete wall. He performs a fast-paced English rap song while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere with high energy and incredible detail. The audio consists solely of the rap, with no other dialogue or background noise."
        },
        "usage": {
            "video_count": 1,
            "duration": 10,
            "input_video_duration": 0,
            "output_video_duration": 10,
            "SR": 720
        }
    }

Java SDK

Importante

Certifique-se de que a versão do DashScope Java SDK seja igual ou superior a 2.22.14 antes de executar o código abaixo.

Se a versão for muito antiga, erros como "url error, please check url!" podem ocorrer. Para mais informações, consulte Instalar SDK para atualizá-lo.

Defina Constants.baseHttpApiUrl com base na região do modelo:

Pequim

Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1"

Singapura

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

Substitua WorkspaceId pelo seu ID do Workspace real.

Singapura

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

Substitua WorkspaceId pelo seu ID do Workspace real.

Pequim

Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1"

Chamada síncrona

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

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.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

import java.util.ArrayList;
import java.util.List;

public class Image2Video {

    static {
        // This is the URL for the Singapore region. If you use a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If the environment variable is not configured, replace the following line with: apiKey="sk-xxx"
    // API keys are region-specific. To obtain an API key, visit: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void syncCall() {
        VideoSynthesis videoSynthesis = new VideoSynthesis();
        final String prompt = "A scene of urban fantasy art. A dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He sings an English rap song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere full of high energy and amazing detail. The audio of the video consists entirely of his rap, with no other dialogue or noise.";
        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/20250925/wpimhv/rap.png")
                    .type("first_frame")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3")
                    .type("driving_audio")
                    .build());
        }};
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-i2v-2026-04-25")
                        .prompt(prompt)
                        .media(media)
                        .watermark(true)
                        .duration(10)
                        .resolution("720P")
                        .build();
        VideoSynthesisResult result = null;
        try {
            System.out.println("---Sync call, please wait...----");
            result = videoSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        } catch (InputRequiredException e) {
            throw new RuntimeException(e);
        }
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        syncCall();
    }
}
Exemplo de resposta
A video_url é válida por 24 horas. Baixe o vídeo prontamente.
{
    "request_id": "78178b55-8399-9823-8173-xxxxxx",
    "output": {
        "task_id": "be457e1b-8a79-47ed-aeff-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "orig_prompt": "An urban fantasy art scene featuring a dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He rapidly sings an English rap song while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. A single street lamp provides the light, creating a high-energy cinematic atmosphere with incredible detail. The audio consists entirely of his rap, with no other dialogue or background noise.",
        "submit_time": "2026-04-13 10:57:36.795",
        "scheduled_time": "2026-04-13 10:57:46.280",
        "end_time": "2026-04-13 10:59:16.338"
    },
    "usage": {
        "video_count": 1,
        "duration": 10,
        "input_video_duration": 0,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Chamada assíncrona

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.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

import java.util.ArrayList;
import java.util.List;

public class Image2Video {

    static {
        // This is the URL for the Singapore region. If you use a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If the environment variable is not configured, replace the following line with: apiKey = "sk-xxx"
    // API keys are region-specific. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void asyncCall() {
        VideoSynthesis videoSynthesis = new VideoSynthesis();
        final String prompt = "A scene of urban fantasy art. A dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He sings an English rap song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere full of high energy and amazing detail. The audio of the video consists entirely of his rap, with no other dialogue or noise.";
        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/20250925/wpimhv/rap.png")
                    .type("first_frame")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3")
                    .type("driving_audio")
                    .build());
        }};
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-i2v-2026-04-25")
                        .prompt(prompt)
                        .media(media)
                        .watermark(true)
                        .duration(10)
                        .resolution("720P")
                        .build();
        VideoSynthesisResult result = null;
        try {
            System.out.println("--- Starting the asynchronous call. Please wait... ---");
            result = videoSynthesis.asyncCall(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        } catch (InputRequiredException e) {
            throw new RuntimeException(e);
        }
        System.out.println(JsonUtils.toJson(result));

        String taskId = result.getOutput().getTaskId();
        System.out.println("taskId=" + taskId);

        try {
            result = videoSynthesis.wait(taskId, apiKey);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
        System.out.println(JsonUtils.toJson(result.getOutput()));
    }

    public static void main(String[] args) {
        asyncCall();
    }
}
Exemplo de resposta
  1. Exemplo de resposta para criação de uma tarefa

    {
        "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
        "output": {
            "task_id": "7277e20e-aa01-4709-xxxxxxxx",
            "task_status": "PENDING"
        }
    }
  2. Exemplo de resposta para consulta do resultado de uma tarefa

    A video_url é válida por 24 horas. Baixe o vídeo prontamente.
    {
        "request_id": "78178b55-8399-9823-8173-xxxxxx",
        "output": {
            "task_id": "be457e1b-8a79-47ed-aeff-xxxxxx",
            "task_status": "SUCCEEDED",
            "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
            "orig_prompt": "An urban fantasy art scene featuring a dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He rapidly sings an English rap song while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. A single street lamp provides the light, creating a high-energy cinematic atmosphere with incredible detail. The audio consists entirely of his rap, with no other dialogue or background noise.",
            "submit_time": "2026-04-13 10:57:36.795",
            "scheduled_time": "2026-04-13 10:57:46.280",
            "end_time": "2026-04-13 10:59:16.338"
        },
        "usage": {
            "video_count": 1,
            "duration": 10,
            "input_video_duration": 0,
            "output_video_duration": 10,
            "SR": 720
        },
        "status_code": 200,
        "code": "",
        "message": ""
    }

Códigos de erro

Se uma chamada de modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolver o problema.

Perguntas frequentes

P: Como gero um vídeo com uma proporção específica, como 3:4?

R: A proporção de saída é determinada pelo material de entrada (imagem do primeiro quadro ou primeiro clipe de vídeo), mas não há garantia de correspondência exata. Pode ocorrer um pequeno desvio.

O exemplo a seguir explica a lógica usando uma imagem de primeiro quadro como entrada:

  • Por que ocorre desvio?

    • Lógica de execução: O sistema usa a proporção da imagem de entrada como base, combinada com o total de pixels alvo para o nível de resolution. Como a codificação de vídeo exige que largura e altura sejam múltiplos de 16, o sistema ajusta a saída para a resolução válida mais próxima.

    • Exemplo de cálculo: Uma imagem de entrada de 750 x 1.000 pixels (proporção 3:4 = 0,75) com resolução "720P" (~920.000 pixels totais) produz uma saída de 816 x 1.104 pixels (proporção ~0,739, ~900.000 pixels totais).

  • Recomendações:

    • Controle de entrada: Use um primeiro quadro ou clipe de vídeo que corresponda à sua proporção alvo.

    • Pós-processamento: Para requisitos rigorosos de proporção, recorte o vídeo ou adicione barras pretas após a geração.

P: Como obtenho a lista de permissões de nomes de domínio para acesso ao armazenamento de vídeo?

R: Os vídeos gerados pelos modelos são armazenados no OSS. A API retorna uma URL pública temporária. Para configurar uma lista de permissões de firewall para esta URL de download, observe o seguinte: O armazenamento subjacente pode mudar dinamicamente. Este tópico não fornece uma lista fixa de permissões de domínio do OSS para evitar problemas de acesso causados por informações desatualizadas. Se você tiver requisitos de controle de segurança, entre em contato com o gerente da sua conta para obter a lista mais recente de nomes de domínio do OSS.