HiAPI API で gemini-omni-1.2-flash を使う方法：curl と Python

gemini-omni-1.2-flash のリクエストはどのような形か

最初のコードを書く前に、gemini-omni-1.2-flash の呼び出しが HiAPI 上で具体的に何で構成されているかを理解しておくと役立ちます。送信するリクエストはすべて JSON オブジェクトで、単一のエンドポイントに送られ、HiAPI の API キーで認証されます。この構造はモデル間で一貫しているため、一度このモデルで身につければ、他のモデルでも同じパターンを再利用できます。

高レベルで見ると、リクエストは 4 種類の情報を含みます：

• モデル識別子 —— 文字列 gemini-omni-1.2-flash で、HiAPI にタスクをどのモデルへルーティングするかを伝えます。
• 入力 —— モデルに処理してほしい内容。対象のモダリティに応じて、プロンプトまたは構造化入力フィールドとして表現されます。
• 生成パラメータ —— duration や解像度など、出力を形作るオプション。これらは本ガイドの後半で調整するつまみです。
• リクエストメタデータ —— プラットフォームがタスクを識別・追跡するために必要な情報。たとえば関連付けに使えるクライアント側の参照など。

レスポンス構造

レスポンスも同様に予測可能です。同期呼び出しは結果フィールドに直接結果を返します。非同期呼び出しはタスクハンドル——状態を問い合わせ、最終的に出力を取得するための識別子——を返します。この 2 つのどちらを扱っているのかを早めに把握しておけば、後のデバッグ時間を大幅に節約できます。

なぜ構造が重要なのか

初回統合の失敗のほとんどはリクエスト構造に起因します：フィールドの欠落、パラメータの型の誤り、あるいは呼び出しが同期だと勘違いして実際はそうでないこと。コードを書く前にこの解剖学を内面化しておけば、後続の curl と Python の例は呪文ではなく、ただの素直な翻訳になります。

実用的な習慣：送信する正確な JSON ボディを変数かファイルに保存しておきましょう。エラーが起きたとき、記憶から再構築するのではなく、実際に何を送ったのかを見られるようにするためです。

1 行で完了する認証

すべてのリクエストは認可ヘッダーに API キーを含みます。キーは機密として扱いましょう：ハードコードせず環境変数から読み込み、バージョン管理にコミットしないこと。この 1 つの規律だけで、API 統合で最もよくあるセキュリティミスを避けられます。

curl で最初の動作するリクエストを送る

キー、エンドポイント、リクエスト構造が正しいことを確認する最速の方法は curl 呼び出しです。これにより、あなたと API の間の抽象化レイヤーがすべて取り除かれるので、これが動けば問題（あるとすれば）は環境設定ではなくコードにあると分かります。

ステップ 1：キーを保存する

HiAPI の API キーを環境変数に置き、シェル履歴や共有スクリプトに現れないようにします：

export HIAPI_API_KEY="your_key_here"

ステップ 2：リクエストボディを組み立てる

JSON ボディをファイルに書き出します。これにより curl コマンドが読みやすく保たれ、再利用可能な成果物が得られます：

cat > request.json <<'EOF'
{
  "model": "gemini-omni-1.2-flash",
  "input": {
    "prompt": "モデルに生成してほしい内容を記述してください。"
  },
  "parameters": {
    "duration": 5,
    "resolution": "720p"
  }
}
EOF

具体的なパラメータ値はユースケースに依存します；ここで重要なのは構造です。最初の呼び出しでは duration と resolution を控えめにしておけば、パイプラインが動くというシグナルを素早く低コストで得られます。

ステップ 3：送信する

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

ステップ 4：レスポンスを読む

リクエストが同期であれば、レスポンスボディに生成結果が表示されます。非同期であれば、タスクハンドル——タスク ID と状態フィールド——を受け取ります。この ID を控えておきましょう；ポーリング時に必要になります。

