HiAPI 経由で HappyHorse 1.1 テキストtoビデオ API を呼び出す：動作する curl + Python チュートリアル

HappyHorse 1.1 は Alibaba のテキストtoビデオモデルです：720p / 1080p の動画クリップ、長さ 3〜15 秒に対応し、1 回の呼び出しでネイティブ音声を生成します（別途の BGM 手順は不要）。HiAPI は他のすべての生成モデルと同じ統一非同期エンドポイントでこのモデルを提供しているため、すでに /v1/tasks で画像モデルを呼び出したことがあるなら、変わるのはモデル id と一部の input フィールドだけです。

このページでは、動作する統合を納品するために必要な最小限の内容を提供します：正確なスキーマ、コピーするだけで使える curl、Python のポーリングクライアント、そして本番環境向けのコールバックパターンです。さらに、あまり自明ではない、モデルが受け付けない 2 つの事項（audio スイッチと seed）も特に指摘しているので、400 エラーでリクエストを無駄にすることはありません。

前提条件。 HiAPI コンソール からキーを取得し、HIAPI_API_KEY としてエクスポートしてください。各リクエストは Authorization: Bearer sk-… で認証されます。復習が必要な場合は Authentication を参照してください。

エンドポイントとリクエスト構造

すべては同じエンドポイントを経由します：

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

リクエストボディには 3 つのトップレベルキーがあります：

• model — happyhorse-1.1/text-to-video（リテラルのモデル id — スラッシュはそのまま保持）。
• input — モデル固有のフィールド。HappyHorse 1.1 T2V の場合：
  • prompt（文字列、必須）— 動画クリップを記述します。
  • resolution（720p | 1080p、デフォルト 1080p）。
  • aspect_ratio（16:9 | 9:16 | 3:4 | 4:3 | 4:5 | 5:4 | 1:1 | 9:21 | 21:9、デフォルト 16:9）。
  • duration（整数、3〜15、デフォルト 5）。料金は秒数に応じて増加します。
• callback（任意、オブジェクト）— callback.url HTTPS エンドポイント + callback.when: "final"。HiAPI は各タスクについて、このアドレスに最終結果をちょうど 1 回 POST します。

使えそうに見えて実際には使えない 2 つのこと：

• ❌ audio フィールドはありません。 音声は動画とともにネイティブ生成され、スイッチはありません。"audio": true を送信すると additional properties 'audio' not allowed が返されます。
• ❌ seed フィールドはありません。 同様に 400 が返されます。バッチの決定性が今すぐ必要な場合は、複数のバージョンを生成して選ぶしかありません——調整できる seed のレバーは存在しません。

最小限の有効なリクエストボディ：

{
  "model": "happyhorse-1.1/text-to-video",
  "input": {
    "prompt": "砂浜を走るゴールデンレトリバー、スローモーション、穏やかな波、暖かい夕日の色調",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}

最小の実行動作例：curl

タスクを作成——レスポンスは即座に返り、taskId だけが含まれます：

curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "朝霧に包まれた雪山の湖、ゆっくりとしたカメラのプッシュイン、暖かいシネマティックな光",
      "resolution": "1080p",
      "aspect_ratio": "16:9",
      "duration": 5
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01KW3..."},"message":"success"}

その後、終端状態になるまでポーリングします：

TASK_ID=tk-hiapi-01KW3...

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "happyhorse-1.1/text-to-video",
#     "output": [
#       {"type":"video","url":"https://temp.hiapi.ai/.../...-0.mp4","expireAt":1783130616}
#     ],
#     ...
#   }
# }

mp4 URL は一時的です（expireAt は約 7 日後の Unix タイムスタンプ）。タスク成功後すぐにダウンロードして永続保存してください——ホットリンクはしないでください。HiAPI に長期ストレージを管理させたい場合は、Output Storage ドキュメント を参照して、出力を一時ストレージから永続ストレージへ昇格させる方法を確認してください。

Python：小さく本番向けのクライアント

実際のクライアントには 3 つのものが必要です：id を返す create_task、締め切り付きでポーリングする wait_task、そしてダウンロード手順です。この骨組みは 3 つすべてを含み、HiAPI の Python SDK ページ の出発点に近いものです——小さく保ち、そこから拡張してください。

# pip install requests
import os, time, json, requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}


def create_task(prompt: str, *, resolution="1080p", aspect_ratio="16:9", duration=5) -> str:
    body = {
        "model": "happyhorse-1.1/text-to-video",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
            "duration": duration,
        },
    }
    r = requests.post(API_BASE, headers={**HEADERS, "Content-Type": "application/json"},
                      data=json.dumps(body), timeout=60)
    r.raise_for_status()
    data = r.json()
    if data.get("code") != 200:
        raise RuntimeError(f"create failed: {data}")
    return data["data"]["taskId"]


