チュートリアル
HiAPI API 経由で happyhorse-1.1/text-to-video を呼び出す方法:利用可能な curl と Python の例
利用可能な統合のためのリクエスト構造、非同期ポーリング、ネイティブ音声処理
このページの内容
この統合ガイドで扱う内容
本ガイドでは、HiAPI の統合 API を通じて happyhorse-1.1/text-to-video を呼び出す一連の流れを解説します。読み終える頃には、テキストプロンプトを送信し、完了までポーリングし、生成された動画とそのネイティブ音声トラックを保存する、動作するリクエストを手にしているはずです。まずはリクエスト構造を説明し、コードを書く前にリクエストペイロードを理解できるようにします。次にそのままコピーできる curl 呼び出しを示し、続いて動画生成に必要な非同期ポーリングのパターンを説明します。最後にすべてを Python に移植し、基本的なエラー処理を追加します。動画 API の経験は不要で、必要なのは HiAPI API キーと、ターミナルまたは Python 環境だけです。目的は、最小限かつ完全な統合例を提供し、それを自分のパイプラインに改変できるようにすることです。
happyhorse-1.1/text-to-video のリクエスト構造
呼び出しを行う前に、テキストから動画へのリクエストを構成するフィールドを理解しておくと役立ちます。このエンドポイントは、少なくともモデル識別子とテキストプロンプトを含む JSON ペイロードを受け取ります。その他の一般的なフィールドは出力サイズや長さを制御しますが、正確なパラメータ名と許容値は HiAPI 上のこのモデルのドキュメントに従ってください。有効なリクエストペイロードは通常、次のようになります。
{
"model": "happyhorse-1.1/text-to-video",
"prompt": "日の出の時間、カメラがゆっくりと横にパンしながら霧に包まれた森を映し出す"
}
ペイロードはフラットに保ち、モデルドキュメントに記載されたフィールドのみを使用してください。認識できないフィールドや型の誤りは、リクエストが拒否される最も一般的な原因です。不明な場合は、model と prompt だけの最小ペイロードから始め、問題を特定しながらオプションパラメータを一つずつ追加してください。
curl で最初のリクエストを送信する
ペイロードの準備ができたら、curl でタスクを送信できます。JSON ボディと Authorization ヘッダーに API キーを含めた POST リクエストを送信します。応答には通常、後でステータスをポーリングするために使用するタスクの識別子が含まれます。以下は動作する例です。
curl -X POST https://api.hiapi.ai/v1/video/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "happyhorse-1.1/text-to-video",
"prompt": "日の出の時間、カメラがゆっくりと横にパンしながら霧に包まれた森を映し出す"
}'
$HIAPI_API_KEY を実際のキーに置き換えるか、シェルでエクスポートしてください。応答は JSON で、id フィールド(または同様の名前の識別子)と、タスクが受け付けられたことを示すステータスが含まれます。応答を注意深く読み、ステータスが受け付け済みでない場合は、続行する前にエラーメッセージを確認してください。この時点で動画が準備できていると仮定しないでください。タスクはちょうどキューに入ったばかりです。
非同期ポーリングを処理する
動画生成は即時には完了しないため、HiAPI は最初の応答で最終的な動画ではなくタスク識別子を返します。タスクが終了状態に達するまで、ステータスエンドポイントをポーリングする必要があります。一般的なパターンは、タスクを送信し、ID を取得し、短い間隔でタスクステータスを繰り返し要求することです。ステータスが成功または失敗を示したら停止します。以下は擬似コード形式のロジックです。
- タスクを送信し、タスク
idを読み取る。 - 数秒待つ。
- その
idを使用してタスクステータスを要求する。 - ステータスが「completed」または「succeeded」の場合、出力 URL を取得してループを終了する。
- ステータスが「failed」の場合、エラーを記録して終了する。
- それ以外の場合は、再び待機して繰り返し、妥当な最大試行回数に達するまで続ける。
ポーリングを頻繁に行いすぎないでください。動画タスクの場合、各試行の間に数秒の間隔を空けるのが通常は十分です。また、単一のブロッキング応答に最終的な動画が含まれることを期待しないでください。非同期モデルは意図的に設計されており、長時間実行されるすべての生成タスクで一貫しています。
出力に含まれるネイティブ音声
happyhorse-1.1/text-to-video で生成された動画には、出力にネイティブ音声が含まれています。タスクが完了すると、応答は生成された動画ファイルを指し、そのファイルにはすでに音声トラックが含まれています。音声を個別に生成したり取得したりする必要はありません。結果を保存して検証するには、提供された URL から動画ファイルをダウンロードし、そのコンテナ形式を維持してください。ファイルをプログラムで処理する場合は、メディアツールを使用してファイルを検査するなどして、音声ストリームが存在することを確認してください。下流のパイプラインで要求されない限り、音声を削除したり再エンコードしたりしないでください。品質が低下したり、音声トラックが完全に失われたりする可能性があります。返されたファイルは完全な視聴覚アセットとして扱ってください。
Python で同じリクエストを送信する
curl 呼び出しを Python に移植するのは簡単です。同じ JSON ペイロードを再利用し、ポーリングループを追加します。以下の例では requests を使用し、各試行の間に待機し、失敗時に例外をスローします。エンドポイントパスとステータスフィールド名は、HiAPI 上の happyhorse-1.1/text-to-video のドキュメントに記載されている内容に置き換えてください。
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "happyhorse-1.1/text-to-video",
"prompt": "日の出の時間、カメラがゆっくりと横にパンしながら霧に包まれた森を映し出す",
}
resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
for attempt in range(60):
status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
status_resp.raise_for_status()
status = status_resp.json()
state = status.get("status")
if state in ("completed", "succeeded"):
video_url = status["output"]["url"]
print("動画の準備ができました:", video_url)
break
if state == "failed":
raise RuntimeError(status.get("error", "生成に失敗しました"))
time.sleep(5)
else:
raise TimeoutError("ポーリングがタイムアウトしました")
これは前述の「完了までポーリングする」ロジックに従っています。raise_for_status() を使用して HTTP エラーを早期に表面化させ、不要なリクエストを避けるために妥当なスリープ間隔を維持してください。
よくある障害のトラブルシューティング
統合に関する問題のほとんどは、いくつかのカテゴリに分類できます。model フィールドの欠落や誤った JSON 型など、ペイロードの形式が誤っている場合は即座に拒否されます。JSON をモデルドキュメントと照合して慎重に確認してください。ポーリングが頻繁すぎると、レート制限や不要な負荷を引き起こす可能性があります。スリープ間隔を広げてください。最初の応答を最終的な動画と誤解するのも、よくある間違いです。必ず終了状態までポーリングしてください。認証エラーは通常、Authorization ヘッダーの欠落または形式の誤りを意味するため、API キーが正しくエクスポートされているか確認してください。最後に、ポーリング後にタスクが失敗した場合は、ステータス応答のエラーメッセージを確認してください。通常、無効なプロンプトやサポートされていないパラメータを示しています。これらを修正した後、最小限の有効なペイロードで再試行してください。