ターミナルが対応していれば、出力を JSON フォーマッタに通すか、ファイルに保存して詳しく確認します：

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json > response.json

ステップ 5：拡張する前に確認する

この素の呼び出しが成功し、出力を読めるようになるまで、duration、解像度、バッチ処理の調整を始めないでください。最初の成功したリクエストがあなたのベースラインであり、それ以降のすべてはそれと比較できる増分変更です。

呼び出しを Python に移植する

curl が動いたら、Python への移植は機械的な作業です。目標は、リクエストを正確に鏡写しにする小さく読みやすいクライアントを書くことです。そうすれば Python 呼び出しが失敗したときに、curl 版とフィールドごとに diff できます。

最小クライアント

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/generate"

payload = {
    "model": "gemini-omni-1.2-flash",
    "input": {
        "prompt": "モデルに生成してほしい内容を記述してください。"
    },
    "parameters": {
        "duration": 5,
        "resolution": "720p"
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=60)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

注意すべきポイント

• json=payload は辞書を自動的にシリアライズします。だからこそボディは手で組み立てた文字列ではなく curl ファイルと一致します。
• raise_for_status() は非 2xx レスポンスを例外に変えるので、失敗はすぐに表面化し、後で結果として解析しようとするエラーボディを黙って返すことはありません。
• timeout=60 は接続が停滞したときにスクリプトが無限にハングするのを防ぎます。生成にどれくらいかかる見込みかに応じて値を選びましょう。

2 つのレスポンス構造を扱う

呼び出しは結果またはタスクハンドルのどちらかを返す可能性があるため、どちらか一方を仮定せずレスポンスを分岐させます：

if "job_id" in data:
    print("非同期タスクを開始しました：", data["job_id"])
else:
    print("結果の準備ができました")

この小さなチェックが、両モードで動くクライアントと、プラットフォームが初めてタスクを非同期で実行すると判断したときにクラッシュするクライアントの差になります。

関数にまとめる

呼び出しをプロンプト、duration、解像度を引数に取る関数に包みましょう。そうすれば調整を始めるときに、異なるパラメータで同じコードを走らせるのが容易になり、リクエスト構造は 1 か所だけで定義されます。

非同期タスクと結果のポーリング

gemini-omni-1.2-flash のリクエストの中には、インラインで結果を返せるほど速く完了するものもあります。他のものはより長くかかり、HiAPI は代わりにタスクハンドルを返します。統合は両方のケースを扱う必要があり、非同期パスこそが最も壊れやすいクライアントが崩れる場所です。

非同期レスポンスを識別する

非同期レスポンスにはタスク識別子と状態が含まれます。得られるのは完成した出力ではなく、仕事が受け付けられ処理されるという約束です。あなたの仕事は後で確認しに戻ることです。

正しくポーリングする

素朴な方法——タイトな while True ループで状態エンドポイントを連打する——には 2 つの悪い点があります：レート制限の予算を浪費し、結果を早く得られないのにプラットフォームに不要な負荷をかけます。

より良いパターンは上限付きの間隔バックオフを使います：

import time

def poll_job(job_id, base_delay=1.0, max_delay=10.0, max_wait=300.0):
    elapsed = 0.0
    delay = base_delay
    while elapsed < max_wait:
        status = get_job_status(job_id)
        if status["state"] == "succeeded":
            return status
        if status["state"] == "failed":
            raise RuntimeError(status.get("error", "job failed"))
        time.sleep(delay)
        elapsed += delay
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"job {job_id} did not finish in time")

ポーリングの 3 つのルール

• 小さく始め、ゆっくり増やす。 短い初期間隔は速いタスクを低コストで捕捉し、上限まで倍々に増やせば遅いタスクを過剰に頻繁にチェックせずに済みます。
• 常に最大待機時間を設定する。 これがないと、詰まったタスクがプロセスを永久にハングさせます。例外を投げるタイムアウトは、黙ってハングするよりはるかに優れています。
• 成功、失敗、保留を区別する。 ループを止めるべきはそのうち 2 つだけで、結果を返すべきは 1 つだけです。

