チュートリアル
HiAPI API で gemini-omni-flash/text-to-video を使う方法:curl と Python ガイド
このページの内容
このエンドポイントの役割と使用すべき場面
gemini-omni-flash/text-to-video は HiAPI 上の生成エンドポイントで、テキストプロンプト——必要に応じて先頭フレーム画像をアンカーとして指定——を短い動画に変換します。リクエストを送信すると HiAPI はポーリング可能なタスクを返し、タスク完了後にダウンロードまたはストリーミング再生できる動画 URL が得られます。
このエンドポイントは以下の場面に適しています:
- 素早いコンセプト動画。 1〜2 文の説明から短いマーケティング予告、絵コンテプレビュー、SNS 用トランジション素材を直接生成します。
- 画像で導く動き。 静止画——製品写真、キャラクターデザイン、イラスト——がすでにあり、ゼロから生成するのではなく、それを動かしたい場合。
- パイプラインでのバッチ生成。 生成は非同期のため、バックエンド worker から大量のタスクを一度に投入し、後で結果を収集できます。リクエスト接続を保持する必要はありません。
長尺動画、フレーム単位の正確な編集、特定ショットの決定論的な再現には向いていません。高速な生成ドラフトと捉えてください:反復コストが低く、レビューに十分で、エンドツーエンドでスクリプト化できます。
以下のすべては同じ HiAPI インターフェース——1 つの API key、1 つのベース URL、1 つのリクエスト構造——を通ります。そのため、ここで書くコードは認証やポーリングを学び直すことなく、他の生成エンドポイントへ移行できます。
最初のリクエストを送る前に
初回呼び出しを成功させる前に、4 つ準備が必要です。
1. API key
HiAPI アカウントで key を作成し、ソースコードではなく環境変数に保存します:
export HIAPI_API_KEY="your_key_here"
2. ベース URL とエンドポイントパス
すべてのリクエストは HiAPI ベース URL に送信され、モデル識別子はパスに含まれます。コードではベース URL を単一の定数として扱い、一箇所だけ変更すれば済むようにします:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. JSON リクエストボディ
リクエストは POST で、Content-Type: application/json を付け、Authorization ヘッダーに bearer token を載せます。先頭フレーム画像を URL で提供する場合を除き、フォームエンコードも multipart アップロードもありません。
4. 先頭フレーム画像(任意)
画像で生成を導く場合は、まず公開 HTTPS URL でアクセスできることを確認してください。ローカルファイルシステムのパスは使用できません——API はサーバー側で画像を取得します。
コスト意識に関する実用的なヒント:このエンドポイントは生成した出力に応じて課金されます——解像度ティアとクリップの長さがどちらも影響します。現在の単価は HiAPI の料金パネルで確認してください。バッチタスクを拡大する前にそこで確認しましょう。重要な習慣は、まず最小設定でプロトタイプを作り、プロンプトが望む効果を生み出せるようになってから設定を上げることです。
生成リクエストの構築
リクエストは概念的には 3 つの部分で構成されます:モデルパス、プロンプト(および任意の画像)、生成オプションです。構造は次のとおりです:
{
"prompt": "ガラスのコーヒーカップにゆっくりドリーインし、湯気が立ち上る、朝の光、浅い被写界深度",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}
プロンプト
prompt フィールドはショットの説明を担います。監督のメモのように書いてください:被写体、カメラワーク、光、雰囲気。具体的な動きの動詞(「slow dolly-in」「camera pans left」「steam curls upward」)は、単に形容詞を並べるよりも確実に結果を導きます。
任意の先頭フレーム
image フィールドは任意です。省略すると、モデルはテキストのみからクリップ全体を生成します。含めると、クリップはそのフレームから始まり、プロンプトはその後に何が起こるべきかを記述します。これは一貫性に最も大きく影響するレバーです:テキストのみのプロンプトは実行ごとにシーンを再構想しますが、先頭フレームを固定すると複数回の反復でも構図が安定します。
両方を提供する場合は、それらが一致していることを確認してください。砂漠の風景の先頭フレームに、雨の都市の街路についてのプロンプトを合わせると、混乱した結果になります——モデルは相反する 2 つの指示を調和させなければなりません。
オプションの配置場所
resolution、duration、audio は prompt、image と同じ JSON ボディのトップレベルに置きます。ネストされた options オブジェクトを覚える必要はありません。リクエストボディはフラットで読みやすく保ちましょう——バッチタスクのデバッグ時にログ記録とリクエスト差分の比較がずっと容易になります。
解像度と長さの選択
2 つのパラメータが出力の見た目とタスクコストの両方を左右します:解像度ティアとクリップの長さです。
解像度ティア
HiAPI はこのエンドポイントを複数の解像度ティアで公開しています。低いティアはプロンプト開発段階の適切なデフォルトです——レンダリングが速く、捨てる予定の細部にコストをかけずに文言を反復できます。プロンプトが望む構図を確実に生み出せるようになったら、最終レンダリングのためにティアを上げます。
実用的なワークフロー:
- 最低ティアでプロンプトを起草する。
- 2〜3 のバリエーションを生成して比較する。
- プロンプトを確定し、より高いティアで再レンダリングする。
クリップの長さ
長さは秒単位で指定し、このエンドポイントは短いクリップ向けに設計されています。長さは控えめに保ちましょう:短いクリップは個々のタスクが速く、失敗時の再試行コストも低く、後でより長いシーケンスが必要になったら複数のクリップを連結できます。1 つのショットに 8 秒の画面時間が必要なら、4 秒の生成を 2 回行う方が、長い 1 回の生成よりも通常は制御しやすいです。
予算への対応方法
このエンドポイントは生成した出力に応じて課金されます——解像度が高く、長さが長いほど、1 タスクあたりの課金対象出力が増えます。料金は生成単位で計算され、ティアは時間とともに変わるため、期待値をハードコードするのではなく、HiAPI の料金パネルにある最新の数字を読んでください。どの価格変動でも成り立つ計画ルール:予想タスク数に出力規模を掛け、最小設定でプロトタイプを作り、最後に解像度を拡大します。
ネイティブ音声の制御
audio フラグは、返される動画に映像と一緒に生成されたネイティブ音声トラックを含めるかどうかを決めます。
{
"prompt": "トタン屋根を叩く雨音、ドアがゆっくりと軋みながら開く",
"audio": true
}
有効にすると何が変わるか
audio: true の場合、モデルはプロンプトで描写されたシーンに合う音——環境音、環境の質感、動作を示唆する音のイベント——を生成します。出力動画には音声ストリームが付属するため、ダウンロードしたファイルはすでに完全で、別途の効果音処理は不要です。
無効にすると何が変わるか
audio: false の場合、無音の動画が得られます。次のような場合に適しています:
- エディタでクリップに独自の音楽やナレーションを重ねる。
- そのクリップがより大きな合成作品の背景要素である。
- 映像だけを反復し、音声生成をループに含めたくない。
音声のためのプロンプトの書き方
音声を有効にする場合は、映像と同じようにサウンドスケープを描写してください。プロンプト内の音の手がかり——雨音、足音、機械音、特定の部屋の雰囲気——が音声モデルの根拠になります。純粋に視覚的なプロンプトでも音声は生成されますが、ショットに合った音ではなく汎用的な環境音になります。
早めにテストする価値のある注意点:音声はクリップの性格を大きく変えます。同じプロンプトをフラグのオンとオフでそれぞれ生成し、両方を見て、それを中心にバッチタスクを構築する前にプロジェクトが実際にどちらのモードを必要とするか決めてください。
非同期タスクのライフサイクルの扱い
動画生成は通常の HTTP リクエストを開いたままにすべき時間より長くかかるため、このエンドポイントは非同期です。各呼び出しは同じ 3 ステップのループに従います。
ステップ 1:送信
JSON ボディをエンドポイントに POST します。送信が成功すると、すぐにタスク識別子——通常はタスク id——と、タスクがキューに入ったまたは処理中であることを示すステータスが返ります。この時点ではまだ何もレンダリングされていません。
ステップ 2:ポーリング
タスク id を取得し、一定間隔でタスクステータスエンドポイントを問い合わせます。各ポーリングは現在のステータスを返します:queued、processing、completed、failed の 4 つすべてを処理する必要があります。単純な指数バックオフ——約 2 秒から始め、間隔に上限を設ける——により、長いタスクで API を叩き続けるのを避けつつ、短いタスクは素早く捕捉できます。
ステップ 3:取得
ステータスが完了を報告すると、レスポンスは完成した動画の URL とそのタスクのメタデータを含みます。ダウンロードするか、保存するか、URL をフロントエンドに渡します。ステータスが失敗を報告した場合は、レスポンスからエラー情報を取得し、プロンプトを修正して再試行するか、失敗をそのまま surface するかを決めます。
組み込むべきガードレール
- タイムアウト上限。 総ポーリング時間を制限し(例:数分)、無限ループではなく自分のコードでタスクを失敗としてマークします。
- 最大ポーリング回数。 ステータスがいつまでも不明確な場合の暴走ループを防ぎます。
- タスク id の永続化。 受け取ったらすぐにデータベースやログに書き込みます。プロセスがポーリング途中でクラッシュしても、再生成して二重に課金されるのではなく、復旧できます。
- 冪等な送信。 最初のリクエストが失敗したことを確認する前に、ネットワークの揺らぎで再送信しないでください。重複タスクは実際の出力を消費します。
このループを一度正しく作れば、HiAPI のすべての非同期エンドポイントに適用できます。
実行可能な curl と Python の例
curl:送信、ポーリング、取得
環境変数から key とベース URL を設定し、送信します:
curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "ガラスのコーヒーカップにゆっくりドリーインし、湯気が立ち上る、朝の光、浅い被写界深度",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}'
レスポンスにはタスク id が含まれます。レスポンスからステータスエンドポイントを取得してポーリングします:
curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
-H "Authorization: Bearer $HIAPI_API_KEY"
ステータスが completed になるまで繰り返し、レスポンスボディから動画 URL を取り出してダウンロードします:
curl -sS -o clip.mp4 "<VIDEO_URL>"
Python:同じループをラップする
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
def generate_video(prompt, image_url=None, resolution="720p",
duration=5, audio=False, timeout=300):
payload = {
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"audio": audio,
}
if image_url:
payload["image"] = image_url
resp = requests.post(
f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
headers=HEADERS, json=payload, timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["id"]
print(f"submitted: {task_id}")
deadline = time.time() + timeout
interval = 2
while time.time() < deadline:
status_resp = requests.get(
f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
)
status_resp.raise_for_status()
data = status_resp.json()
state = data.get("status")
if state == "completed":
return data["video_url"]
if state == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
interval = min(interval * 1.5, 10)
raise TimeoutError(f"job {task_id} did not finish in {timeout}s")
if __name__ == "__main__":
url = generate_video(
"ガラスのコーヒーカップにゆっくりドリーインし、"
"湯気が立ち上る、朝の光、浅い被写界深度",
)
print("video ready:", url)
このスクリプトはテキストのみのタスクを送信し、バックオフ付きでポーリングし、タイムアウト上限を強制し、完成した URL を返します。image_url= を渡すと生成を先頭フレームに固定でき、audio=True を設定するとネイティブ音声を含められます。ここから generate_video を worker キュー、FastAPI ルート、バッチループに組み込めます——この関数は自己完結しており、生成したタスク id 以外に状態を持ちません。
よくある失敗点と回避方法
失敗する統合のほとんどは、次の 5 つの問題のいずれかに陥ります。
送信時に無効なパラメータで拒否される
最も一般的な原因は API がリクエストボディを解析できないことです:prompt の欠落、サポート範囲外の長さ、サポートされない解像度文字列など。エンドポイントリファレンスで許容値を確認し、ローカルで先に検証してください。呼び出し前に許容値をアサートする小さなツールがあれば、1 往復と混乱するエラーを節約できます。
先頭フレーム画像にアクセスできない
API はサーバー側で image を取得するため、ブラウザでは動く URL でも失敗することがあります——プライベートバケット、期限切れの署名付きリンク、ホットリンク防止が原因になります。公開読み取り可能な HTTPS URL を使い、送信前にあなたのネットワーク外から解決できることを確認してください。
ポーリングを諦める
同じ誤りの 2 つの変種:最初の processing レスポンスで諦めて失敗と見なす、またはポーリングが攻撃的すぎてレート制限に達する。上で示した上限付きバックオフループで両方を解決します:計画どおりにポーリングし、非終端状態は正常と見なし、明示的な失敗またはタイムアウト時のみ例外を投げます。
タスク id を失う
送信後、結果を保存する前にプロセスが停止すると、タスクは課金済みなのにアクセスできません。送信後すぐにタスク id を永続ストレージに書き込み、起動時に進行中の id が残っていないか確認してから新しいタスクを送信してください。
スケール時に出力が過大になる
高解像度・長尺で大量に生成すると出力量が急速に膨らみ、生成ファイルはストレージコストが高く配信も遅くなります。小規模でプロトタイプを作り、最終レンダリングは 1 回だけ行い、ストレージのライフサイクルルールを整えておきましょう。課金は生成出力に連動するため、最も安価な修正はほとんどの場合、より小さなプロトタイプ反復ループです。
ステージング環境でこのチェックリストを一通り確認すれば、本番経路はスムーズになります。