> ## 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 API guide - Ace Data Cloud

本書では、HappyHorse Videos API の連携方法を紹介します。この API は統一された `/happyhorse/videos` エンドポイントと `action` パラメータにより、テキストからの動画生成、開始フレーム画像からの動画生成、参照画像からの動画生成、および動画編集をサポートします。

## 申請手順

HappyHorse Videos API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。

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

まだログインまたは登録していない場合は、ログインページに自動的にリダイレクトされ、登録とログインが案内されます。完了後、自動的に現在のページへ戻ります。

**1 つの 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.