萬相Wan首尾幀生視頻API參考 - Alibaba Cloud Model Studio

萬相首尾幀生視頻模型基於首幀映像、尾幀映像和文本提示詞，產生一段平滑過渡的視頻。

相關文檔：使用指南

適用範圍

為確保調用成功，請務必保證模型、Endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。

選擇模型：確認模型所屬的地區。
選擇 URL：選擇對應的地區 Endpoint URL，支援HTTP URL或 DashScope SDK URL。
配置 API Key：選擇地區並擷取API Key與API Host，再配置API Key到環境變數（準備下線，併入配置 API Key）。
安裝 SDK：如需通過SDK進行調用，請安裝DashScope SDK。

說明

本文的範例程式碼適用於新加坡地區。

HTTP調用

由於圖生視頻任務耗時較長（通常為1-5分鐘），API採用非同步呼叫。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟，具體如下：

步驟1：建立任務擷取任務ID

新加坡

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

北京

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

說明

建立成功後，使用介面返回的 task_id 查詢結果，task_id 有效期間為 24 小時。請勿重複建立任務，輪詢擷取即可。
新手指引請參見Postman。

請求參數	首尾幀生視頻根據首幀、尾幀和prompt產生視頻。 curl --location 'https://dashscope-intl.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": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。" }, "parameters": { "resolution": "480P", "prompt_extend": true } }' 使用反向提示詞通過 negative_prompt 指定產生的視頻避免出現“人物”元素。 curl --location 'https://dashscope-intl.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": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。", "negative_prompt": "人物" }, "parameters": { "resolution": "720P", "prompt_extend": true } }'
要求標頭（Headers）
Content-Type `string` （必選）請求內容類型。此參數必須設定為`application/json`。
Authorization `string`（必選）請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值：Bearer sk-xxxx。
X-DashScope-Async `string` （必選）非同步處理配置參數。HTTP請求只支援非同步，必須設定為`enable`。重要缺少此要求標頭將報錯：“current user api does not support synchronous calls”。
請求體（Request Body）
model `string` （必選）模型名稱。樣本值：wan2.2-kf2v-flash。詳情參見模型列表與價格。
input `object` （必選）輸入的基本資料，如提示詞等。屬性 prompt `string` （可選）文本提示詞。支援中英文，長度不超過800個字元，每個漢字/字母佔一個字元，超過部分會自動截斷。如果首尾幀的主體和情境變化較大，建議描寫變化過程，例如運鏡過程（鏡頭向左移動）或者主體運動過程（人向前奔跑）。樣本值：一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。提示詞的提示請參見文生視頻/圖生視頻Prompt指南。 negative_prompt `string` （可選）反向提示詞，用來描述不希望在視頻畫面中看到的內容，可以對視頻畫面進行限制。支援中英文，長度不超過500個字元，超過部分會自動截斷。樣本值：低解析度、錯誤、最差品質、低品質、殘缺、多餘的手指、比例不良等。 first_frame_url `string` （必選）首幀映像URL。輸出視頻的寬高比與首幀映像保持一致。 URL 需為公網可訪問地址，支援 HTTP 或 HTTPS 協議。映像限制：映像格式：JPEG、JPG、PNG（不支援透明通道）、BMP、WEBP。映像解析度：映像的寬度和高度範圍為[360, 2000]，單位為像素。檔案大小：不超過10MB。 last_frame_url `string` （必選）尾幀映像URL。 URL 需為公網可訪問地址，支援 HTTP 或 HTTPS 協議。映像限制：映像格式：JPEG、JPG、PNG（不支援透明通道）、BMP、WEBP。映像解析度：映像的寬度和高度範圍為[360, 2000]，單位為像素。尾幀映像解析度可與首幀不同，無需強制對齊。檔案大小：不超過10MB。
parameters `object` （可選）視頻處理參數。屬性 resolution `string` （可選）重要 resolution直接影響費用，同一模型：1080P > 720P > 480P，調用前請確認模型價格。產生的視頻解析度檔位。僅用於調整視頻的清晰度（總像素），不改變視頻的寬高比，視頻寬高比將與首幀映像 first_frame_url 的寬高比保持一致。此參數的預設值和可用枚舉值依賴於 model 參數，規則如下： wan2.2-kf2v-flash：可選值：480P、720P、1080P。預設值為`720P`。 wan2.1-kf2v-plus：可選值：720P。預設值為`720P`。樣本值：720P。 duration `integer` （可選）重要 duration直接影響費用，按秒計費，調用前請確認模型價格。視頻產生時間長度，單位為秒。當前參數值固定為5，且不支援修改。模型將始終產生5秒時間長度的視頻。 prompt_extend `bool` （可選）是否開啟prompt智能改寫。開啟後使用大模型對輸入prompt進行智能改寫。對於較短的prompt產生效果提升明顯，但會增加耗時。 true：預設值，開啟智能改寫。 false：不開啟智能改寫。樣本值：true。 watermark `bool` （可選）是否添加浮水印標識，浮水印位於圖片右下角，文案為“AI產生”。 false：預設值，不添加浮水印。 true：添加浮水印。樣本值：false。 seed `integer` （可選）隨機數種子，取值範圍為`[0, 2147483647]`。未指定時，系統自動產生隨機種子。若需提升產生結果的可複現性，建議固定seed值。請注意，由於模型產生具有機率性，即使使用相同 seed，也不能保證每次產生結果完全一致。樣本值：12345。

