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

通義萬相首尾幀生視頻模型基於首幀映像、尾幀映像和文本提示詞，產生一段平滑過渡的視頻。支援的能力包括：

視頻規格：視頻時間長度固定為5秒，視頻解析度固定為720P。
智能 Prompt 最佳化：自動對輸入提示詞進行改寫，尤其對簡短提示詞效果提升顯著。
其他：可選擇是否添加“AI產生”浮水印。

說明

通義萬相官網的功能與API支援的能力可能存在差異。本文檔以API的實際能力為準，並會隨功能更新及時同步。

模型概覽

模型功能	輸入樣本			輸出視頻
模型功能	首幀圖片	尾幀圖片	提示詞	輸出視頻
首尾幀生視頻			寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。

模型名稱

模型簡介

輸出視頻格式

wan2.1-kf2v-plus

萬相2.1專業版（無聲視頻）

複雜運動，物理規律還原，畫面細膩

解析度檔位：720P

視頻時間長度：5秒

固定規格：30fps、MP4（H.264編碼）

說明

調用前，請查閱各地區支援的模型列表與價格。

前提條件

在調用前，需要準備工作：擷取與配置 API Key，再配置API Key到環境變數（準備下線，併入配置 API Key）。如果通過SDK進行調用，請安裝DashScope SDK。目前，該SDK已支援Python和Java。

重要

北京和新加坡地區擁有獨立的 API Key 與請求地址，不可混用，跨地區調用將導致鑒權失敗或服務報錯。

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 小時。請勿重複建立任務，輪詢擷取即可。

請求參數	首尾幀生視頻根據首幀、尾幀和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": "寫實風格，一隻黑色小貓好奇地看向天空，鏡頭從平視逐漸上升，最後俯拍它的好奇的眼神。" }, "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.1-kf2v-plus。詳情參見模型列表與價格。
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.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":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-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。以下為新加坡地區base_url，若使用北京地區的模型，需將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調用

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

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

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

Python SDK調用

Python SDK 支援兩種映像輸入方式：公網 URL、本地檔案路徑（絕對/相對），任選其一即可，具體參見輸入映像。

說明

推薦安裝最新版DashScope Python SDK，否則可能運行報錯：安裝或升級SDK。

同步調用

本樣本展示同步調用方式，包括兩種映像輸入方式：公網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.1-kf2v-plus",
                              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.1-kf2v-plus",
                                    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調用

Java SDK 支援兩種映像輸入方式：公網 URL、本地檔案路徑（絕對路徑），任選其一即可，具體參見輸入映像。

說明

推薦安裝最新版DashScope Java SDK，否則可能運行報錯：安裝或升級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.1-kf2v-plus")
                        .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.1-kf2v-plus")
                        .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和視頻url均只保留 24 小時，到期後將無法查詢或下載。
音頻支援：當前僅支援產生無聲視頻，不支援音訊輸出。如有需要，可通過語音合成產生音頻。
內容審核：輸入prompt 和映像、輸出視頻均會經過Alibaba Content Security Service審核，含違規內容將返回 “IPInfringementSuspect”或“DataInspectionFailed”錯誤，詳情請參見錯誤資訊。

關鍵參數說明

輸入映像

輸入映像first_frame_url和last_frame_url參數均支援以下方式傳入：

方式一：公網URL

一個公網可直接存取的地址，支援 HTTP/HTTPS。
樣本值：https://example.com/images/cat.png。

方式二：本地檔案路徑（僅限 SDK）

Python SDK：支援傳入檔案的絕對路徑和相對路徑。檔案路徑規則如下：

系統	傳入的檔案路徑	樣本（絕對路徑）	樣本（相對路徑）
Linux或macOS系統	file://{檔案的絕對路徑或相對路徑}	file:///home/images/test.png	file://./images/test.png
Windows系統	file://{檔案的絕對路徑或相對路徑}	file://D:/images/test.png	file://./images/test.png

Java SDK：僅支援傳入檔案的絕對路徑。檔案路徑規則如下：
系統
傳入的檔案路徑
樣本（絕對路徑）
Linux或macOS系統
file://{檔案的絕對路徑}
file:///home/images/test.png
Windows系統
file:///{檔案的絕對路徑}
file:///D:/images/test.png

計費和限流

模型免費額度和計費單價請參見模型列表與價格。
模型限流請參見通義萬相系列。
計費說明：
- 按成功產生的 視頻秒數 計費。僅當查詢結果介面返回task_status為SUCCEEDED 並成功產生視頻後，才會計費。
- 模型調用失敗或處理錯誤不產生任何費用，也不消耗免費額度。

錯誤碼

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

常見問題

視頻FAQ快速入口：常見問題。

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

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

工作原理：模型以輸入映像的寬高比為基準，然後根據 resolution 參數（如 480P / 720P / 1080P）將其適配到模型支援的合法解析度。由於輸出解析度需滿足技術要求（長和寬必須能被 16 整除），最終輸出的寬高比可能存在微小偏差（例如從 0.75 調整為 0.739），屬於正常現象。

樣本：輸入映像750×1000（寬高比 3:4 = 0.75），並設定 resolution = "720P"（目標總像素約 92 萬），實際輸出816×1104（寬高比 ≈ 0.739，總像素約90萬）。
請注意，resolution 參數主要用於控制視頻清晰度（總像素量），最終視頻寬高比仍以輸入映像為基礎，僅做必要微調。

最佳實務：若需嚴格符合目標寬高比，請使用與目標比例一致的輸入映像，並對輸出視頻進行後處理裁剪或填充。例如，使用視頻編輯工具將輸出視頻裁剪至目標比例，或添加黑邊、模糊背景進行填充適配。

響應參數	任務執行成功視頻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調用

同步調用

請求樣本

響應樣本

非同步呼叫

請求樣本

響應樣本

使用限制

關鍵參數說明

輸入映像

方式一：公網URL

方式二：本地檔案路徑（僅限 SDK）

計費和限流

錯誤碼

常見問題

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