チュートリアル
HiAPI API で gemini-omni-1.1-flash を呼び出す方法:curl と Python ガイド
このページの内容
最初のリクエストの前に用意するもの
コードを書く前に、4つの点を確認してください。どれもデバッグの往復を1回節約してくれます。
API キー
HiAPI へのすべてのリクエストは API キーで認証する必要があります。アカウントのコンソールでキーを生成し、ソースコード管理に含まれないようにしてください。以下のサンプルでは環境変数から読み込むため、キーがシェルの履歴やコミットされたファイルに現れることはありません:
export HIAPI_API_KEY="your_key_here"
ベース URL とエンドポイントパス
ベース URL はすべての HiAPI モデルで共通で、変わるのはモデル識別子だけです。エンドポイントパスとリクエストメソッドはブログ記事からコピーするのではなく、API リファレンスドキュメントから取得してください。パスはバージョン付きで変更される可能性があるためです。ベース URL はクライアント内の定数にしておけば、将来の変更は1行の修正で済みます。
モデル識別子
gemini-omni-1.1-flash はリクエストのペイロード内に文字列として渡します。正確にコピーしてください。ハイフンとバージョン接尾辞が重要です。タイプミスがあると、通常はルーティング失敗ではなくバリデーション失敗になるため混乱しやすいです。後述のデバッグの章を参照してください。
モデルページをブックマークする
gemini-omni-1.1-flash モデルページは、どのパラメータがあり、どの値を受け付け、レスポンス構造がどうなっているかを判断するための信頼できる情報源です。一度読んで終わりにするのではなく、変更のたびに確認するリファレンスとして扱ってください。
この4つが揃えば、呼び出しを開始できます。
curl で最小限のリクエストを送信する
できるだけ小さなリクエストから始めましょう。目的は良い結果を出すことではなく、キー、エンドポイント、ペイロード構造が正しく対応していることを証明することです。一度通れば、以降の変更はすべて増分的なものです。
curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "木製のテーブルの上の陶器のカップにゆっくりとカメラを寄せていく、柔らかな朝の光"
}
}'
各部分の意味は以下の通りです:
- メソッドと URL —— この呼び出しは
POSTで、API リファレンスドキュメントから取得したエンドポイントパスの前にベース URL を結合したものです。 Authorizationヘッダー —— bearer トークンを運びます。ここで変数が欠落しているか空であることが、401 の最も一般的な原因です。Content-Typeヘッダー ——application/jsonである必要があります。これがないと、サーバーがリクエストボディをまったく解析しない可能性があります。model—— 正確なモデル識別子の文字列。input—— 生成パラメータを含むオブジェクト。プロンプトはここに置きます。解像度と長さもここに追加します(詳細は後述)。
呼び出しが最終出力ではなくタスク識別子や受理済み状態のレスポンスを返した場合、それは正常です。生成は非同期です。その識別子を保存しておいてください。ポーリングのステップで使用します。
同じ呼び出しを Python に移植する
Python 版はまったく同じ JSON リクエストボディを送信する必要があります。ペイロードを一致させておくことで、この移植が信頼できるものになります。curl が成功して Python が失敗する場合、問題は API の理解ではなく Python コードにあります。
import json
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "木製のテーブルの上の陶器のカップにゆっくりとカメラを寄せていく、柔らかな朝の光"
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())
すぐに身につけるべき習慣がいくつかあります:
- URL は定数で構築する。コードのあちこちに文字列連結を散らかさないこと。
- 明示的なタイムアウトを設定する。 設定しないと、ハングしたリクエストがワーカープロセスを無期限に停止させる可能性があります。
raise_for_status()を呼び出す。これによりエラーレスポンスが例外として表面化し、成功レスポンスのボディとして静かに解析されることがなくなります。json.dumpsでシリアライズする。フォームエンコーディングに依存しないこと。後者はネストされたinputオブジェクトを正しく生成できません。
動作すれば、再利用可能なリクエスト構造が手に入ります。次の2つの節では、出力を実際に制御するパラメータを追加します。
リクエストで解像度と長さを設定する
解像度と長さは input オブジェクト内の通常のフィールドで、プロンプトと並びます。概念的にはペイロードは次のようになります:
{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "...",
"resolution": "<supported-value>",
"duration": "<supported-value>"
}
}
重要なルール:記憶や数か月前に読んだチュートリアルに基づいてこれらの値をハードコードしないでください。 サポートされる値はモデルの更新に伴って変わり、サポートされていない値を渡すとペイロードエラーのように見えるバリデーションエラーが発生します。設定する前に、常にモデルページで現在受け付けられている値を確認してください。
実用的なパターン
値をコードではなく設定に置きます:
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": prompt,
"resolution": settings.resolution,
"duration": settings.duration,
},
}
これには3つの利点があります。ロジックを変えずに出力品質を調整できます。開発中は安価な低解像度テストを実行し、最終レンダリング時だけ品質を上げることができます。プラットフォームが新しいサポート値を追加したとき、コードベースを探し回るのではなく、設定フィールドを1つ変更するだけで済みます。
さらに2つの見落としやすい落とし穴を指摘しておきます。第一に、解像度と長さは通常コストと関連します。課金は通常産出量に連動するため、より長く高解像度のクリップは無料ではありません。第二に、フィールドがオプションの場合、空文字列や null を送信するのではなく省略してください。一部のバリデータは、フィールド自体がオプションであっても明示的な null を拒否します。
非同期生成を扱う:まず送信し、次にポーリングする
生成には時間がかかるため、API は送信してからポーリングするパターンを採用しています。クライアントはこれらを、異なるリトライセマンティクスを持つ2つの独立した操作として扱う必要があります。
ステップ1:送信
送信呼び出しは、すでに構築したリクエストです。タスクの識別子を返します。エンドポイントによってはタスク ID、task ID、または同様のフィールドです。防御的に解析してください:
created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier in response: {created}")
ステップ2:ポーリング
次にその識別子でステータスエンドポイントをポーリングし、タスクが終端状態に達するまで待ちます。堅牢なループには4つの特性があります:最大待機時間、バックオフ、終端状態のチェック、失敗のチェックです。
import time
def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
deadline = time.time() + timeout
delay = initial_delay
while time.time() < deadline:
status = fetch_status(job_id) # GET on the status endpoint
state = status.get("status")
if state in ("succeeded", "completed"):
return status
if state in ("failed", "error", "cancelled"):
raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
time.sleep(delay)
delay = min(delay * 2, max_delay)
raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
なぜこれらの細部が重要なのか
- 指数バックオフにより、レンダリングに1分かかりまだキューにあるタスクに対して、ステータスエンドポイントを絶えず叩き続けることを避けられます。
- 厳格な締め切りにより、ハングしたタスクがワーカープロセスを永久にブロックすることを防ぎます。タイムアウト時はタスク ID を記録し、手動で確認できるようにしてください。
- 明示的な終端状態により、予期しない状態で無限ループに陥ることがなくなります。未知の状態は「待機継続」として扱いますが、一度ログに記録します。
- 分離されたリトライ戦略:送信呼び出しのリトライはステータス呼び出しのリトライよりもリスクが高く、重複タスクを作成する可能性があります。ポーリングは安心してリトライできます。送信は明確な転送エラーの場合にのみリトライしてください。
よくある障害モードのトラブルシューティング
ほとんどの障害は少数のカテゴリに分類されます。後の症状はしばしば前の問題によって引き起こされるため、この順序で調査してください。
認証エラー
症状: 401 または 403。
最初に確認すること: キーは実際にプロセスが実行されている環境に存在しますか? len(API_KEY) を出力すると、変数が設定されていないために bearer トークンが空になる典型的なケースを捕まえられます。次に、ヘッダー形式が Bearer <key> で、スペースが1つだけであること、キーが取り消されていないか別のプロジェクトに限定されていないことを確認してください。
ペイロード形式エラー
症状: 400 で、リクエストボディや不足フィールドについての苦情。
最初に確認すること: リクエストボディを動作する curl リクエストと比較してください。よくある原因には、Content-Type: application/json ヘッダーの欠落、JSON ではなくフォームエンコードデータの送信、API がネストを期待しているのに input オブジェクトがフラットになっている(またはその逆)、そして意図しない型変換(数値型の duration を引用符付き文字列として送信するとバリデーションに失敗する可能性があります)。
サポートされていないパラメータ値
症状: 400 または 422 で、resolution や duration などの特定のフィールドを名指し。
最初に確認すること: モデルページ。現在サポートされている値が記載されています。これはほぼ常に古いハードコード値であり、コードの欠陥ではありません。以前は動作していた値が今失敗する場合、サービス障害を疑う前に、まずモデルが更新されたと仮定してドキュメントを読み直してください。
モデル識別子のスペルミス
症状: プロンプトに言及のないバリデーションエラーまたは見つからないエラー。
最初に確認すること: model 文字列を出力し、ドキュメントと1文字ずつ比較してください。末尾の余分なスペースやバージョン番号の逆転は見落としやすいです。
タイムアウトと一時的障害
症状: 接続タイムアウト、429、または 5xx レスポンス。 最初に確認すること: タイムアウトを設定しましたか? タイムアウトを追加し、429 と 5xx にのみバックオフ付きの有界リトライを追加してください。429 以外の 4xx エラーはリトライしないでください。リクエストは毎回同じように失敗します。長時間タスクの場合、最終結果はポーリングで取得されることを覚えておいてください。送信呼び出しのタイムアウトは生成の失敗を意味しません。
技術的には有効だが結果が正しくない
リクエストは成功したが出力が期待に達しない。これは API の問題ではなくプロンプトの問題です。プロンプトを被写体、カメラワーク、照明、リズムについて具体的にし、差異を帰属できるよう一度に1つの変数だけを変更してください。
再利用可能なクライアント関数にカプセル化する
カプセル化の目標はシンプルです:ビジネスロジックにモデル識別子、パラメータ名、ポーリングループを含めないこと。モデル関連の詳細はすべて1か所に集中させます。
def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
payload = {
"model": "gemini-omni-1.1-flash",
"input": {"prompt": prompt},
}
if resolution is not None:
payload["input"]["resolution"] = resolution
if duration is not None:
payload["input"]["duration"] = duration
created = post_json(ENDPOINT, payload)
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier: {created}")
return wait_for_job(job_id, timeout=timeout)
これがもたらすもの
- モデルの切り替えは1行で済む。 新しいモデルが登場したら、定数とデフォルト引数を変更するだけです。呼び出し側は影響を受けません。
- オプションパラメータが正しく処理される。 省略された値は送信されないため、前述の null 拒否の問題を回避できます。
- ポーリングは呼び出し元から見えない。 呼び出し元は結果を取得するか例外を取得するかのどちらかで、自分で管理する必要のあるタスク ID を取得することはありません。
- テストが容易になる。
post_jsonとwait_for_jobをそれぞれスタブ化し、ペイロード構築とポーリングロジックを分離してテストできます。
階層化された構成
構造はフラットで明確に保ってください:トランスポート層(HTTP、ヘッダー、タイムアウト、リトライ)、モデル層(gemini-omni-1.1-flash のペイロード構築)、タスク層(送信とポーリング)。単一の generate_video 関数がそれらを組み合わせ、各層は問題発生時に推論しやすいよう十分小さくします。
まず curl で接続設定を確認し、次に Python で実際の作業を行い、パラメータが変わったときはいつでもモデルページを読み、ポーリングループをインターフェースの背後に置いてアプリケーションコードに漏れないようにしてください。