HappyHorse API ドキュメント
HappyHorse 1.0 動画生成 API をアプリに組み込むための完全ガイド。
クイックスタート
curl -X POST 'https://happyhorse.app/api/generate' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "happyhorse-1.0/video",
"prompt": "A cinematic shot of mountains at sunrise",
"mode": "pro",
"duration": 5,
"aspect_ratio": "16:9"
}'認証
すべての API リクエストは Authorization ヘッダーに Bearer トークンを付与する必要があります。
API キーを取得: ダッシュボードの API Keys ページで API キーを取得できます。 → API キーを取得
Authorization: Bearer YOUR_API_KEYGenerate と Status の流れ
HappyHorse の動画タスクは非同期です。POST /api/generate でタスクを作成し、返された task_id を保存して、最終状態になるまで GET /api/status を確認します。
タスクを作成
prompt、model、mode、duration、必要に応じて画像を /api/generate に送信します。成功すると task_id がすぐに返ります。
状態をポーリング
task_id を使って /api/status を呼び出します。status が IN_PROGRESS の間は動画生成中で、response は null のままです。
結果を取得
status が SUCCESS になったら data.response.resultUrls[0] が動画 URL です。FAILED になった場合は error_message を表示し、ポーリングを停止します。
利用可能なモデル
HappyHorse 1.0
HappyHorse による高品質な AI 動画生成
| 種類 | 説明 | 長さ | クレジット |
|---|---|---|---|
pro (text-to-video) | Pro 品質のテキストから動画 | 3-15s | 54/s (no audio) · 80/s (with audio) |
pro (image-to-video) | Pro 品質の画像から動画 | 3-15s | 54/s (no audio) · 80/s (with audio) |
std (text-to-video) | 標準品質のテキストから動画 | 3-15s | 40/s (no audio) · 60/s (with audio) |
std (image-to-video) | 標準品質の画像から動画 | 3-15s | 40/s (no audio) · 60/s (with audio) |
API エンドポイント
新しい動画生成タスクを作成します。model は 'happyhorse-1.0/video' に設定してください。
リクエストボディ
モデル名。'happyhorse-1.0/video' である必要があります
生成する動画のテキスト説明(最大 2500 文字)。multi_shots が true の場合は不要。
品質モード:'pro' または 'std'(既定:std) Defaults to std.
動画の長さ(秒)、3〜15。マルチショット時の最終尺は multi_prompt の合計から決まります。duration を明示する場合は各ショットの合計秒数に合わせてください。 Defaults to 5 / sum(multi_prompt).
出力アスペクト比(16:9、9:16、1:1) Defaults to 16:9.
画像から動画へ用の画像 URL の配列
ネイティブ音声生成を有効化(既定:true)。マルチショットではこのフィールドを true または false で明示的に送信してください。 Defaults to true.
プロンプト忠実度(0-1、既定: 0.5)。値が高いほどプロンプトに忠実に従います。 Defaults to 0.5.
複数プロンプトによるマルチショットモード Defaults to false.
マルチショット用の 'prompt, duration' オブジェクトの配列
要素オブジェクトの配列。プロンプトでは各要素の name の前に @ を付けて参照(例:name が element_dog なら @element_dog と書く)。各要素: name、description、element_input_urls(2-4 画像URL)。1タスク最大3要素。
テキストから動画
{
"model": "happyhorse-1.0/video",
"prompt": "A majestic eagle soaring through clouds at sunset",
"mode": "pro",
"duration": 5,
"aspect_ratio": "16:9",
"sound": true
}画像から動画
{
"model": "happyhorse-1.0/video",
"prompt": "The character slowly turns and smiles",
"mode": "pro",
"image_urls": ["https://example.com/my-image.jpg"],
"duration": 5
}マルチショット動画
{
"model": "happyhorse-1.0/video",
"mode": "pro",
"multi_shots": true,
"sound": true,
"duration": 10,
"multi_prompt": [
{ "prompt": "A woman walks into a coffee shop", "duration": 3 },
{ "prompt": "She orders a latte and sits by the window", "duration": 4 },
{ "prompt": "She looks outside and smiles", "duration": 3 }
],
"aspect_ratio": "16:9"
}レスポンス
Task created successfully
{
"code": 200,
"message": "success",
"data": {
"task_id": "n92abc123hh10",
"status": "IN_PROGRESS"
}
}generate が返した task_id で動画生成タスクの状態を確認します。
クエリパラメータ
generate が返す一意のタスク ID(n92 接頭辞)
リクエスト例
curl -X GET 'https://happyhorse.app/api/status?task_id=n92abc123hh10' \
-H 'Authorization: Bearer YOUR_API_KEY'ヒント: response に resultUrls 配列が含まれます。動画 URL は data.response.resultUrls[0] で取得できます。
// Extract video URL after the task is complete
const task = payload.data;
const videoUrl = task.status === "SUCCESS"
? task.response?.resultUrls?.[0]
: null;レスポンス
{
"code": 200,
"message": "success",
"data": {
"task_id": "n92abc123hh10",
"status": "SUCCESS",
"consumed_credits": 400,
"created_at": "2026-04-08T10:30:00Z",
"type": "text-to-video",
"request": {
"model": "happyhorse-1.0/video",
"prompt": "A majestic eagle soaring through clouds at sunset",
"mode": "pro",
"duration": 5,
"aspect_ratio": "16:9"
},
"response": {
"resultUrls": [
"https://cdn.example.com/videos/abc123.mp4"
]
},
"error_message": null
}
}ポーリングのベストプラクティス
動画生成には少し時間がかかるため、状態確認は高頻度ループではなく、落ち着いたバックグラウンド処理として扱ってください。
短い待機から始める
最初の確認前に約 8-10 秒待ち、その後は 10-20 秒ごとに確認します。より頻繁に確認しても生成は早くなりません。
最終状態で停止
SUCCESS と FAILED は最終状態です。どちらかを確認したらすぐに停止し、サポートや後日の確認のため task_id を保存してください。
クライアント側のタイムアウト
10-15 分待ったらアクティブな待機を終了し、ユーザーが後で手動確認できるようにします。ブラウザータブで無限にポーリングしないでください。
エラー時は間隔を延ばす
429 や一時的なネットワークエラーを受けたら、次のリクエストまで長めに待ちます。401 または 402 では API Key やクレジットの確認を促してください。
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function waitForHappyHorseVideo(taskId) {
const deadline = Date.now() + 15 * 60 * 1000;
let delayMs = 8000;
while (Date.now() < deadline) {
const res = await fetch(
`${BASE_URL}/api/status?task_id=${encodeURIComponent(taskId)}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
if (res.status === 429) {
await sleep(Math.min(delayMs * 2, 30000));
continue;
}
const payload = await res.json();
if (!res.ok) {
throw new Error(payload.message || `Status request failed: ${res.status}`);
}
const task = payload.data;
if (task.status === "SUCCESS") {
return task.response?.resultUrls?.[0];
}
if (task.status === "FAILED") {
throw new Error(task.error_message || "Generation failed");
}
await sleep(delayMs);
delayMs = Math.min(delayMs + 2000, 20000);
}
throw new Error("Timed out. Keep the task_id and check again later.");
}API プレイグラウンド
ブラウザから直接 API を試せます。YOUR_API_KEY を実際のキーに置き換えてください。
エラーコード
| HTTP ステータス | コード | 説明 |
|---|---|---|
| 400 不正なリクエスト | INVALID_PROMPT | プロンプトが無効または空です |
| 400 不正なリクエスト | INVALID_DURATION | 長さが対応範囲外です(3〜15 秒) |
| 400 不正なリクエスト | INVALID_MODEL | モデルは 'happyhorse-1.0/video' である必要があります |
| 401 未認証 | INVALID_API_KEY | API キーがないか無効です |
| 402 支払いが必要 | INSUFFICIENT_CREDITS | この操作に十分なクレジットがありません |
| 429 リクエストが多すぎます | RATE_LIMITED | リクエストが多すぎます。間隔を空けてください |
| 500 内部サーバーエラー | INTERNAL_ERROR | サーバーエラーです。しばらくしてから再試行してください |