Wan - Referência da API de imagem para vídeo com primeiro e último quadros (2.2) - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

O modelo Wan 2,2 gera um vídeo com transições suaves a partir de um primeiro quadro , um último quadro e um prompt de texto .

Documentos relacionados: Guia do usuário

Observações de uso

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

Selecione um modelo: Confirme a região onde o modelo está disponível.
Selecione uma URL: Escolha a URL do endpoint correspondente à sua região. Há suporte tanto para URLs HTTP quanto para URLs do DashScope SDK.
Configure sua chave de API: Selecione uma região, obtenha sua chave de API e defina-a como variável de ambiente.
Instale o SDK: Para fazer chamadas de API com o SDK, instale o DashScope SDK.

ObservaçãoOs exemplos de código neste tópico aplicam-se a 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, encontrado na página Workspace Details no console do Model Studio. O domínio existente permanece totalmente funcional.

Chamada HTTP

Como as tarefas de imagem para vídeo são operações de longa duração que geralmente levam de 1 a 5 minutos, a API utiliza chamada assíncrona. O processo envolve duas etapas principais: crie uma tarefa e consulte o resultado periodicamente.

Etapa 1: Crie uma tarefa

China (Pequim)

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

Singapura

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

Substitua WorkspaceId pelo seu ID do Workspace real.

Singapura

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

Substitua WorkspaceId pelo seu ID do Workspace real.

China (Pequim)

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

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, use consultas periódicas para recuperar o resultado.
Para orientações a iniciantes, consulte Chamar APIs com Postman ou cURL.

Parâmetros da solicitação

Primeiro e último quadros

Gera um vídeo com base em um primeiro quadro, um último quadro e um prompt.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
        -H 'X-DashScope-Async: enable' \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
        "model": "wan2.2-kf2v-flash",
        "input": {
            "first_frame_url": "https://wanx.alicdn.com/material/20250318/first_frame.png",
            "last_frame_url": "https://wanx.alicdn.com/material/20250318/last_frame.png",
            "prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view."
        },
        "parameters": {
            "resolution": "480P",
            "prompt_extend": true
        }
    }'

Prompt negativo

Use o parâmetro negative_prompt para excluir certos elementos, como pessoas, do vídeo gerado.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
        -H 'X-DashScope-Async: enable' \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
        "model": "wan2.1-kf2v-plus",
        "input": {
            "first_frame_url": "https://wanx.alicdn.com/material/20250318/first_frame.png",
            "last_frame_url": "https://wanx.alicdn.com/material/20250318/last_frame.png",
            "prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
            "negative_prompt": "people"
        },
        "parameters": {
            "resolution": "720P",
            "prompt_extend": true
        }
    }'

Cabeçalhos da solicitação

Content-Type string (Obrigatório)

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.

ImportanteSe este cabeçalho estiver ausente, o erro "current user api does not support synchronous calls" será retornado.

Corpo da solicitação

model string (Obrigatório)

Nome do modelo. Exemplo: wan2.2-kf2v-flash.

Para mais detalhes, consulte o console do Model Studio.

input object (Obrigatório)

Contém a entrada principal da tarefa, como o prompt.

Propriedades

prompt string (Opcional)

Prompt de texto. Suporta chinês e inglês. Comprimento máximo de 800 caracteres. Caracteres chineses e letras contam como um único caractere. Textos que excederem esse limite serão truncados.

Se houver mudanças significativas no assunto ou na cena entre o primeiro e o último quadros, recomendamos descrever o processo de transição, como movimento de câmera (por exemplo, "a câmera se move para a esquerda") ou movimento do assunto (por exemplo, "uma pessoa corre para frente").

Exemplo: "Um pequeno gato preto olha curiosamente para o céu. A câmera sobe gradualmente do nível dos olhos e finalmente captura seu olhar curioso de uma vista de cima para baixo."

Para dicas sobre como escrever prompts eficazes, consulte o Guia de prompts para texto para vídeo e imagem para vídeo.

negative_prompt string (Opcional)

Prompt negativo que descreve o conteúdo a ser excluído do vídeo, ajudando a restringir a saída.

Suporta chinês e inglês. Comprimento máximo de 500 caracteres. Textos que excederem esse limite serão truncados.

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