利用可能なら webhook を優先する

負荷が高い場合、タスクごとのポーリングはスケールしません。HiAPI が完了コールバックを提供している箇所では、繰り返し問い合わせるのではなくそれを使って結果を受け取りましょう。インタラクティブなツールや低量のスクリプトには、バックオフ付きポーリングで十分です。

いずれにせよ、タスクハンドルを仕事の永続的な識別子として扱いましょう。保存し、記録し、後で結果を照合するために使いましょう。

duration と解像度を選ぶ

duration と解像度は出力に最も直接影響する 2 つのパラメータであり、請求額と待ち時間にも影響します。どちらにも唯一の正しい値はありません；正しい選択は何を構築しているかによります。重要なのは、例から数値をコピーするのではなく、意識的に選ぶことです。

duration

duration は生成出力の長さを制御します。より長い duration はより多くの内容を与えますが、生成により多くの計算資源を要し、遅延とリクエストの課金方法（出力の長さに基づく課金）の両方に影響します。実用的な指針：

• テスト時は短く始める。 短い duration は、各イテレーションで時間を浪費せずにパイプラインが端から端まで動くことを証明します。
• duration を用途に合わせる。 プレビューやサムネイル用の短いクリップには、完全な成果物の長さは不要です。
• 投機的に長くしない。 実際に使う長さだけ生成しましょう；後からトリミングしても何の得にもなりません。

解像度

解像度は出力の忠実度を制御します。より高い解像度はより多くの詳細と大きなペイロードを意味し、処理時間とコストが相応に増えます。トレードオフ：

• プレビューやドラフト作業 に高い解像度は不要——それは正しさの確認であり、最終製品ではありません。
• 最終成果物 には、特に出力がフルサイズで表示される場合、より高い設定がふさわしいかもしれません。
• 帯域幅とストレージ も重要です：高解像度の出力は転送も保持も重くなります。

一度に 1 つの変数だけ調整する

パラメータを調整するときは、一度に 1 つだけ変え、ベースラインの curl 呼び出しと比較しましょう。duration と解像度を同時に変えると、品質、遅延、コストの変化をどちらに帰属させるか分からなくなります。テストした設定と観察された挙動を記録する小さなマトリクスを維持しましょう。

コストを数値ではなく関数として考える

料金はサイトの料金パネルにあるため、コストを関数として捉えましょう：総コストは出力の長さに比例し、より高い解像度では最終出力サイズと処理量にも比例します。あなたの仕事はどのパラメータがその関数を動かすかを知り、本番量を約束する前に現在の料金を確認することです。そうすれば価格が変わっても見積もりは正しく保たれます。

よくあるエラーとその修正方法

初回統合の失敗のほとんどは少数のカテゴリに収まります。この順序で 1 つずつ確認しましょう——各ステップは前のステップが正しいことに依存するので、飛ばして確認すると表面症状を追いかけることになります。

1. リクエスト構造

症状：検証エラー、またはフィールドの欠落や予期しないフィールドに関するメッセージ。

修正：ボディが有効な JSON であること（末尾のカンマが典型的な犯人です）、model フィールドが正確に gemini-omni-1.2-flash であること、そしてペイロードを動作する curl の例と 1 行ずつ比較することを確認してください。curl が動いて Python が動かない場合は、2 つのリクエストボディを diff しましょう。

2. パラメータ

症状：duration や resolution を名指しするエラー、または予期しない出力サイズ。

修正：型を確認し（数値であるべき所は数値、文字列であるべき所は文字列）、値が許容範囲内かを確認しましょう。あるパラメータが黙って無視される場合は、API が期待する位置に入れ子になっているか、トップレベルに置かれていないかを確認しましょう。

3. 認証

症状：401 または 403 レスポンス。

