HappyHorse API ドキュメント

HappyHorse 1.0 動画生成 API をアプリに組み込むための完全ガイド。

API v1.0 Base URL: https://happyhorse.app

クイックスタート

bash
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 キーを取得

http
Authorization: Bearer YOUR_API_KEY

Generate と Status の流れ

HappyHorse の動画タスクは非同期です。POST /api/generate でタスクを作成し、返された task_id を保存して、最終状態になるまで GET /api/status を確認します。

1

タスクを作成

prompt、model、mode、duration、必要に応じて画像を /api/generate に送信します。成功すると task_id がすぐに返ります。

2

状態をポーリング

task_id を使って /api/status を呼び出します。status が IN_PROGRESS の間は動画生成中で、response は null のままです。

3

結果を取得

status が SUCCESS になったら data.response.resultUrls[0] が動画 URL です。FAILED になった場合は error_message を表示し、ポーリングを停止します。

利用可能なモデル

HappyHorse 1.0

HappyHorse 1.0

HappyHorse による高品質な AI 動画生成

種類説明長さクレジット
pro (text-to-video)Pro 品質のテキストから動画3-15s54/s (no audio) · 80/s (with audio)
pro (image-to-video)Pro 品質の画像から動画3-15s54/s (no audio) · 80/s (with audio)
std (text-to-video)標準品質のテキストから動画3-15s40/s (no audio) · 60/s (with audio)
std (image-to-video)標準品質の画像から動画3-15s40/s (no audio) · 60/s (with audio)

API エンドポイント

新しい動画生成タスクを作成します。model は 'happyhorse-1.0/video' に設定してください。

リクエストボディ

ボディパラメータJSON
model:string

モデル名。'happyhorse-1.0/video' である必要があります

prompt:optional string

生成する動画のテキスト説明(最大 2500 文字)。multi_shots が true の場合は不要。

mode:optional string

品質モード:'pro' または 'std'(既定:std) Defaults to std.

duration:optional number

動画の長さ(秒)、3〜15。マルチショット時の最終尺は multi_prompt の合計から決まります。duration を明示する場合は各ショットの合計秒数に合わせてください。 Defaults to 5 / sum(multi_prompt).

aspect_ratio:optional string

出力アスペクト比(16:9、9:16、1:1) Defaults to 16:9.

image_urls:optional string[]

画像から動画へ用の画像 URL の配列

sound:optional boolean

ネイティブ音声生成を有効化(既定:true)。マルチショットではこのフィールドを true または false で明示的に送信してください。 Defaults to true.

cfg_scale:optional number

プロンプト忠実度(0-1、既定: 0.5)。値が高いほどプロンプトに忠実に従います。 Defaults to 0.5.

multi_shots:optional boolean

複数プロンプトによるマルチショットモード Defaults to false.

multi_prompt:optional array

マルチショット用の 'prompt, duration' オブジェクトの配列

happyhorse_elements:optional array

要素オブジェクトの配列。プロンプトでは各要素の name の前に @ を付けて参照(例:name が element_dog なら @element_dog と書く)。各要素: name、description、element_input_urls(2-4 画像URL)。1タスク最大3要素。

テキストから動画

json
{
  "model": "happyhorse-1.0/video",
  "prompt": "A majestic eagle soaring through clouds at sunset",
  "mode": "pro",
  "duration": 5,
  "aspect_ratio": "16:9",
  "sound": true
}

画像から動画

json
{
  "model": "happyhorse-1.0/video",
  "prompt": "The character slowly turns and smiles",
  "mode": "pro",
  "image_urls": ["https://example.com/my-image.jpg"],
  "duration": 5
}

マルチショット動画

json
{
  "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 で動画生成タスクの状態を確認します。

クエリパラメータ

クエリパラメータ
task_id:string

generate が返す一意のタスク ID(n92 接頭辞)

リクエスト例

bash
curl -X GET 'https://happyhorse.app/api/status?task_id=n92abc123hh10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

ヒント: response に resultUrls 配列が含まれます。動画 URL は data.response.resultUrls[0] で取得できます。

javascript
// 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 やクレジットの確認を促してください。

javascript
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 を実際のキーに置き換えてください。

API プレイグラウンドPOST

エラーコード

HTTP ステータスコード説明
400 不正なリクエストINVALID_PROMPTプロンプトが無効または空です
400 不正なリクエストINVALID_DURATION長さが対応範囲外です(3〜15 秒)
400 不正なリクエストINVALID_MODELモデルは 'happyhorse-1.0/video' である必要があります
401 未認証INVALID_API_KEYAPI キーがないか無効です
402 支払いが必要INSUFFICIENT_CREDITSこの操作に十分なクレジットがありません
429 リクエストが多すぎますRATE_LIMITEDリクエストが多すぎます。間隔を空けてください
500 内部サーバーエラーINTERNAL_ERRORサーバーエラーです。しばらくしてから再試行してください