first_frame_url string (Obrigatório)

URL da imagem do primeiro quadro. A proporção de aspecto do vídeo de saída corresponderá à da imagem do primeiro quadro.

A URL deve ser um endereço publicamente acessível que suporte HTTP ou HTTPS.

Requisitos da imagem:

Formato: JPEG, JPG, PNG (sem suporte a canal alfa), BMP, WEBP.
Resolução: Largura e altura entre 240 e 8.000 pixels.
Tamanho do arquivo: Máximo de 10 MB.

last_frame_url string (Obrigatório)

URL da imagem do último quadro.

A URL deve ser um endereço publicamente acessível que suporte HTTP ou HTTPS.

Requisitos da imagem:

Formato: JPEG, JPG, PNG (sem suporte a canal alfa), BMP, WEBP.
Resolução: Largura e altura entre 240 e 8.000 pixels. A resolução do último quadro pode diferir da do primeiro quadro; resoluções ou proporções de aspecto não precisam corresponder.
Tamanho do arquivo: Máximo de 10 MB.

parameters object (Opcional)

Parâmetros de processamento de vídeo.

Propriedades

resolution string (Opcional)

ImportanteO parâmetro resolution afeta diretamente o custo. Para o mesmo modelo, a hierarquia de custos é 1080P > 720P > 480P. Confirme os preços no console do Model Studio antes de chamar a API.

Resolução do vídeo gerado. Este parâmetro ajusta a definição (total de pixels) sem alterar a proporção de aspecto.

O valor padrão e os valores disponíveis dependem do parâmetro model, conforme descrito abaixo:

wan2.2-kf2v-flash: Valores possíveis: 480P, 720P e 1080P. Valor padrão: 720P.
wan2.1-kf2v-plus: Único valor possível: 720P. Valor padrão: 720P.

Exemplo: 720P

duration integer (Opcional)

ImportanteO parâmetro duration afeta diretamente o custo, cobrado por segundo. Confirme os preços no console do Model Studio antes de chamar a API.

Valor fixo em 5.

prompt_extendbool (Opcional)

Defina se a reescrita de prompt deve ser ativada. Quando ativado, um modelo de linguagem grande (LLM) reescreve inteligentemente o prompt de entrada. Isso pode melhorar significativamente os resultados para prompts curtos, mas aumenta a latência.

true: Valor padrão. Ativa a reescrita de prompt.
false: Desativa a reescrita de prompt.

Exemplo: true

watermark bool (Opcional)

Defina se uma marca d'água com o texto "AI-generated" deve ser adicionada ao canto inferior direito do vídeo.

false: Valor padrão. Não adiciona marca d'água.
true: Adiciona marca d'água.

Exemplo: false

seed integer (Opcional)

A semente de número aleatório deve ser um inteiro no intervalo [0, 2147483647].

Se não 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 da 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` ID da tarefa. Válido para consultas por 24 horas. task_status `string` 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

China (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.

China (Pequim)

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

Observação

Recomendação de consulta periódica: A geração de vídeo leva vários minutos. Use um mecanismo de consulta periódica com 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 resultado da tarefa Substitua `86ecf553-d340-4e21-xxxxxxxxx` pelo seu `task_id` real. As chaves de API diferem por região. Para mais informações, consulte Obter uma chave de API. Se você usar um modelo na região China (Pequim), substitua `base_url` por `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx`, onde WorkspaceId é o ID real do seu workspace. `curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
Cabeçalhos da solicitação
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) ID da tarefa.

