適用範圍
為確保調用成功，請務必保證模型、Endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
HTTP調用
由於視頻編輯任務耗時較長（通常為1-5分鐘），API採用非同步呼叫。整個流程包含 "建立任務 -> 輪詢擷取" 兩個核心步驟，具體如下：
步驟1：建立任務擷取任務ID
新加坡
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
北京
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
請求參數 | 視頻編輯（指令+參考圖）curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "happyhorse-1.0-video-edit",
"input": {
"prompt": "讓視頻中的馬頭人身角色穿上圖片中的條紋毛衣",
"media": [
{
"type": "video",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4"
},
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260415/hynnff/wan-video-edit-clothes.webp"
}
]
},
"parameters": {
"resolution": "720P"
}
}'
|
要求標頭（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 （必選） 模型名稱。 固定值：happyhorse-1.0-video-edit。 |
input object （必選） 輸入的基本資料，包括待編輯的視頻、參考圖片和提示詞。 屬性 prompt string （必選） 文本提示詞。用來描述對視頻的編輯意圖，如風格轉換、本機覆寫等。 支援任何語言輸入，長度不超過5000個非中文字元或2500個中文字元，超過部分會自動截斷。 media array （必選） 媒體素材列表，用於指定待編輯的視頻和參考映像。 數組必須包含1個 video 類型元素；可選包含0~5個 reference_image 類型元素。 元素屬性 type string （必選） 媒體素材類型。可選值為： video：必傳。待編輯的視頻。
reference_image：可選。參考映像。
素材限制： url string （必選） 媒體素材的URL地址。 傳入的視訊（type=video） 待編輯的視頻URL，必須為公網可訪問的URL。 支援 HTTP 和 HTTPS 協議。 樣本值：https://xxx/xxx.mp4。
視頻限制： 傳入映像（type=reference_image） 參考映像的URL，必須為公網可訪問的URL。 支援 HTTP 或 HTTPS 協議。 樣本值：https://xxx/xxx.png。
映像限制： 格式：JPEG、JPG、PNG、WEBP。 解析度：寬高尺寸不小於300像素。 寬高比：1:2.5~2.5:1。 檔案大小：不超過10MB。
|
parameters object （可選） 視頻編輯參數。如設定視頻解析度等。 屬性 resolution string （可選） 產生視頻的解析度檔位。 可選值： watermark boolean （可選） 是否在產生的視頻上添加浮水印標識。浮水印位於視頻右下角，文案固定為“Happy Horse”。 true：預設值，添加浮水印。
false：不添加浮水印。
audio_setting string （可選） 聲音控制。 auto：預設值，由模型自行控制。
origin：保留輸入視頻的原始聲音。
seed integer （可選）
隨機數種子，取值範圍為[0, 2147483647]。
未指定時，系統自動產生隨機種子。若需提升產生結果的可複現性，建議固定seed值。
請注意，由於模型產生具有機率性，即使使用相同 seed，也不能保證每次產生結果完全一致。
|
響應參數 |
成功響應
請儲存 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（失敗）。
task_id 有效期間：24小時，逾時後將無法查詢結果，介面將返回任務狀態為UNKNOWN。
請求參數 | 查詢任務結果
將{task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期間為24小時。
curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
|
要求標頭（Headers） |
|
Authorization string（必選）
請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值：Bearer sk-xxxx。
|
URL路徑參數（Path parameters） |
|
響應參數 | 任務執行成功
視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。
{
"request_id": "c11018a8-3f83-9591-a636-xxxxxx",
"output": {
"task_id": "051c7b40-b2c5-4341-aee4-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2026-04-26 14:13:14.373",
"scheduled_time": "2026-04-26 14:13:14.419",
"end_time": "2026-04-26 14:14:13.679",
"orig_prompt": "讓視頻中的馬頭人身角色穿上圖片中的條紋毛衣",
"video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4"
},
"usage": {
"duration": 13.24,
"input_video_duration": 6.62,
"output_video_duration": 6.62,
"video_count": 1,
"SR": 720
}
}
任務執行失敗
若任務執行失敗，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 resolution is not valid 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，請檢查錯誤資訊並重試。
-
若狀態為 CANCELED，表示任務已取消，如需繼續請重新提交任務。
-
若狀態為 UNKNOWN，表示任務不存在或狀態未知，可能在 task_id 不存在或超過 24 小時有效期間後出現。
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。
code string
請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。
message string
請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。
|
usage object 輸出資訊統計。只對成功的結果計數。 屬性 duration float 產生視頻的總視頻時間長度，用於計費。 output_video_duration float 輸出視頻的時間長度，單位秒。 input_video_duration float 輸入視頻的時間長度，單位秒。 video_count integer 產生視頻的數量。固定為1。 | |
|
request_id string
請求唯一標識。可用於請求明細溯源和問題排查。
| |
錯誤碼
如果模型調用失敗並返回報錯資訊，請參見錯誤資訊進行解決。