hiapi API で happyhorse-1.1 を使う方法：テキストから動画、画像から動画、参照から動画

happy horse 1.1 の使い方をお探しなら、まず結論から言うと、happyhorse-1.1 は 1 つのモデルエンドポイントではなく 3 つあり、いずれも hiapi の統一された非同期タスク API を通じて提供されます：

エンドポイント（モデル ID）	機能	必須入力
happyhorse-1.1/text-to-video	テキストプロンプトから動画を生成	prompt
happyhorse-1.1/image-to-video	静止画像を動かす	image_urls
happyhorse-1.1/reference-to-video	参照画像とプロンプトの誘導で動画を生成	prompt、reference_image

これら 3 つのエンドポイントは同じライフサイクルを共有します：POST /v1/tasks で送信 → taskId を取得 → GET /v1/tasks/<id> をポーリング（またはコールバックを受信）→ output[0].url をダウンロード。以下の各パラメータ表と各エラーメッセージはすべて実際の API に対して検証済みです——推測は一切含まれていません。

前提条件

必要なものは 1 つだけです：hiapi API キー。hiapi コンソールから取得してください——形式は sk-... のようなもので、Authorization: Bearer リクエストヘッダーに設定します。動画生成は出力秒数に応じて課金されます。各エンドポイントの現在の毎秒料金は料金ページをご覧ください。

export HIAPI_KEY="sk-your-key-here"

最小の実行可能なサンプル（テキストから動画）

タスクを送信します：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A golden retriever puppy runs through a sunlit meadow, slow motion, cinematic",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

レスポンスの data.taskId にタスク ID が返ります。それをポーリングします：

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer $HIAPI_KEY"

data.status が success になると、動画 URL は data.output[0].url にあります。すぐにダウンロードしてください——出力 URL には expireAt タイムスタンプがあり、一時ストレージに保存されるため、永続的なホスティングではなく受け取り可能な期間とみなしてください。

以下は同じフローの完全な Python スクリプトです（標準ライブラリのみ使用）：

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-your-key-here"

def api(method, url, payload=None):
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("Content-Type", "application/json")
    data = json.dumps(payload).encode() if payload else None
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read())

# 1. 送信
task = api("POST", API, {
    "model": "happyhorse-1.1/text-to-video",
    "input": {
        "prompt": "A golden retriever puppy runs through a sunlit meadow, cinematic",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
    },
})
task_id = task["data"]["taskId"]
print("submitted:", task_id)

# 2. 終了状態になるまでポーリング
while True:
    data = api("GET", f"{API}/{task_id}")["data"]
    status = data["status"]
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        raise RuntimeError(f"task failed: {data.get('error')}")
    time.sleep(5)

# 3. URL が期限切れになる前にダウンロード
urllib.request.urlretrieve(video_url, "output.mp4")
print("saved output.mp4")

各エンドポイントのパラメータ

入力スキーマは厳格です：未知のフィールドは黙って無視されるのではなく、400 で拒否されます。size、seed、negative_prompt、audio などのフィールドはいずれも additional properties ... not allowed を返します。以下は各エンドポイントが正確に受け付けるパラメータです。

happyhorse-1.1/text-to-video

フィールド	必須	型	許容値
prompt	✅	string	シーンの説明
aspect_ratio	—	string	16:9、9:16、3:4、4:3、4:5、5:4、1:1、9:21、21:9
resolution	—	string	720p、1080p
duration	—	integer	3〜15（秒）

プロンプトのコツを含む完全な解説：happyhorse-1.1 テキストから動画チュートリアル。

happyhorse-1.1/image-to-video

フィールド	必須	型	許容値
image_urls	✅	文字列の配列	ちょうど 1 つの公開アクセス可能な画像 URL（maxItems: 1）
prompt	—	string	アニメーションの動き/シーンの誘導
resolution	—	string	720p、1080p
duration	—	integer	3〜15（秒）

ここには 2 つの落とし穴があります。第一に、image_urls は配列ですが、現在は 1 つの要素しか受け付けません——裸の文字列でも複数の URL でもなく、["https://..."] のように渡してください。第二に、このエンドポイントにはaspect_ratio がありません（API はこれを拒否します）；出力のアスペクト比は元画像に従います。

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "prompt": "slow camera push-in, soft studio lighting",
      "resolution": "720p",
      "duration": 5
    }
  }'

さらに詳しく：happyhorse 画像から動画チュートリアル。

happyhorse-1.1/reference-to-video

フィールド	必須	型	許容値
prompt	✅	string	シーンの説明
reference_image	✅	文字列の配列	1〜9 個の公開アクセス可能な画像 URL（maxItems: 9）
aspect_ratio	—	string	テキストから動画と同じ 9 種類の比率
resolution	—	string	720p、1080p
duration	—	integer	3〜15（秒）

