HappyHorse參考生視頻API參考 - Alibaba Cloud Model Studio

HappyHorse-參考生視頻模型支援傳入多張參考映像，通過文本提示詞描述情境，將映像中的主體角色融合產生一段流暢的視頻。

適用範圍

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

選擇模型：確認模型所屬的地區。
選擇 URL：選擇對應的地區 Endpoint URL，支援HTTP URL或 DashScope SDK URL。
配置 API Key：選擇地區並擷取與配置 API Key，再配置API Key到環境變數。

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

重要阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：

華北2（北京）地區：從 https://dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
新加坡地區：從 https://dashscope-intl.aliyuncs.com 遷移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

其中 {WorkspaceId} 為您的業務空間 ID，可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。

HTTP調用

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

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

新加坡

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

美國（維吉尼亞）

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

華北2（北京）

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

德國（法蘭克福）

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

日本（東京）

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

調用時請將{WorkspaceId}替換為真實的業務空間ID。

說明

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

請求參數

要求標頭（Headers）

Content-Typestring（必選）

請求內容類型。此參數必須設定為application/json。

Authorizationstring（必選）

請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值：Bearer sk-xxxx。

X-DashScope-Asyncstring（必選）

非同步處理配置參數。HTTP請求只支援非同步，必須設定為enable。

重要缺少此要求標頭將報錯：“current user api does not support synchronous calls”。

請求體（Request Body）

model string （必選）

模型名稱。

可選值：

happyhorse-1.1-r2v
happyhorse-1.0-r2v

input object （必選）

輸入的基本資料，包括參考映像和提示詞。

屬性

prompt string （必選）

文本提示詞。用來描述產生視頻中期望包含的元素和視覺特點。

支援任何語言輸入，長度不超過5000個非中文字元或2500個中文字元，超過部分會自動截斷。

參考指代：在prompt中通過“[Image 1]、[Image 2]”標識指代media數組中對應位置的參考映像，順序與media數組順序一致。使用時需要指明參考圖中的具體對象，例如“[Image 1]中身著紅色旗袍的女性”。

media array （必選）

媒體素材列表，用於指定參考映像。

數組的每個元素為一個媒體對象，包含 type和 url欄位。

按照數組順序定義prompt中動作項目參考的順序。
數組中的第 1 個reference_image對應 [Image 1]，第 2 個對應 [Image 2]，以此類推。

元素屬性

type string （必選）

媒體素材類型。固定值為：

reference_image：參考映像。

素材限制：

參考映像數量：1～9張。

url string （必選）

參考映像URL或 Base 64 編碼資料。

映像限制：

格式：JPEG、JPG、PNG、WEBP。
解析度：短邊不低於400像素，推薦720P以上清晰圖。避免傳入過小、模糊或壓縮過度的映像，影響效果。
檔案大小：不超過20MB。

支援輸入的格式：

公網URL：
- 支援 HTTP 或 HTTPS 協議。
- 樣本值：https://xxx/xxx.jpg。
Base 64 編碼映像後的字串：
- 資料格式：data:{MIME_type};base64,{base64_data}。
- 樣本值：data:image/png;base64,GDU7MtCZzEbTbmRZ......（樣本已截斷，僅做示範）。
  Base64編碼資料格式
  格式： data:{MIME_type};base64,{base64_data} 。
  - {base64_data}：影像檔經過 Base 64 編碼後的字串。
  - {MIME_type}：映像的媒體類型，需與檔案格式對應。
  映像格式
  MIME Type
  JPEG
  image/jpeg
  JPG
  image/jpeg
  PNG
  image/png
  WEBP
  image/webp

parameters object （可選）

視頻產生參數。如設定視頻解析度、寬高比、時間長度等。

屬性

resolution string （可選）

產生視頻的解析度檔位。

可選值：

480P
720P
1080P：預設值。

ratio string （可選）

產生視頻的寬高比。

可選值：

16:9：預設值。
9:16
3:4
4:3
4:5
5:4
1:1
9:21
21:9

duration integer （可選）

產生視頻的時間長度，單位為秒。

取值範圍：3~15之間的整數。