Parâmetros da resposta	Tarefa bem-sucedida As URLs de vídeo são válidas apenas por 24 horas e depois removidas automaticamente. Salve os vídeos gerados prontamente. { "request_id": "ec016349-6b14-9ad6-8009-xxxxxx", "output": { "task_id": "3f21a745-9f4b-4588-b643-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2025-04-18 10:36:58.394", "scheduled_time": "2025-04-18 10:37:13.802", "end_time": "2025-04-18 10:45:23.004", "video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxx", "orig_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.", "actual_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view. The cat's yellow eyes are bright and expressive, its fur is smooth, and its whiskers are clearly visible. The background is a simple light-colored wall, highlighting the cat's black silhouette. A close-up shot emphasizes the changes in the cat's expression and the details of its eyes." }, "usage": { "video_duration": 5, "video_count": 1, "SR": 480 } } Tarefa falhou Quando uma tarefa falha, `task_status` é FAILED com um código de erro e uma 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" } }`
output`object` Informações de saída da tarefa. Propriedades task_id `string` ID da tarefa. Válido para consultas por 24 horas. task_status `string` 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 inicial da consulta 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 execute a tarefa novamente. submit_time `string` Horário de envio da tarefa. O horário está em UTC+8 e o formato é AAAA-MM-DD HH:mm:ss.SSS. scheduled_time `string` Horário de execução da tarefa. O horário está em UTC+8 e o formato é AAAA-MM-DD HH:mm:ss.SSS. end_time `string` Horário de conclusão da tarefa. O horário está em UTC+8 e o formato é AAAA-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` Prompt de entrada original, correspondente ao parâmetro de solicitação `prompt`. actual_prompt `string` Prompt otimizado usado quando a reescrita de prompt está ativada. Não retornado quando desativado. 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 da tarefa. Apenas tarefas bem-sucedidas são cobradas. Propriedades video_duration `integer` Duração do vídeo gerado em segundos, sempre 5. Fórmula de cobrança: Custo = Segundos de vídeo × Preço unitário. video_count `integer` Número de vídeos gerados. Valor fixo em 1. video_ratio `string` Valor retornado atualmente apenas pelo modelo 2,1. Proporção de aspecto do vídeo gerado, fixa em `standard`. SR `integer` Valor retornado atualmente apenas pelo modelo 2,2. Nível de resolução do vídeo gerado. Valores possíveis: `480`, `720` e `1080`.
request_id `string` Identificador único da solicitação para rastreamento e solução de problemas.

Chamadas do DashScope SDK

Os nomes dos parâmetros do SDK são amplamente consistentes com a API HTTP, e a estrutura segue as convenções de cada linguagem de programação.

Como as tarefas de imagem para vídeo são de longa duração (geralmente 1–5 minutos), o SDK lida internamente com as chamadas HTTP assíncronas, suportando métodos síncronos e assíncronos.

O tempo real de processamento depende do número de tarefas na fila e do desempenho do serviço. Aguarde.

Chamadas do SDK Python

ImportanteAntes de execute o código abaixo, certifique-se de que a versão do DashScope Python SDK seja no mínimo 2.0.1.

Versões anteriores podem gerar erros como "url error, please check url!". Consulte Instale SDK para atualize.

Defina a region com base na região do modelo (passada ao construir o Client; o valor de region varia conforme a região):

Pequim

region="cn-beijing"

Singapura

region="ap-southeast-1"

Substitua WorkspaceId pelo seu ID do Workspace real.

Singapura

region="ap-southeast-1"

Substitua WorkspaceId pelo seu ID do Workspace real.

Pequim

region="cn-beijing"

Código de exemplo

Chamada síncrona

Este exemplo demonstra três métodos de entrada de imagem: URL pública, codificação Base64 e caminho de arquivo local.

Exemplo de solicitação

Exemplo de resposta

A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.

{
    "status_code": 200,
    "request_id": "efa545b3-f95c-9e3a-a3b6-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?xxxxx",
        "submit_time": "2025-02-12 11:03:30.701",
        "scheduled_time": "2025-02-12 11:06:05.378",
        "end_time": "2025-02-12 11:12:18.853",
        "orig_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
        "actual_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view. The cat's fur is jet-black and glossy, its eyes are large and bright with golden pupils. It looks up with its ears pricked, appearing exceptionally focused. After the camera moves up, the cat turns to face the camera, its eyes filled with curiosity and alertness. The background is simple, highlighting the cat's detailed features. A close-up shot with soft, natural light."
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Chamada assíncrona

Este exemplo demonstra uma chamada assíncrona, que retorna imediatamente um ID de tarefa. Consulte o status da tarefa periodicamente ou aguarde a conclusão.

Exemplo de solicitação

Exemplo de resposta

Resposta após a criação da tarefa

{
    "status_code": 200,
    "request_id": "c86ff7ba-8377-917a-90ed-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
        "task_status": "PENDING",
        "video_url": ""
    },
    "usage": null
}

Exemplo de resposta para uma tarefa concluída

A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.

{
    "status_code": 200,
    "request_id": "efa545b3-f95c-9e3a-a3b6-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?xxxxx",
        "submit_time": "2025-02-12 11:03:30.701",
        "scheduled_time": "2025-02-12 11:06:05.378",
        "end_time": "2025-02-12 11:12:18.853",
        "orig_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
        "actual_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view. The cat's fur is jet-black and glossy, its eyes are large and bright with golden pupils. It looks up with its ears pricked, appearing exceptionally focused. After the camera moves up, the cat turns to face the camera, its eyes filled with curiosity and alertness. The background is simple, highlighting the cat's detailed features. A close-up shot with soft, natural light."
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Chamada síncrona

Este exemplo demonstra uma chamada síncrona com dois métodos de entrada de imagem: URL pública e caminho de arquivo local.

Exemplo de solicitação

import os
import dashscope
from dashscope.v2 import DashScopeError

# A configuração abaixo refere-se à região Singapura (ap-southeast-1). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key = "sk-xxx"
    # As API Keys variam conforme a região. Para obter uma API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

"""
Requirements:
    dashscope python SDK >= 2.0.1
Install/Upgrade the SDK:
    pip install -U dashscope
"""

# ========== Métodos de entrada de imagem (escolha um) ==========
# [Método 1] Usar uma URL de imagem pública
first_frame_url = "https://wanx.alicdn.com/material/20250318/first_frame.png"
last_frame_url = "https://wanx.alicdn.com/material/20250318/last_frame.png"

# [Método 2] Usar um caminho de arquivo local (file:// + caminho do arquivo)
# Caminho absoluto:
# first_frame_url = "file://" + "/path/to/your/first_frame.png"  # Linux/macOS
# last_frame_url = "file://" + "C:/path/to/your/last_frame.png"  # Windows
# Ou um caminho relativo:
# first_frame_url = "file://" + "./first_frame.png"              # Use o seu caminho real.
# last_frame_url = "file://" + "./last_frame.png"                # Use o seu caminho real.

def sample_sync_call_kf2v():
    print('please wait...')
    # generate é uma chamada de uma etapa (envia a tarefa e aguarda a conclusão) e retorna um Job concluído
    # first_frame_url e last_frame_url são campos da seção input que não fazem parte da assinatura nomeada e são passados via extra_input
    try:
        job = client.videos.generate(model="wan2.2-kf2v-flash",
                                     prompt="Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
                                     extra_input={'first_frame_url': first_frame_url,
                                                  'last_frame_url': last_frame_url},
                                     resolution="720P",
                                     prompt_extend=True)
        print(job)
        print(job.video_url)
    except DashScopeError as e:
        print(f"Código de status HTTP: {e.status_code}")
        print(f"Código de erro: {e.code}")
        print(f"Mensagem de erro: {e.message}")
        print("Consulte a documentação: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_kf2v()

Exemplo de resposta

A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.

{
    "status_code": 200,
    "request_id": "a37fafc3-907c-96f3-95a6-5b2a8268a3fd",
    "code": null,
    "message": "",
    "output": {
        "task_id": "4dba0092-da13-42b2-afb1-0f7b8a0f4643",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.mp4?xxxxx",
        "submit_time": "2025-05-23 15:50:12.404",
        "scheduled_time": "2025-05-23 15:50:12.443",
        "end_time": "2025-05-23 15:54:56.502",
        "orig_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
        "actual_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view. The cat's yellow eyes are bright and expressive, its ears are pricked, and its whiskers are clearly visible. The background is a simple, light-colored wall that highlights the cat's black fur and focused expression. A close-up shot emphasizes the change in the cat's gaze and posture."
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Chamada assíncrona

Este exemplo demonstra uma chamada assíncrona, que retorna imediatamente um ID de tarefa. Consulte o status da tarefa periodicamente ou aguarde a conclusão.

Exemplo de solicitação

import os
import dashscope
from dashscope.v2 import DashScopeError

# A configuração abaixo refere-se à região Singapura (ap-southeast-1). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key = "sk-xxx"
    # As API Keys variam conforme a região. Para obter uma API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

"""
Requirements:
    dashscope python SDK >= 2.0.1
Install/Upgrade the SDK:
    pip install -U dashscope
"""

# ========== Métodos de entrada de imagem (escolha um) ==========
# [Método 1] Usar uma URL de imagem pública
first_frame_url = "https://wanx.alicdn.com/material/20250318/first_frame.png"
last_frame_url = "https://wanx.alicdn.com/material/20250318/last_frame.png"

# [Método 2] Usar um caminho de arquivo local (file:// + caminho do arquivo)
# Caminho absoluto:
# first_frame_url = "file://" + "/path/to/your/first_frame.png"  # Linux/macOS
# last_frame_url = "file://" + "C:/path/to/your/last_frame.png"  # Windows
# Ou um caminho relativo:
# first_frame_url = "file://" + "./first_frame.png"              # Use o seu caminho real.
# last_frame_url = "file://" + "./last_frame.png"                # Use o seu caminho real.

def sample_async_call_kf2v():
    # Chamada assíncrona, que retorna um task_id
    # first_frame_url e last_frame_url são campos da seção input que não fazem parte da assinatura nomeada e são passados via extra_input
    try:
        job = client.videos.jobs.create(model="wan2.2-kf2v-flash",
                                        prompt="Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
                                        extra_input={'first_frame_url': first_frame_url,
                                                     'last_frame_url': last_frame_url},
                                        resolution="720P",
                                        prompt_extend=True)
        print(job)
        print("task_id: %s" % job.task_id)
    except DashScopeError as e:
        print(f"Código de status HTTP: {e.status_code}")
        print(f"Código de erro: {e.code}")
        print(f"Mensagem de erro: {e.message}")
        print("Consulte a documentação: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
        return

    # Consulte as informações da tarefa assíncrona, incluindo o status da tarefa
    try:
        snapshot = client.videos.jobs.fetch(job.task_id)
        print(snapshot.status)  # verifique o status da tarefa
    except DashScopeError as e:
        print(f"Código de status HTTP: {e.status_code}")
        print(f"Código de erro: {e.code}")
        print(f"Mensagem de erro: {e.message}")
        print("Consulte a documentação: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

    # Aguarde a conclusão da tarefa assíncrona (sondagem com backoff exponencial, orçamento total padrão de 24 horas)
    try:
        done = client.videos.jobs.wait(job)
        print(done)
        print(done.video_url)
    except DashScopeError as e:
        print(f"Código de status HTTP: {e.status_code}")
        print(f"Código de erro: {e.code}")
        print(f"Mensagem de erro: {e.message}")
        print("Consulte a documentação: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call_kf2v()

Exemplo de resposta

Resposta após a criação da tarefa

{
    "status_code": 200,
    "request_id": "c86ff7ba-8377-917a-90ed-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
        "task_status": "PENDING",
        "video_url": ""
    },
    "usage": null
}

Exemplo de resposta para uma tarefa concluída

A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.

{
    "status_code": 200,
    "request_id": "efa545b3-f95c-9e3a-a3b6-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?xxxxx",
        "submit_time": "2025-02-12 11:03:30.701",
        "scheduled_time": "2025-02-12 11:06:05.378",
        "end_time": "2025-02-12 11:12:18.853",
        "orig_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.",
        "actual_prompt": "Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view. The cat's fur is jet-black and glossy, its eyes are large and bright with golden pupils. It looks up with its ears pricked, appearing exceptionally focused. After the camera moves up, the cat turns to face the camera, its eyes filled with curiosity and alertness. The background is simple, highlighting the cat's detailed features. A close-up shot with soft, natural light."
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Chamadas do SDK Java

ImportanteAntes de execute o código abaixo, certifique-se de que a versão do DashScope Java SDK seja no mínimo 2.20.9.

Versões anteriores podem gerar erros como "url error, please check url!". Consulte Instale SDK para atualize.

Código de exemplo

Chamada síncrona

Este exemplo demonstra uma chamada síncrona e suporta três métodos de entrada de imagem: URL pública, codificação Base64 e caminho de arquivo local.

Exemplo de solicitação

Exemplo de resposta

A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.

{
    "request_id": "e6bb4517-c073-9c10-b748-dedb8c11bb41",
    "output": {
        "task_id": "984784fe-83c1-4fc4-88c7-52c2c1fa92a2",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.mp4?xxxxx"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Chamada assíncrona

Este exemplo demonstra uma chamada assíncrona, que retorna imediatamente um ID de tarefa. Consulte o status da tarefa periodicamente ou aguarde a conclusão.

Exemplo de solicitação

Exemplo de resposta

Resposta após a criação da tarefa

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

Exemplo de resposta para uma tarefa concluída

A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.

{
    "request_id": "1625235c-c13e-93ec-aff7-xxxxxxxx",
    "output": {
        "task_id": "464a5e46-79a6-46fd-9823-xxxxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?xxxxxx"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Chamada síncrona

Este exemplo demonstra uma chamada síncrona com dois métodos de entrada de imagem: URL pública e caminho de arquivo local.

Exemplo de solicitação

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

// DashScope SDK >= 2.20.1
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.HashMap;
import java.util.Map;

public class Kf2vSyncIntl {

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

    // Get the DashScope API key (which is your Model Studio API key) from an environment variable.
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Image input method (choose one):
     *
     * [Method 1] Public URL
     */
    static String firstFrameUrl = "https://wanx.alicdn.com/material/20250318/first_frame.png";
    static String lastFrameUrl = "https://wanx.alicdn.com/material/20250318/last_frame.png";

     /**
     * [Method 2] Local file path (file://+absolute path or file:///+absolute path)
     */
    // static String firstFrameUrl = "file://" + "/your/path/to/first_frame.png";  // Linux/macOS
    // static String lastFrameUrl = "file:///" + "C:/path/to/your/img.png";        // Windows

    public static void syncCall() {

        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);
        parameters.put("resolution", "720P");

        VideoSynthesis videoSynthesis = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.2-kf2v-flash")
                        .prompt("Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.")
                        .firstFrameUrl(firstFrameUrl)
                        .lastFrameUrl(lastFrameUrl)
                        .parameters(parameters)
                        .build();
        VideoSynthesisResult result = null;
        try {
            // Making a synchronous call. This may take a moment.
            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 dentro desse período.

{
    "request_id": "e6bb4517-c073-9c10-b748-dedb8c11bb41",
    "output": {
        "task_id": "984784fe-83c1-4fc4-88c7-52c2c1fa92a2",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.mp4?xxxxx"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Chamada assíncrona

Este exemplo demonstra uma chamada assíncrona, que retorna imediatamente um ID de tarefa. Consulte o status da tarefa periodicamente ou aguarde a conclusão.

Exemplo de solicitação

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

// DashScope SDK >= 2.20.1
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.HashMap;
import java.util.Map;

public class Kf2vAsync {

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

    // Get the DashScope API key (which is your Model Studio API key) from an environment variable.
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Image input method (choose one):
     *
     * [Method 1] Public URL
     */
    static String firstFrameUrl = "https://wanx.alicdn.com/material/20250318/first_frame.png";
    static String lastFrameUrl = "https://wanx.alicdn.com/material/20250318/last_frame.png";

    /**
     * [Method 2] Local file path (file://+absolute path or file:///+absolute path)
     */
    // static String firstFrameUrl = "file://" + "/your/path/to/first_frame.png";   // Linux/macOS
    // static String lastFrameUrl = "file:///" + "C:/path/to/your/img.png";        // Windows

    public static void asyncCall(){

        // Set parameters.
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);
        parameters.put("resolution", "720P");

        VideoSynthesis videoSynthesis = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.2-kf2v-flash")
                        .prompt("Realistic style, a small black cat looks up at the sky curiously, the camera gradually rises from eye level, and finally captures its curious gaze from a top-down view.")
                        .firstFrameUrl(firstFrameUrl)
                        .lastFrameUrl(lastFrameUrl)
                        .parameters(parameters)
                        .build();
        VideoSynthesisResult result = null;
        try {
            // Making an asynchronous call.
            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

Resposta após a criação da tarefa

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

Exemplo de resposta para uma tarefa concluída

A video_url é válida por 24 horas. Baixe o vídeo dentro desse período.

{
    "request_id": "1625235c-c13e-93ec-aff7-xxxxxxxx",
    "output": {
        "task_id": "464a5e46-79a6-46fd-9823-xxxxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?xxxxxx"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Limitações

Retenção de dados: O task_id e a video_url são retidos por 24 horas. Após esse período, não podem ser consultados ou baixados.
Suporte a áudio: O serviço gera apenas vídeos silenciosos. Para gerar áudio, use a síntese de fala.
Moderação de Conteúdo: A Moderação de Conteúdo analisa todos os prompts de entrada, imagens e vídeos de saída. Se qualquer conteúdo violar as políticas de uso, o serviço retornará um erro "IPInfringementSuspect" ou "DataInspectionFailed". Para mais detalhes, consulte Códigos de erro.

Códigos de erro

Se uma chamada de modelo falhar, consulte Códigos de erro para solução de problemas.

FAQ

P: Como gerar uma proporção de aspecto específica?

R: A proporção de aspecto do vídeo de saída depende da imagem do primeiro quadro (first_frame_url). No entanto, não é possível garantir uma proporção exata (como 3:4 estrito), podendo haver pequenos desvios.

Por que a proporção de aspecto apresenta desvios?
O modelo usa a proporção de aspecto da imagem de entrada como base e calcula a resolução válida mais próxima com base no total de pixels da configuração de resolution selecionada. Como a largura e a altura do vídeo devem ser múltiplos de 16, o modelo faz pequenos ajustes na resolução final.
- Por exemplo, se você fornecer uma imagem de entrada de 750×1000 (proporção de 3:4 ou 0,75) e definir resolution como "720P" (visando aproximadamente 920.000 pixels), a saída real poderá ser 816×1104 (proporção de aproximadamente 0,739, com cerca de 900.000 pixels).
Recomendações:
- Imagem de Entrada: Para melhores resultados, use uma imagem de primeiro quadro que corresponda à proporção de aspecto desejada.
- Pós-processamento: Se uma proporção de aspecto estrita for necessária, use uma ferramenta de edição de vídeo para cortar o vídeo gerado ou adicionar barras pretas.

P: Como obtenho a lista de permissões de nomes de domínio para 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 configure uma lista de permissões de firewall para esta URL de download, observe: o armazenamento subjacente pode mudar dinamicamente. Este tópico não fornece uma lista fixa de permissões de nomes de domínio do OSS para evitar problemas de acesso causados por informações desatualizadas. Se 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.

Observações de uso

Chamada HTTP

Etapa 1: Crie uma tarefa

China (Pequim)

Singapura

Singapura

China (Pequim)

Parâmetros da solicitação

Primeiro e último quadros

Prompt negativo

Cabeçalhos da solicitação

Corpo da solicitação

Parâmetros da resposta

Resposta bem-sucedida

Resposta de erro

Etapa 2: Consultar o resultado

China (Pequim)

Singapura

Singapura

China (Pequim)

Parâmetros da solicitação

Consultar resultado da tarefa

Cabeçalhos da solicitação

Parâmetros de caminho

Parâmetros da resposta

Tarefa bem-sucedida

Tarefa falhou

Consulta de tarefa expirada

Chamadas do DashScope SDK

Chamadas do SDK Python

Pequim

Singapura

Singapura

Pequim

Código de exemplo

Chamada síncrona

Exemplo de solicitação

Exemplo de resposta

Chamada assíncrona

Exemplo de solicitação

Exemplo de resposta

Chamada síncrona

Exemplo de solicitação

Exemplo de resposta

Chamada assíncrona

Exemplo de solicitação

Exemplo de resposta

Chamadas do SDK Java

Código de exemplo

Chamada síncrona

Exemplo de solicitação

Exemplo de resposta

Chamada assíncrona

Exemplo de solicitação

Exemplo de resposta

Chamada síncrona

Exemplo de solicitação

Exemplo de resposta

Chamada assíncrona

Exemplo de solicitação

Exemplo de resposta

Limitações

Códigos de erro

FAQ

P: Como gerar uma proporção de aspecto específica?

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