これが「キャラクター/製品の一貫性を保つ」エンドポイントです：参照画像がアイデンティティとスタイルを固定し、プロンプトが動きを駆動します。画像から動画とは異なり、ここでは aspect_ratio の制御が再び利用でき、最大 9 枚の参照画像を渡せます。

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "the character waves at the camera and smiles, city street at dusk",
      "reference_image": ["https://your-cdn.example.com/character-front.jpg",
                          "https://your-cdn.example.com/character-side.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 5
    }
  }'

さらに詳しく：happyhorse-1.1 参照から動画チュートリアル。

どのエンドポイントを選ぶべきか？

• アイデアしかない → text-to-video。テキストから動きへの最速の道。
• アニメーション化したい正確な画面がある（製品画像、イラスト、写真）→ image-to-video。元画像がそのまま最初のフレームになります。
• 複数のクリップで同じ主体を保つ必要がある（1 人のキャラクター、1 つのマスコット、1 つの製品の複数アングル）→ reference-to-video。参照画像がアイデンティティを固定し、プロンプトがクリップごとに変化します。

実運用のベストプラクティス

ポーリングの代わりにコールバックを使う

スクリプトの範囲を超える用途では、タスク作成時に webhook を登録してください——動画タスクは長時間かかるため、Web リクエストハンドラー内でポーリングしているといずれタイムアウトします：

{
  "model": "happyhorse-1.1/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

"when": "final" のみがサポートされています——タスクが終了状態に達すると、POST を 1 回だけ受け取ります（それ以外の値は invalid callback.when: only 'final' is supported を返します）。受信側はtaskId に基づいて冪等になるように設計してください：送信時にタスク ID を保存し、重複または処理済みのコールバックは何もしないものとして扱います。ネットワークの揺らぎでコールバックが失われた場合のフォールバックとして、低頻度のポーリングスイーパーを 1 つ残しておきましょう。

エラー処理：3 種類の失敗

1. バリデーションエラー（HTTP 400、INVALID_REQUEST）。 メッセージは非常に正確で、該当するフィールドを指し示します：

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: duration: maximum: got 99, want 15; resolution: value must be one of '720p', '1080p'"
}

2. 認証/権限エラー（HTTP 401、permission_denied）。 キーが誤っているか、キーにこのモデルへのアクセス権限がありません：

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026..."
  }
}

コンソールでキーを確認し、サポートに連絡する場合は request_id を添えてください。

3. 生成失敗（タスクの status: "fail"）。 送信は成功したが生成に失敗した場合；ポーリングまたはコールバック受信時、エラーの詳細はタスクオブジェクトの error フィールドにあります。この種のエラーはバックオフ付きのリトライに値します——バリデーションエラーや認証エラーはリトライに値しません。

コスト管理

課金は生成された動画の秒数に基づくため、duration が主要なコストレバーです——15 秒のクリップは 5 秒のクリップの 3 倍のコストがかかり、resolution の影響はより小さくなります。duration: 3 と 720p でプロンプトを反復し、その後フルレングスで最終版をレンダリングしてください。現在の料金は料金ページをご覧ください。

関連記事

• happyhorse-1.1 テキストから動画——モデルページとプレイグラウンド
• happyhorse-1.1 画像から動画——モデルページとプレイグラウンド
• happyhorse-1.1 参照から動画——モデルページとプレイグラウンド
• happyhorse-1.1 を使ったショート動画ワークフロー
• hiapi ドキュメント

よくある質問

画像とテキストプロンプトを同時に使えますか？ はい——image-to-video は必須の image_urls に加えてオプションの prompt を受け付け、reference-to-video は prompt と reference_image の両方を要求します。プロンプトのみなのは text-to-video だけです。

画像は何枚まで渡せますか？ image-to-video：ちょうど 1 枚（image_urls は上限 1 要素）。reference-to-video：reference_image に最大 9 枚。どちらもアップロードファイルや base64 ではなく、公開アクセス可能な URL の配列を受け付けます。

happyhorse-1.1 は seed、negative_prompt、audio パラメータをサポートしていますか？ いいえ。入力スキーマは厳格で、これら 3 つは 400 additional properties not allowed エラーで拒否されます。再現性が必要な場合は、プロンプトとパラメータを完全に同一に保ち、バージョン管理を手元で行ってください。

利用可能な解像度と長さは？ 3 つのエンドポイントすべて：720p または 1080p、そして 3〜15 秒（整数）。省略した場合はデフォルト値が適用されます。

有効に見えるキーを使っているのに 401 permission_denied が返るのはなぜですか？ キーは存在しますが、このモデルを使用できません——スコープ限定キーや試用キーでよくあります。コンソールでそのキーのモデル権限を確認するか、制限のない新しいキーを生成してください。

ポーリングせずに動画の準備完了を知るには？ 送信時に callback: {"url": "...", "when": "final"} を渡します。タスクが success または fail に達すると、hiapi はあなたの URL に 1 回 POST します。出力 URL は期限切れになることを忘れずに——コールバックハンドラー内でファイルをダウンロードし、ホットリンクしないでください。