Como chamar o modelo de imagem para vídeo Wan usando o primeiro e o último quadros - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

O modelo de imagem para vídeo Wan gera vídeos fluidos a partir de uma imagem do primeiro quadro, uma imagem do último quadro e um prompt de texto opcional.

Especificações de vídeo: Duração fixa de 5 segundos e resolução personalizada (480P/720P/1080P).
Capacidades adicionais: Reescrita de prompt e marca d'água.

Links rápidos: Referência da API | Guia de prompts

Primeiros passos

Prompt	Primeiro quadro	Último quadro	Vídeo de saída
Um monstro azul fofo com expressão levemente triste está na chuva. A câmera aproxima lentamente e para no momento em que ele olha para o céu.

Antes de chamar a API: Obtenha uma chave de API, defina-a como variável de ambiente e instale o DashScope SDK.

Python SDK

ImportanteÉ necessário ter o DashScope Python SDK ≥ 2.0.1 antes de executar o código abaixo. Versões mais antigas podem apresentar erros do tipo "url error, please check url!". Instale o SDK.

import os
import dashscope
from dashscope.v2 import DashScopeError

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região. Para os endpoints de cada região, consulte https://www.alibabacloud.com/help/model-studio/image-to-video-by-first-and-last-frame-api-reference
# As API Keys variam conforme a região. Para obter uma API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY", "YOUR_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

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 / 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="A cute blue monster with a slightly sad expression stands in the rain. The camera slowly zooms in and stops on the moment it looks up at the sky.",
                                 extra_input={'first_frame_url': "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260126/ixdxvt/wan-kf2v-blue-1.png",
                                              'last_frame_url': "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260126/nhtdrc/wan-kf2v-blue-2.png"},
                                 duration=5,  # Fixado em 5, não modificável
                                 prompt_extend=True,
                                 watermark=True)
    print(job)
    print("video_url:", job.video_url)
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

Java SDK

ImportanteÉ necessário ter o DashScope Java SDK ≥ 2.22.6 antes de executar o código abaixo. Versões mais antigas podem apresentar erros do tipo "url error, please check url!". Instale o SDK.

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;

public class Image2Video {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region. Get your URL: https://www.alibabacloud.com/help/en/model-studio/image-to-video-by-first-and-last-frame-api-reference
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not set an environment variable, replace the line below with: apiKey="sk-xxx"
    // API keys differ by region. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void image2video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.2-kf2v-flash")
                        .prompt("A cute blue monster with a slightly sad expression stands in the rain. The camera slowly zooms in and stops on the moment it looks up at the sky.")
                        .firstFrameUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260126/ixdxvt/wan-kf2v-blue-1.png")
                        .lastFrameUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260126/nhtdrc/wan-kf2v-blue-2.png")
                        .resolution("720P")
                        .promptExtend(true)
                        .watermark(true)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

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

curl

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

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://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260126/ixdxvt/wan-kf2v-blue-1.png",
        "last_frame_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260126/nhtdrc/wan-kf2v-blue-2.png",
        "prompt": "A cute blue monster with a slightly sad expression stands in the rain. The camera slowly zooms in and stops on the moment it looks up at the sky."
    },
    "parameters": {
        "resolution": "720P",
        "prompt_extend": true,
        "watermark": true
    }
}'

Etapa 2: Obtenha o resultado usando o ID da tarefa

Substitua {task_id} pelo valor de task_id retornado pela chamada de API anterior. O task_id permanece 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"

Saída de exemplo

A video_url expira após 24 horas. Baixe o vídeo imediatamente.

{
    "request_id": "c1209113-8437-424f-a386-xxxxxx",
    "output": {
        "task_id": "966cebcd-dedc-4962-af88-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
         ...
    },
    ...
}

Disponibilidade

Os modelos suportados variam conforme a região. Os recursos são isolados entre regiões. Para verificar os modelos suportados em cada região, consulte o console do Model Studio.
Ao fazer uma chamada, certifique-se de que seu modelo, URL do endpoint e chave de API pertençam à mesma região. Chamadas entre regiões falham.

ObservaçãoOs códigos de exemplo neste tópico aplicam-se à região de Singapore.

Capacidades principais

Gerar vídeo a partir do primeiro e último quadros

Modelos suportados: Todos os modelos.

Gera vídeos fluidos a partir das imagens do primeiro e do último quadros.

Parâmetros:

first_frame_url: Obrigatório. Forneça a imagem do primeiro quadro.
last_frame_url: Obrigatório. Forneça a imagem do último quadro.
prompt: Opcional (recomendado). Controla como o vídeo muda ao longo do tempo.

Prompt	Primeiro quadro	Último quadro	Vídeo de saída
Estilo realista. Um gatinho preto curioso olha para o céu. A câmera começa na altura dos olhos e sobe gradualmente até capturar o olhar curioso do gatinho de cima.

Python SDK

É necessário ter o DashScope Python SDK ≥ 2.0.1 . Atualize se necessário .

import os
import dashscope
from dashscope.v2 import DashScopeError

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região. Para os endpoints de cada região, consulte https://www.alibabacloud.com/help/model-studio/image-to-video-by-first-and-last-frame-api-reference
# As API Keys variam conforme a região. Para obter uma API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY", "YOUR_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def sample_async_call_kf2v():
    # Chamada assíncrona, que retorna um task_id
    # first_frame_url / 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 curious black kitten looks up at the sky. The camera starts at eye level and gradually rises until it captures the kitten’s curious gaze from above.",
                                        extra_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"},
                                        duration=5,  # Fixado em 5, não modificável
                                        prompt_extend=True,
                                        watermark=True)
        print(job)
        print("task_id: %s" % job.task_id)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
        return

    # Aguarde a conclusão da tarefa assíncrona (polling 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"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call_kf2v()