預設值：5。

watermark boolean （可選）

是否在產生的視頻上添加浮水印標識。浮水印位於視頻右下角，文案固定為“Happy Horse”。

true：預設值，添加浮水印。
false：不添加浮水印。

seedinteger（可選）

隨機數種子，取值範圍為[0, 2147483647]。

未指定時，系統自動產生隨機種子。若需提升產生結果的可複現性，建議固定seed值。

請注意，由於模型產生具有機率性，即使使用相同 seed，也不能保證每次產生結果完全一致。

參考生視頻（多映像）

# 以下為新加坡地區URL，調用時請將{WorkspaceId}替換為真實的業務空間ID，各地區的URL不同。
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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.1-r2v",
    "input": {
        "prompt": "[Image 1]中身著紅色旗袍的女性，鏡頭先以側面中景勾勒旗袍修身剪裁與S型曲線，隨即切換至低角度仰拍，捕捉她輕抬玉手展開[Image 2]中的摺扇的同時，[Image 3]中的流蘇耳墜隨頭部轉動輕盈擺動的細節，最後推近至面部特寫，定格在她指尖輕點扇骨、眼波流轉間的含蓄風情，多視角全方位展現東方韻味。",
        "media": [
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "duration": 5
    }
}'

響應參數

output object

任務輸出資訊。

屬性

task_id string

任務ID。查詢有效期間24小時。

task_status string

任務狀態。

枚舉值

PENDING：任務排隊中
RUNNING：任務處理中
SUCCEEDED：任務執行成功
FAILED：任務執行失敗
CANCELED：任務已取消
UNKNOWN：任務不存在或狀態未知

request_idstring

請求唯一標識。可用於請求明細溯源和問題排查。

codestring

請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。

messagestring

請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤碼。

成功響應

請儲存 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"
}

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

新加坡

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

美國（維吉尼亞）

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

華北2（北京）

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

德國（法蘭克福）

GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

日本（東京）

GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

說明

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

請求參數

要求標頭（Headers）

Authorizationstring（必選）

請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值：Bearer sk-xxxx。

URL路徑參數（Path parameters）

task_id string（必選）

任務ID。

查詢任務結果

將{task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期間為24小時，並請將{WorkspaceId}替換為真實的業務空間ID。

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

響應參數

outputobject

任務輸出資訊。

屬性

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_urlstring

視頻URL。僅在 task_status 為 SUCCEEDED 時返回。

連結有效期間24小時，可通過此URL下載視頻。視頻格式為MP4（H.264 編碼）。

orig_prompt string

原始輸入的prompt，對應請求參數prompt。

codestring

請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。

messagestring

請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤碼。

usage object

輸出資訊統計。只對成功的結果計數。

屬性

duration integer

產生視頻的總視頻時間長度，用於計費。

input_video_duration integer

輸入視頻的總時間長度，單位為秒。參考生視頻中固定為0。

output_video_duration integer

輸出視頻的總時間長度，單位為秒。

ratio string

產生視頻的寬高比。

SR integer

產生視頻的解析度檔位。

video_count integer

產生視頻的數量。固定為1。

request_idstring

請求唯一標識。可用於請求明細溯源和問題排查。

任務執行成功

視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。

{
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-25 15:03:25.848",
        "scheduled_time": "2026-04-25 15:03:25.884",
        "end_time": "2026-04-25 15:04:05.882",
        "orig_prompt": "[Image 1]中身著紅色旗袍的女性，鏡頭先以側面中景勾勒旗袍修身剪裁與S型曲線，隨即切換至低角度仰拍，捕捉她輕抬玉手展開[Image 2]中的摺扇的同時，[Image 3]中的流蘇耳墜隨頭部轉動輕盈擺動的細節，最後推近至面部特寫，定格在她指尖輕點扇骨、眼波流轉間的含蓄風情，多視角全方位展現東方韻味。",
        "video_url": "https://dashscope-result-intl.oss-ap-southeast-1.aliyuncs.com/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720,
        "ratio": "16:9"
    }
}

任務執行失敗

若任務執行失敗，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"
    }
}

錯誤碼

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