修正：キーが Bearer プレフィックス付きで Authorization ヘッダーに存在すること、環境変数が実際に値を含んでいること（空文字列は間違ったキーによく似ています）、そして周囲の空白や引用符をキーにコピーしていないことを確認しましょう。キーが漏洩した疑いがある場合は再生成してください。

4. タスク状態

症状：ポーリングしても永遠に成功が見えない、または保留中のタスクを失敗として扱っている。

修正：正しいタスク ID をポーリングしていること、ループがすべての状態（pending、running、succeeded、failed）を識別していること、最大待機時間が現実的なタスクに対して十分長いことを確認しましょう。各状態遷移をログに記録すれば、どこで詰まっているかが分かります。

5. レート制限と一時的な障害

症状：429 レスポンスまたは断続的な 5xx エラー。

修正：即座に再試行するのではなく、ジッター付きバックオフで再試行しましょう。多数のタスクをポーリングしている場合は並行性を下げてください。一時的なエラーは正常です；賢く再試行するクライアントはそれを乗り越えます。

デバッグの規律

何かがうまくいかないときは、一度に 1 つだけ変え、できるだけ小さなリクエストを再実行しましょう。生のレスポンスボディを保っておきましょう——エラーメッセージは通常、正確なフィールドや条件を名指ししており、それを注意深く読む方がどんな推測よりも時間を節約できます。

本番統合チェックリスト

ノート PC で一度動いたスクリプトは統合ではありません。公開前にこれらのギャップを埋めましょう。

バックオフ付きリトライ

ネットワーク呼び出しを、一時的な障害——タイムアウト、接続リセット、429、5xx レスポンス——を扱えるリトライ戦略で包みましょう。ジッター付き指数バックオフを使い、試行回数を制限し、検証に失敗したリクエストは決して再試行しないでください；不正なボディを再試行してもより遅く再び失敗するだけです。

すべてにタイムアウトを設定する

すべての HTTP 呼び出しに明示的なタイムアウトを設定しましょう。接続タイムアウトと読み取りタイムアウトを区別し、生成リクエストのタイムアウトは実際の生成にかかる時間以上に設定してください——ただし上限付きで。

タスクを中心に冪等性を実装する

ネットワークの揺らぎは、サーバーがリクエストを受け付けた後、レスポンスを見る前に起こり得ます。盲目的に再試行すると重複タスクを作ってしまうかもしれません。各論理リクエストにクライアント生成の参照を付与し、既存タスクを検出して再利用できるようにし、新規作成を避けましょう。そしてその参照をキーとしてタスクハンドルを永続ストレージに保存しましょう。

問いに答えられるログ

各リクエストについて、モデル名、パラメータ値（duration、解像度）、タスクハンドル、状態遷移、遅延を記録しましょう。API キーや機密データを含む可能性のある完全なプロンプト内容は決して記録しないでください。午前 3 時に問題が起きたとき、これらのログこそが何が起きたかを正確に再構築できるものになります。

可観測性とアラート

リクエストとタスクライフサイクルの両方について、成功率、種類別のエラー分布、エンドツーエンドの遅延を追跡しましょう。単発の失敗ではなく持続的なエラー率に対してアラートを出しましょう。検証エラーと一時的なエラーを分けるダッシュボードは、バグがあるのかネットワーク状況が悪いのかを即座に教えてくれます。

設定の衛生

エンドポイント、モデル名、デフォルトパラメータはコード全体に散らばせるのではなく設定に置きましょう。API キーはシークレットマネージャーか環境変数から読み込みましょう。料金と制限が計画に関係する場合は、ハードコードした数値ではなく料金パネルを参照しましょう。これらは変わるからです。

このチェックリストを一通りこなせば、gemini-omni-1.2-flash 統合は最初のテストだけでなく実際のトラフィックを扱えるようになります。動作する curl 呼び出しから始め、Python に移植し、そこから外へ構築していきましょう。