響應參數	成功響應請儲存 task_id，用於查詢任務狀態與結果。 `{ "output": { "task_status": "PENDING", "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx" }, "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx" }` 異常響應建立任務失敗，請參見錯誤資訊進行解決。 `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` 任務輸出資訊。屬性 task_id `string` 任務ID。查詢有效期間24小時。 task_status `string` 任務狀態。枚舉值 PENDING：任務排隊中 RUNNING：任務處理中 SUCCEEDED：任務執行成功 FAILED：任務執行失敗 CANCELED：任務已取消 UNKNOWN：任務不存在或狀態未知
request_id `string` 請求唯一標識。可用於請求明細溯源和問題排查。
code `string` 請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。
message `string` 請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。

步驟2：根據任務ID查詢結果

新加坡

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

北京

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

說明

輪詢建議：視頻產生過程約需數分鐘，建議採用輪詢機制，並設定合理的查詢間隔（如 15 秒）來擷取結果。
任務狀態流轉：PENDING（排隊中）→ RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。
結果連結：任務成功後返回視頻連結，有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存（如阿里雲 OSS）。
task_id 有效期間：24小時，逾時後將無法查詢結果，介面將返回任務狀態為UNKNOWN。

請求參數	查詢任務結果請將`86ecf553-d340-4e21-xxxxxxxxx`替換為真實的task_id。各地區的API Key不同。擷取API Key與API Host。若使用北京地區的模型，需將base_url替換為https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx `curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值：Bearer sk-xxxx。
URL路徑參數（Path parameters）
task_id `string`（必選）任務ID。

響應參數	任務執行成功視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。 { "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": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。", "actual_prompt": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。小貓的黃色眼睛明亮有神，毛髮光滑，鬍鬚清晰可見。背景是簡單的淺色牆面，突顯小貓的黑色身影。近景特寫，強調小貓的表情變化和眼神細節。" }, "usage": { "video_duration": 5, "video_count": 1, "SR": 480 } } 任務執行失敗若任務執行失敗，task_status將置為 FAILED，並提供錯誤碼和資訊。請參見錯誤資訊進行解決。 `{ "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" } }` 任務查詢到期 task_id查詢有效期間為 24 小時，逾時後將無法查詢，返回以下報錯資訊。 `{ "request_id": "a4de7c32-7057-9f82-8581-xxxxxx", "output": { "task_id": "502a00b1-19d9-4839-a82f-xxxxxx", "task_status": "UNKNOWN" } }`
output `object` 任務輸出資訊。屬性 task_id `string` 任務ID。查詢有效期間24小時。 task_status `string` 任務狀態。枚舉值 PENDING：任務排隊中 RUNNING：任務處理中 SUCCEEDED：任務執行成功 FAILED：任務執行失敗 CANCELED：任務已取消 UNKNOWN：任務不存在或狀態未知輪詢過程中的狀態流轉： PENDING（排隊中） → RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。初次查詢狀態通常為 PENDING（排隊中）或 RUNNING（處理中）。當狀態變為 SUCCEEDED 時，響應中將包含產生的視頻url。若狀態為 FAILED，請檢查錯誤資訊並重試。 submit_time `string` 任務提交時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。 scheduled_time `string` 任務執行時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。 end_time `string` 任務完成時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。 video_url `string` 視頻URL。僅在 task_status 為 SUCCEEDED 時返回。連結有效期間24小時，可通過此URL下載視頻。視頻格式為MP4（H.264 編碼）。 orig_prompt `string` 原始輸入的prompt，對應請求參數`prompt`。 actual_prompt `string` 開啟 prompt 智能改寫後，返回實際使用的最佳化後 prompt。若未開啟該功能，則不返回此欄位。 code `string` 請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。 message `string` 請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。
usage `object` 輸出資訊統計。只對成功的結果計數。屬性 video_duration `integer` 產生視頻的時間長度，單位秒。枚舉值為5。計費公式：費用 = 視頻秒數 × 單價。 video_count `integer` 產生視頻的數量。固定為1。 video_ratio `string` 當前僅當2.1模型返回該值。產生視頻的比例，固定為standard。 SR `integer` 當前僅當2.2模型返回該值。產生視頻的解析度檔位，枚舉值為480、720、1080。
request_id `string` 請求唯一標識。可用於請求明細溯源和問題排查。

DashScope SDK調用

SDK 的參數命名與HTTP介面基本一致，參數結構根據語言特性進行封裝。

由於圖生視頻任務耗時較長（通常為1-5分鐘），SDK 在底層封裝了 HTTP 非同步呼叫流程，支援同步、非同步兩種調用方式。

具體耗時受限於排隊任務數和服務執行情況，請在擷取結果時耐心等待。

Python SDK調用

重要

請確保 DashScope Python SDK 版本不低於 1.23.8，再運行以下代碼。

若版本過低，可能會觸發 “url error, please check url!” 等錯誤。請參考安裝SDK進行更新。

根據模型所在地區設定 base_http_api_url:

新加坡

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

北京

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

範例程式碼

同步調用

本樣本展示同步調用方式，包括兩種映像輸入方式：公網URL、本地檔案路徑。

請求樣本

import os
from http import HTTPStatus
# dashscope sdk >= 1.23.4
from dashscope import VideoSynthesis
import dashscope

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

# 從環境變數中擷取 DashScope API Key（即阿里雲百鍊平台 API key）
api_key = os.getenv("DASHSCOPE_API_KEY")

# ========== 映像輸入方式（二選一）==========
# 【方式一】使用公網圖片 URL
first_frame_url = "https://wanx.alicdn.com/material/20250318/first_frame.png"
last_frame_url = "https://wanx.alicdn.com/material/20250318/last_frame.png"

# 【方式二】使用本地檔案路徑（file://+檔案路徑）
# 使用絕對路徑
# first_frame_url = "file://" + "/path/to/your/first_frame.png"  # Linux/macOS
# last_frame_url = "file://" + "C:/path/to/your/last_frame.png"  # Windows
# 或使用相對路徑
# first_frame_url = "file://" + "./first_frame.png"              # 以實際路徑為準
# last_frame_url = "file://" + "./last_frame.png"                # 以實際路徑為準

def sample_sync_call_kf2v():
    print('please wait...')
    rsp = VideoSynthesis.call(api_key=api_key,
                              model="wan2.2-kf2v-flash",
                              prompt="寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。",
                              first_frame_url=first_frame_url,
                              last_frame_url=last_frame_url,
                              resolution="720P",
                              prompt_extend=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    sample_sync_call_kf2v()

響應樣本

video_url 有效期間24小時，請及時下載視頻。

{
    "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": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。",
        "actual_prompt": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。小貓的黃色眼睛明亮有神，耳朵豎立，鬍鬚清晰可見。背景是簡潔的淺色牆面，突顯小貓的黑色毛髮和專註的表情。近景特寫，強調小貓的眼神變化和姿態。"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

非同步呼叫

本樣本展示非同步呼叫方式。該方式會立即返回任務ID，需要自行輪詢或等待任務完成。

請求樣本

import os
from http import HTTPStatus
# dashscope sdk >= 1.23.4
from dashscope import VideoSynthesis
import dashscope

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

# 從環境變數中擷取 DashScope API Key（即阿里雲百鍊平台 API key）
api_key = os.getenv("DASHSCOPE_API_KEY")

# ========== 映像輸入方式（二選一）==========
# 【方式一】使用公網圖片 URL
first_frame_url = "https://wanx.alicdn.com/material/20250318/first_frame.png"
last_frame_url = "https://wanx.alicdn.com/material/20250318/last_frame.png"

# 【方式二】使用本地檔案路徑（file://+檔案路徑）
# 使用絕對路徑
# first_frame_url = "file://" + "/path/to/your/first_frame.png"  # Linux/macOS
# last_frame_url = "file://" + "C:/path/to/your/last_frame.png"  # Windows
# 或使用相對路徑
# first_frame_url = "file://" + "./first_frame.png"              # 以實際路徑為準
# last_frame_url = "file://" + "./last_frame.png"                # 以實際路徑為準

def sample_async_call_kf2v():
    print('please wait...')
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                    model="wan2.2-kf2v-flash",
                                    prompt="寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。",
                                    first_frame_url=first_frame_url,
                                    last_frame_url=last_frame_url,
                                    resolution="720P",
                                    prompt_extend=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print("task_id: %s" % rsp.output.task_id)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

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

    # wait the task complete, will call fetch interval, and check it's in finished status.
    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_kf2v()

響應樣本

1、建立任務的響應樣本

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

2、查詢任務結果的響應樣本

video_url 有效期間24小時，請及時下載視頻。

{
    "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": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。",
        "actual_prompt": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。小貓毛髮烏黑光亮，眼睛大而明亮，瞳孔呈金黃色。它抬頭仰望，耳朵豎立，顯得格外專註。鏡頭上移後，小貓轉頭直視鏡頭，眼神中充滿好奇與警覺。背景簡潔，突出小貓的細節特徵。近景特寫，自然光線柔和。"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 5,
        "video_ratio": "standard"
    }
}

Java SDK調用

重要

請確保 DashScope Java SDK 版本不低於 2.20.9，再運行以下代碼。

若版本過低，可能會觸發 “url error, please check url!” 等錯誤。請參考安裝SDK進行更新。

範例程式碼

同步調用

本樣本展示同步調用方式，包括兩種映像輸入方式：公網URL、本地檔案路徑。

請求樣本

// 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://dashscope-intl.aliyuncs.com/api/v1";
    }

    // 從環境變數中擷取 DashScope API Key（即阿里雲百鍊平台 API Key）
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * 映像輸入方式（二選一）：
     *
     * 【方式一】公網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";

     /**
     * 【方式二】本地檔案路徑（file://+絕對路徑 or file:///+絕對路徑）
     */
    // 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("寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。")
                        .firstFrameUrl(firstFrameUrl)
                        .lastFrameUrl(lastFrameUrl)
                        .parameters(parameters)
                        .build();
        VideoSynthesisResult result = null;
        try {
            System.out.println("---sync call, please wait 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();
    }
}

響應樣本

video_url 有效期間24小時，請及時下載視頻。

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

非同步呼叫

本樣本展示非同步呼叫方式。該方式會立即返回任務ID，需要自行輪詢或等待任務完成。

請求樣本

// 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://dashscope-intl.aliyuncs.com/api/v1";
    }
    
    // 從環境變數中擷取 DashScope API Key（即阿里雲百鍊平台 API Key）
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * 映像輸入方式（二選一）
     *
     * 【方式一】公網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";

    /**
     * 【方式二】本地檔案路徑（file://+絕對路徑 or file:///+絕對路徑）
     */
    // 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(){

        // 設定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("寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。")
                        .firstFrameUrl(firstFrameUrl)
                        .lastFrameUrl(lastFrameUrl)
                        .parameters(parameters)
                        .build();
        VideoSynthesisResult result = null;
        try {
            System.out.println("---async call, please wait a moment----");
            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();
    }
}

響應樣本

1、建立任務的響應樣本

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

2、查詢任務結果的響應樣本

video_url 有效期間24小時，請及時下載視頻。

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

使用限制

資料時效：任務task_id和視頻video_url均只保留 24 小時，到期後將無法查詢或下載。
音頻支援：當前僅支援產生無聲視頻，不支援音訊輸出。如有需要，可通過語音合成產生音頻。
內容審核：輸入prompt 和映像、輸出視頻均會經過Alibaba Content Security Service審核，含違規內容將返回 “IPInfringementSuspect”或“DataInspectionFailed”錯誤，詳情請參見錯誤資訊。

錯誤碼

如果模型調用失敗並返回報錯資訊，請參見錯誤資訊進行解決。

常見問題

Q：如何產生特定寬高比（如3:4）的視頻？

A：輸出視頻的寬高比由輸入首幀映像（first_frame_url）決定，但無法保證精確比例（如嚴格3:4），會存在一定偏差。

為什麼會有偏差：模型會以您輸入映像的比例為基準，結合設定的解析度檔位（resolution）總像素，自動計算出最接近的合法解析度。由於要求視頻的長和寬必須是 16 的倍數，模型會對最終解析度做微調，因此無法保證輸出比例嚴格等於 3:4，但會非常接近。

例如：輸入映像750×1000（寬高比 3:4 = 0.75），並設定 resolution = "720P"（目標總像素約 92 萬），實際輸出816×1104（寬高比 ≈ 0.739，總像素約90萬）。

實踐建議：

輸入控制：盡量使用與目標比例一致的圖片作為首幀輸入。
後期處理：如果您對比例有嚴格要求，建議在視頻產生後，使用編輯工具進行簡單的裁剪或黑邊填充。

響應參數	任務執行成功視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。 { "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": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。", "actual_prompt": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。小貓的黃色眼睛明亮有神，毛髮光滑，鬍鬚清晰可見。背景是簡單的淺色牆面，突顯小貓的黑色身影。近景特寫，強調小貓的表情變化和眼神細節。" }, "usage": { "video_duration": 5, "video_count": 1, "SR": 480 } } 任務執行失敗若任務執行失敗，task_status將置為 FAILED，並提供錯誤碼和資訊。請參見錯誤資訊進行解決。 `{ "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" } }` 任務查詢到期 task_id查詢有效期間為 24 小時，逾時後將無法查詢，返回以下報錯資訊。 `{ "request_id": "a4de7c32-7057-9f82-8581-xxxxxx", "output": { "task_id": "502a00b1-19d9-4839-a82f-xxxxxx", "task_status": "UNKNOWN" } }`
output `object` 任務輸出資訊。屬性 task_id `string` 任務ID。查詢有效期間24小時。 task_status `string` 任務狀態。枚舉值 PENDING：任務排隊中 RUNNING：任務處理中 SUCCEEDED：任務執行成功 FAILED：任務執行失敗 CANCELED：任務已取消 UNKNOWN：任務不存在或狀態未知輪詢過程中的狀態流轉： PENDING（排隊中） → RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。初次查詢狀態通常為 PENDING（排隊中）或 RUNNING（處理中）。當狀態變為 SUCCEEDED 時，響應中將包含產生的視頻url。若狀態為 FAILED，請檢查錯誤資訊並重試。 submit_time `string` 任務提交時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。 scheduled_time `string` 任務執行時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。 end_time `string` 任務完成時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。 video_url `string` 視頻URL。僅在 task_status 為 SUCCEEDED 時返回。連結有效期間24小時，可通過此URL下載視頻。視頻格式為MP4（H.264 編碼）。 orig_prompt `string` 原始輸入的prompt，對應請求參數`prompt`。 actual_prompt `string` 開啟 prompt 智能改寫後，返回實際使用的最佳化後 prompt。若未開啟該功能，則不返回此欄位。 code `string` 請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。 message `string` 請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。
usage `object` 輸出資訊統計。只對成功的結果計數。屬性 video_duration `integer` 產生視頻的時間長度，單位秒。枚舉值為5。計費公式：費用 = 視頻秒數 × 單價。 video_count `integer` 產生視頻的數量。固定為1。 video_ratio `string` 當前僅當2.1模型返回該值。產生視頻的比例，固定為standard。 SR `integer` 當前僅當2.2模型返回該值。產生視頻的解析度檔位，枚舉值為480、720、1080。
request_id `string` 請求唯一標識。可用於請求明細溯源和問題排查。

適用範圍

HTTP調用

步驟1：建立任務擷取任務ID

新加坡

北京

請求參數

首尾幀生視頻

使用反向提示詞

要求標頭（Headers）

請求體（Request Body）

響應參數

成功響應

異常響應

步驟2：根據任務ID查詢結果

新加坡

北京

請求參數

查詢任務結果

要求標頭（Headers）

URL路徑參數（Path parameters）

響應參數

任務執行成功

任務執行失敗

任務查詢到期

DashScope SDK調用

Python SDK調用

新加坡

北京

範例程式碼

同步調用

請求樣本

響應樣本

非同步呼叫

請求樣本

響應樣本

Java SDK調用

範例程式碼

同步調用

請求樣本

響應樣本

非同步呼叫

請求樣本

響應樣本

使用限制

錯誤碼

常見問題

Q：如何產生特定寬高比（如3:4）的視頻？