Skip to main content
本文介紹 HappyHorse Videos API 的串接方式。該介面透過統一的 /happyhorse/videos 入口和 action 參數支援文生影片、首幀圖生影片、參考圖生影片和影片編輯。

​
申請流程

要使用 HappyHorse Videos API，首先到 Ace Data Cloud 控制台 取得您的 API Token，留作備用。 如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。 一個 API Token 即可呼叫平台所有服務，無需為每個服務單獨申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在 控制台 儲值通用餘額。
📘 完整文件：HappyHorse Videos API →

​
操作類型

action 決定本次請求的生成模式：
  • generate：文生影片，預設 action，支援 happyhorse-1.0-t2v 和 happyhorse-1.1-t2v，必須傳入 prompt。
  • image_to_video：首幀圖生影片，支援 happyhorse-1.0-i2v 和 happyhorse-1.1-i2v，必須傳入 image_url。
  • reference_to_video：參考圖生影片，支援 happyhorse-1.0-r2v 和 happyhorse-1.1-r2v，必須傳入 prompt 和 1–9 張 image_urls。
  • video_edit：影片編輯，支援 happyhorse-1.0-video-edit，必須傳入 prompt 和 video_url，可額外傳入 0–5 張參考圖 image_urls。
各動作預設使用 1.1 模型；video_edit 目前只有 happyhorse-1.0-video-edit。

​
基本使用

文生影片只需要提供 prompt，也可以指定 resolution、ratio、duration 等參數：
返回結果範例如下：
欄位說明：
  • success：本次請求是否成功。
  • task_id：Ace Data Cloud 端任務 ID，可用於查詢任務狀態。
  • trace_id：本次請求的追蹤 ID，用於排查問題。
  • data：影片結果清單。
    • id：HappyHorse 端的任務 ID。
    • video_url：生成影片的 CDN 連結位址。
    • state：任務狀態，可選 pending / succeeded / error。
    • duration：計費影片時長，單位秒；video_edit 為輸入和輸出影片時長合計。
    • resolution：輸出解析度。
    • ratio：輸出寬高比。
對應的 CURL 程式碼如下：
對應的 Python 程式碼如下：

​
首幀圖生影片

使用 image_to_video 時，image_url 會作為影片首幀。輸出寬高比會盡量跟隨首幀圖片，因此該動作不需要傳入 ratio。

​
參考圖生影片

使用 reference_to_video 時，image_urls 可以傳入 1–9 張參考圖。提示詞中可以用 character1、character2 等方式引用對應順序的圖片。

​
影片編輯

使用 video_edit 時必須傳入待編輯影片 video_url 和編輯意圖 prompt。可選的 image_urls 會作為參考圖，例如換裝、風格遷移或局部替換。audio_setting 可選 auto 或 origin，其中 origin 表示保留原影片音訊。

​
非同步回呼

影片生成需要一定處理時間。如果不希望保持長連線等待，可以傳入 callback_url，此時 API 會立即返回 task_id，任務完成後會將最終結果 POST 到該地址：
立即返回的結果如下：
如果只希望輪詢，不需要回呼，也可以傳入 "async": true，隨後透過 HappyHorse Tasks API 查詢任務結果。

​
計費說明

HappyHorse 按輸出影片秒數和解析度計費：
  • 720P：低至約 $0.105 / 秒。
  • 1080P：低至約 $0.18 / 秒。
  • video_edit：按輸入影片和輸出影片時長合計計費，實際計費時長以任務完成後的統計為準。
失敗的任務不計費，也不占用免費額度。

​
錯誤處理

當請求出現問題時，API 會返回對應的錯誤碼與說明，常見的如下：
  • 400：請求參數有誤，例如 action 與 model 不相符、缺少 prompt / image_url / video_url，或 duration 超出 3–15 秒範圍。
  • 401：驗證失敗，token 無效或與 API 不相符。
  • 403：餘額不足，或提示詞命中內容審核而被拒絕。
  • 429：請求過於頻繁，觸發限流，請稍後重試。
  • 500：伺服器內部錯誤或生成失敗。