> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# HappyHorse Videos API 串接說明

> HappyHorse Video 整合指南 - Ace Data Cloud

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

## 申請流程

要使用 HappyHorse Videos API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 取得您的 API Token，留作備用。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。

**一個 API Token 即可呼叫平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。

> 📘 完整文件：[HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## 操作類型

`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` 等參數：

```json theme={null}
{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}
```

返回結果範例如下：

```json theme={null}
{
  "success": true,
  "task_id": "27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1",
  "trace_id": "6071ab5e-2f37-46f0-9e07-f1e378112e69",
  "data": [
    {
      "id": "9650580f-6d9e-4bc1-823a-29011790c5cb",
      "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
      "state": "succeeded",
      "duration": 5,
      "resolution": "720P",
      "ratio": null
    }
  ]
}
```

欄位說明：

* `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 程式碼如下：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/happyhorse/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}'
```

對應的 Python 程式碼如下：

```python theme={null}
import requests

url = "https://api.acedata.cloud/happyhorse/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 首幀圖生影片

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

```json theme={null}
{
  "action": "image_to_video",
  "model": "happyhorse-1.1-i2v",
  "image_url": "https://cdn.acedata.cloud/b1c82e4937.png",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "1080P",
  "duration": 5
}
```

## 參考圖生影片

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

```json theme={null}
{
  "action": "reference_to_video",
  "model": "happyhorse-1.1-r2v",
  "prompt": "character1 walks forward through a sunrise meadow with the warm leather and gold trim style from character2",
  "image_urls": [
    "https://cdn.acedata.cloud/b1c82e4937.png",
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}
```

## 影片編輯

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

```json theme={null}
{
  "action": "video_edit",
  "model": "happyhorse-1.0-video-edit",
  "prompt": "Apply the warm leather and gold trim style from the reference image while preserving the original camera motion",
  "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
  "image_urls": [
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "audio_setting": "auto"
}
```

## 非同步回呼

影片生成需要一定處理時間。如果不希望保持長連線等待，可以傳入 `callback_url`，此時 API 會立即返回 `task_id`，任務完成後會將最終結果 POST 到該地址：

```json theme={null}
{
  "action": "generate",
  "prompt": "A horse running through a snowy forest",
  "duration": 5,
  "callback_url": "https://your-domain.com/callback/happyhorse"
}
```

立即返回的結果如下：

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

如果只希望輪詢，不需要回呼，也可以傳入 `"async": true`，隨後透過 [HappyHorse Tasks API](https://platform.acedata.cloud/documents/happyhorse-tasks) 查詢任務結果。

## 計費說明

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`：伺服器內部錯誤或生成失敗。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.