def wait_task(task_id: str, *, timeout_s: int = 600, poll: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


def download(url: str, path: str) -> None:
    with requests.get(url, stream=True, timeout=120) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(1 << 14):
                f.write(chunk)


if __name__ == "__main__":
    task_id = create_task(
        "雨上がりの夜のネオン街、地面への反射、"
        "サイバーパンクの雰囲気、ゆっくりとしたパン",
        resolution="720p", aspect_ratio="9:16", duration=5,
    )
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    download(url, "out.mp4")
    print("saved out.mp4")

本番環境での注意点：

• ステータスフィールド。 success または fail 以外の値はすべて進行中として扱ってください（プラットフォームは現在 handling を使用しています）。
• raise_for_status だけでは不十分。 一部の検証エラーでは、HiAPI は HTTP 200 を返しますが code は 200 ではありません——必ず data["code"] も確認してください。新しい統合で最も多いのは 401 permission_denied で、これは bearer トークンが誤っているか欠落していることを意味します——HIAPI_API_KEY を再エクスポートし、コンソールで確認してください。

本番環境：ポーリングよりコールバックを優先

クイックスタートを超えるあらゆる場面では、HiAPI に webhook を渡し、タスク完了時にあなたを呼び出させてください：

{
  "model": "happyhorse-1.1/text-to-video",
  "input": {
    "prompt": "朝霧に包まれた雪山の湖、ゆっくりとしたカメラのプッシュイン、暖かいシネマティックな光",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

コールバックハンドラーは次のことを必ず行ってください：

• taskId で重複排除する。 success も fail も終端状態です——同じ taskId を 2 回受け取った場合、あなたのサービスはそれをノーオペレーションとして扱う必要があります（taskId をキーとした冪等書き込み）。
• 素早く 2xx を返す。 重い処理（mp4 のダウンロード、永続化、ユーザーへの通知）はキューに入れてください。Webhook ハンドラーは数秒以内に確認応答する必要があります。
• GET /v1/tasks/:id をフォールバックとして保持する。 webhook が失われた場合（デプロイ、ネットワークの揺らぎ）、id でスタックしたタスクを取得し同じハンドラーを適用する照合ジョブが、最もシンプルなセーフティネットです。

どちらか一方の道を選ぶなら：ポーリングは使い捨てスクリプトやローカルデバッグに適しており、実際のトラフィックがある場所ではコールバックを使うべきです。

正しいパラメータの選び方（resolution × aspect_ratio × duration）

要件	resolution	aspect_ratio	duration
SNS 向け縦型ショート、コスト最小	720p	9:16	5
正方形プレビュー / サムネイルループ	720p	1:1	3
横長ナラティブ / 広告ショット	1080p	16:9	5–8
ワイドスクリーンのキービジュアルクリップ	1080p	21:9	8–12

料金は解像度と長さに応じて増加します——正確な秒単位の料金は HiAPI 料金 を参照してください。正しい値がわからない場合は入力しないでください：resolution のデフォルトは 1080p、aspect_ratio のデフォルトは 16:9、duration のデフォルトは 5 です。

よくある質問

HappyHorse 1.1 テキストtoビデオには seed パラメータがありますか？ いいえ。API は additional properties 'seed' not allowed で seed を拒否します。選択用に複数の候補が必要な場合は、同じ prompt で複数のタスクを送信してください——異なる実行は自然に差異を生み出します。

音声をオンまたはオフにするにはどうすればよいですか？ 操作できません——HappyHorse 1.1 は同じ呼び出しでネイティブに音声トラックを生成します。スキーマに audio スイッチはなく、送信すると 400 が返されます。無音のクリップが必要な場合は、ポストプロダクションで音声を除去してください。

有効な長さはどれくらいですか？ 3 から 15（秒）の整数です。この範囲外の値は duration: minimum: got 0, want 3 または duration: maximum: got 20, want 15 を返します。小数も拒否されます（このフィールドの型は整数です）。

どのアスペクト比に対応していますか？ 9 種類：16:9、9:16、3:4、4:3、4:5、5:4、1:1、9:21、21:9。デフォルトは 16:9 です。

output[].url はどのくらいの期間有効ですか？ 約 1 週間です——レスポンスには expireAt Unix タイムスタンプが含まれます。すぐに mp4 をダウンロードして再ホスティングするか（S3、R2、あなたの CDN）、Output Storage API 経由で永続ストレージへ昇格させてください。

イメージtoビデオはどうですか？ HappyHorse 1.1 は同じエンドポイントに I2V バリアントがあります——HappyHorse 1.1 I2V を参照してください。同じ認証、同じ非同期ライフサイクル、異なる input スキーマです。

完全な非同期 API リファレンスはどこにありますか？ リクエストエンベロープは Create Task、ポーリングエンドポイントは Get Task Detail、正規の入力スキーマは HappyHorse 1.1 T2V モデルページ にあります。ゼロから始める場合は、Quickstart が最初の呼び出しをエンドツーエンドで案内します。