Java SDK

É necessário ter o DashScope Java SDK ≥ 2.22.6 . Atualize se necessário .

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;

public class Image2Video {

    static {
        // The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region. Get your URL: https://www.alibabacloud.com/help/en/model-studio/image-to-video-by-first-and-last-frame-api-reference
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not set an environment variable, replace the line below with: apiKey="sk-xxx"
    // API keys differ by region. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void image2video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.2-kf2v-flash")
                        .prompt("Realistic style. A curious black kitten looks up at the sky. The camera starts at eye level and gradually rises until it captures the kitten’s curious gaze from above.")
                        .firstFrameUrl("https://wanx.alicdn.com/material/20250318/first_frame.png")
                        .lastFrameUrl("https://wanx.alicdn.com/material/20250318/last_frame.png")
                        .resolution("720P")
                        .promptExtend(true)
                        .watermark(true)
                        .build();
        // Asynchronous call
        VideoSynthesisResult task = vs.asyncCall(param);
        System.out.println(JsonUtils.toJson(task));
        System.out.println("please wait...");

        // Get result
        VideoSynthesisResult result = vs.wait(task, apiKey);
        System.out.println(JsonUtils.toJson(result));
    }

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

curl

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

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 curious black kitten looks up at the sky. The camera starts at eye level and gradually rises until it captures the kitten’s curious gaze from above."
    },
    "parameters": {
        "resolution": "720P",
        "prompt_extend": true,
        "watermark": true
    }
}'

Etapa 2: Obtenha o resultado usando o ID da tarefa

Substitua {task_id} pelo valor de task_id retornado pela chamada de API anterior. O task_id permanece 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"

Imagem de entrada

Quantidade de imagens: Uma imagem para o primeiro quadro e uma para o último quadro.
Métodos de entrada: URL da imagem, caminho do arquivo local .

Método 1: URL da imagem (API HTTP e SDK) Recomendado

URL pública: HTTP ou HTTPS (por exemplo, https://xxxx/xxx.png).

Método 2: Caminho do arquivo local (apenas SDK)

Os requisitos de caminho variam conforme a linguagem:

Python SDK: Suporta caminhos absolutos e relativos.

Sistema operacional	Caminho do arquivo de entrada	Exemplo (caminho absoluto)	Exemplo (caminho relativo)
Linux / macOS	file://{caminho absoluto ou relativo}	file:///home/images/test.png	file://./images/test.png
Windows	file://{caminho absoluto ou relativo}	file://D:/images/test.png	file://./images/test.png

Java SDK: Suporta apenas caminhos absolutos.

Sistema operacional	Caminho do arquivo de entrada	Exemplo (caminho absoluto)
Linux / macOS	file://{caminho absoluto}	file:///home/images/test.png
Windows	file:///{caminho absoluto}	file:///D:/images/test.png

Código de exemplo: Múltiplos métodos de entrada de imagem

Python SDK

import os
import dashscope
from dashscope.v2 import DashScopeError

# A configuração abaixo refere-se à região Singapura. 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"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# ========== Métodos de entrada de imagem (escolha um) ==========
# [Método 1] Use uma URL pública de imagem
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] Use um caminho de arquivo local (file:// + caminho do arquivo)
# Use um 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 use um caminho relativo:
# first_frame_url = "file://" + "./first_frame.png"              # Use o caminho real
# last_frame_url = "file://" + "./last_frame.png"                # Use o 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 / 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"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_kf2v()

Java SDK

// 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();
    }
}

Vídeo de saída

Quantidade de vídeos: Um.
Especificações: Variam conforme o modelo. Consulte Especificações de vídeo.
Expiração da URL: 24 horas.
Dimensões: Determinadas pela imagem do primeiro quadro e pela configuração de resolution.
- O modelo preserva a proporção do primeiro quadro e ajusta a contagem total de pixels para o alvo. As dimensões de saída são ajustadas automaticamente para serem divisíveis por 16 (requisito de codificação).
- Exemplo: Uma entrada de 750×1000 (3:4) com resolution="720P" (alvo ≈920K pixels) pode resultar em uma saída de 816×1104 (proporção ≈0.739, ≈900K pixels, ambos divisíveis por 16).

Faturamento e limitação de taxa

Para detalhes sobre cota gratuita e preços, consulte Wanx-Image-to-Video-First-Last-Frame.
Para limitação de taxa do modelo, consulte Série Wanxiang.
Detalhes de faturamento:
- A entrada é gratuita. O faturamento da saída baseia-se nos segundos de vídeo gerados com sucesso.
- Chamadas com falha não geram cobranças e não consomem a cota gratuita.
- O recurso de imagem para vídeo também suporta planos de economia.

Referência da API

Imagem para vídeo - primeiro e último quadros - Referência da API

FAQ

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

R: A API não suporta controle direto da proporção — apenas de resolution.

O parâmetro resolution controla a contagem de pixels, não a proporção. O modelo preserva a proporção do primeiro quadro (first_frame_url) com pequenos ajustes para codificação (as dimensões devem ser múltiplos de 16). Para um vídeo 3:4, envie uma imagem de primeiro quadro na proporção 3:4.

Exemplo: Uma entrada de 750×1000 (3:4) com resolution="720P" (alvo ≈920K pixels) pode resultar em uma saída de 816×1104 (proporção ≈0.739, ≈900K pixels, ambos divisíveis por 16).

P: Por que recebo um erro “url error, please check url!” ao executar o código do SDK?

R: Certifique-se de que sua versão do SDK atenda ao requisito mínimo: DashScope Python SDK ≥ 2.0.1 ou DashScope Java SDK ≥ 2.22.6. Versões mais antigas podem apresentar erros do tipo "url error, please check url!". Atualize o SDK.