Skip to main content
HappyHorse

HappyHorse-視頻編輯API參考

HappyHorse 視頻編輯模型支援輸入視頻與參考圖，結合文本指令完成風格變換、本機覆寫等編輯任務。

適用範圍

為確保調用成功，請務必保證模型、Endpoint URL 和 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

  • 新加坡
  • 美國（維吉尼亞）
  • 華北2（北京）
  • 德國（法蘭克福）
  • 日本（東京）
POST https://{WorkspaceId}.ap-southeast-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.0-video-edit。input object （必選）輸入的基本資料，包括待編輯的視頻、參考圖片和提示詞。

屬性

prompt string （必選）文本提示詞。用來描述對視頻的編輯意圖，如風格轉換、本機覆寫等。支援任何語言輸入，長度不超過5000個非中文字元或2500個中文字元，超過部分會自動截斷。media array （必選）媒體素材列表，用於指定待編輯的視頻和參考映像。數組必須包含1個 video 類型元素；可選包含0~5個 reference_image 類型元素。

元素屬性

type string （必選）媒體素材類型。可選值為：
  • video：必傳。待編輯的視頻。
  • reference_image：可選。參考映像。
素材限制：
  • 視頻數量：有且僅有1個。
  • 參考映像數量：0～5張。
url string （必選）媒體素材的URL地址。

傳入的視訊（type=video）

待編輯的視頻URL，必須為公網可訪問的URL。視頻限制：
  • 格式：MP4、MOV（建議H.264編碼）。
  • 時間長度：3~60秒。
  • 解析度：長邊不超過4096像素，短邊不小於360像素。
  • 寬高比：1:2.5~2.5:1。
  • 檔案大小：不超過100MB。
  • 幀率：8-60fps（若輸入可變幀率視頻，需保證幀率變化均在此範圍內）。
輸出視頻時間長度：3~15秒。
  • 當輸入視頻不超過 15 秒時，輸出視頻時間長度與輸入視頻保持一致。
  • 當輸入視頻超過 15 秒時，系統會從頭開始自動截取前 15 秒作為有效片段，因此最長輸出為 15 秒。

傳入映像（type=reference_image）

參考映像的URL或 Base 64 編碼資料。映像限制：
  • 格式：JPEG、JPG、PNG、WEBP。
  • 解析度：寬高尺寸不小於300像素。
  • 寬高比：1:2.5~2.5:1。
  • 檔案大小：不超過20MB。
支援輸入的格式：
  1. 公網URL：
  2. 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 （可選）產生視頻的解析度檔位。可選值：
  • 1080P：預設值。
  • 720P
watermark boolean （可選）是否在產生的視頻上添加浮水印標識。浮水印位於視頻右下角，文案固定為“Happy Horse”。
  • true：預設值，添加浮水印。
  • false：不添加浮水印。
audio_setting string （可選）聲音控制。
  • auto：預設值，由模型自行控制。
  • origin：保留輸入視頻的原始聲音。
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.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"
    }
}'

響應參數

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

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

  • 新加坡
  • 美國（維吉尼亞）
  • 華北2（北京）
  • 德國（法蘭克福）
  • 日本（東京）
GET https://{WorkspaceId}.ap-southeast-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 float產生視頻的總視頻時間長度，用於計費。SR integer產生視頻的解析度檔位。output_video_duration float輸出視頻的時間長度，單位秒。input_video_duration float輸入視頻的時間長度，單位秒。video_count integer產生視頻的數量。固定為1。
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。
  • 任務執行成功
  • 任務執行失敗
  • 任務查詢到期
視頻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
    }
}

錯誤碼

如果模型調用失敗並返回報錯資訊，請參見錯誤碼進行解決。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多