HiAPI API で imagen-4.0-fast を使う方法：curl と Python ガイド

imagen-4.0-fast の最適化の方向性

imagen-4.0-fast は imagen-4.0 シリーズの中で低遅延向けの階層です。画像生成リクエストへの高速応答に最適化しつつ、シリーズの他のモデルと同じリクエスト・レスポンス構造を維持します。実際の利用では、画像をユーザーとのインタラクションの途中で即座に提示する必要がある場合——たとえば下書きサムネイル、ユーザーがさらに調整するためのプレビュー画像、リアルタイムレイアウトに必要な素材など——であり、オフラインのバッチ処理（実時間が問題にならない場面）ではないときに、この階層を選ぶべきです。

モデル選択を考える有効な方法の一つは、インタラクション予算と品質の上限を区別することです。インタラクション予算が厳しく、「十分に良い」画像が次のステップを解放する場合には、高速階層が勝ります。画像そのものが成果物である場合には、より高品質な階層が勝ります。imagen-4.0-fast は他の画像モデルと同じ HiAPI インターフェースを共有しているため、後から階層を切り替える際もコードを書き直す必要はなく設定を変更するだけで済みます——したがって、まず高速階層から始め、出力品質が製品の基準に達するかを測定してから、特定のユースケースを段階的に上位へ移すことを検討できます。

高速階層が最適化しているもう一つの側面は、負荷下での予測可能性です。生成時間が短いということは接続の占有時間が短いことを意味し、これにより並行予算の挙動がより線形に近づきます。アカウントレベルのレート制限に達するまでに、ワーカースレッドを倍にすればおおよそスループットも倍になり、生成の途中でタイムアウトすることはありません。後述のタイムアウトと並行性に関する議論は、この特性の上に成り立っています。

ユースケースが多段階のユーザーフロー、バッチ処理、またはリクエストが再試行される可能性のあるあらゆるシナリオを含む場合、高速階層はより安全なデフォルトの選択です——人間の忍耐の許容範囲内に留まりながら、追加の試行を一度受け入れることができます。

前提条件と API 設定

初回の呼び出しの前に、四つのものを準備する必要があります。

1. HiAPI アカウントと API キー

すべての画像生成は HiAPI の統一 API を通じて行われます。HiAPI コンソールで API キーを作成し、ソースコードに書くのではなく環境変数として保存します：

export HIAPI_API_KEY="your_key_here"

キーをコミットしてはいけません。コードが CI やコンテナ内で実行される場合は、実行時にシークレットマネージャー経由でこの変数を注入してください。

2. ベース URL とモデル識別子

設定モジュールに二つの定数を保持し、コードベース内のすべてのリクエストが同じ場所を指すようにします：

HIAPI_BASE_URL = "https://api.hiapi.ai"
HIAPI_IMAGE_MODEL = "imagen-4.0-fast"

モデル識別子はリクエストペイロード内で imagen-4.0-fast を選択するために使います。これをデータとして扱い、各ファイルに散らばるハードコードされた文字列にしないでください。

3. 信頼できる HTTP クライアント

Python では httpx と requests のどちらも使用できますが、httpx はより明確なタイムアウトオブジェクトを提供します。シェル作業では curl で十分であり、問題が自分のコードにあるのかリクエスト自体にあるのかを切り分ける最速の方法です。

4. 最小限のテストツール

生成出力の保存先を事前に決めておきます——スモークテストではディスクファイルへの書き込みで十分ですが、本番コードでは大きなペイロードをメモリに残さず、意識的にストリーミングまたは保存するべきです。

二つの設定習慣が早い段階で報われます。第一に、認証を Authorization ヘッダーを付加する一つのヘルパー関数に集約し、キーのローテーションが一箇所の変更で済むようにします。第二に、ペイロードを変えずにリクエスト ID と所要時間を出力できる DEBUG フラグを保持します。深夜二時に障害が起きたとき、この二つの習慣が五分での修正か一時間の推測かを分けます。

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

以下は完全で実行可能な curl 呼び出しです。テキストプロンプトから画像を一枚生成します：

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "prompt": "a quiet harbor at dawn, soft mist over wooden docks, photographic",
    "n": 1,
    "size": "1024x1024"
  }'

フィールドごとの説明：

• -sS は進行状況バーを隠しますが、エラーは表示します。デバッグ時には -i を加えてレスポンスヘッダーを確認できます。そこには通常リクエスト ID が含まれており、助けを求める際に参照できます。
• -X POST と Content-Type: application/json ヘッダーの組み合わせにより、ペイロードは不透明なリクエストボディではなく構造化されたリクエストになります。
• Authorization: Bearer $HIAPI_API_KEY が唯一の認証機構です。キーは環境変数から読み込まれるため、セッション内で設定している限り、シェル履歴に平文で現れることはありません。
• model は HiAPI 画像エンドポイントで imagen-4.0-fast を選択します。省略すると別のデフォルトモデルになる可能性があります——常に明示的に指定してください。
• prompt は唯一必須のコンテンツフィールドです。説明的にしますが百科事典のように書かないでください。長すぎるプロンプトはトークンを消費し、ある程度を超えると高速階層の出力を改善することはほとんどありません。
• n はリクエストが返す画像の数を制御します。統合中は 1 から始めてください。
• size は出力解像度のリクエストです。選択方法は第五節で説明します。

Python コードを書く前に、まず一度実行してレスポンスボディを確認してください。curl が成功すれば、その後の失敗はクライアントコードにあります。curl が失敗すれば、問題はキー、ペイロード、またはアカウントにあり、すでに調査範囲の半分を排除できています。

Python で同じリクエストを送る

以下は最小限の Python クライアントで、curl 呼び出しにフィールドごとに対応し、HTTP 層の周囲にエラーハンドリングを包んでいます：

import os
import httpx

HIAPI_BASE_URL = "https://api.hiapi.ai"
HIAPI_IMAGE_MODEL = "imagen-4.0-fast"

def generate_image(prompt: str, size: str = "1024x1024") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # fail fast if unset
    payload = {
        "model": HIAPI_IMAGE_MODEL,
        "prompt": prompt,
        "n": 1,
        "size": size,
    }
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }
    with httpx.Client(timeout=httpx.Timeout(60.0, connect=10.0)) as client:
        response = client.post(
            f"{HIAPI_BASE_URL}/v1/images/generations",
            json=payload,
            headers=headers,
        )
    if response.status_code == 401:
        raise RuntimeError("HiAPI rejected the API key")
    if response.status_code == 429:
        raise RuntimeError("Rate limited; back off and retry")
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft mist over wooden docks, photographic")
    print(result)

このスニペットにはいくつか意図的な選択があります：

• os.environ["HIAPI_API_KEY"] は変数が欠けている場合に直ちに KeyError を投げます。これは未認証のリクエストを送って 401 をキーの問題と誤認するよりも良い方法です。
• 明示的なタイムアウト——接続タイムアウトと読み取りタイムアウトを分けて設定します。読み取りタイムアウトは画像生成で最も重要です。サーバーは画像生成中に接続を保持するためです。
• ステータスコードによる分岐処理を raise_for_status() の前に置きます。401 と 429 はコードにまったく異なる対応を要求します。これらを一つの例外にまとめると、再試行が誤りやすくなります。
• Client コンテキストマネージャは接続が確実に閉じられることを保証します。長命なサービスでは、起動時に一つのクライアントを作成して再利用すべきです——接続の再利用はスループットにとって重要です。

レスポンスボディには生成画像への参照とメタデータが含まれます。統合中の最初の数回の呼び出しではレスポンスボディ全体を記録し、コードがどのフィールド名に依存しているかを正確に把握してください。

パラメータと解像度の選択

imagen-4.0-fast のパラメータ処理には、素朴で明示的なスタイルが適しています。ペイロードは単一の関数で構築される辞書として保ち、失敗後ではなく送信前に検証してください。

プロンプト

プロンプトは最もレバレッジの高いパラメータであり、最も過剰設計されやすいものです。主体、場面、スタイルの順に記述します。互いに矛盾するスタイル語を積み重ねるのは避けてください。高速階層はそれらをあなたが制御する妥協ではなく平均値として解釈します。同じプロンプトを繰り返し生成する場合は、再リクエストするのではなく結果をサーバー側でキャッシュしてください。

n

一回の呼び出しで複数の画像を要求するのはユーザー向けの選択肢としては便利ですが、単一リクエストの作業量を倍増させ、接続の占有時間を延ばします。統合中は n を 1 に保ち、有効化後のエンドツーエンドの遅延を測定してから増やしてください。

size

解像度パラメータはコストと遅延が静かに積み重なる場所です。より大きな出力は生成作業とレスポンスボディの増大を意味します。表示コンテキストを満たす最小の解像度を選んでください——サムネイルの位置にメインビジュアル画像のサイズは不要です。生成サイズと表示サイズを分離し、画像パイプラインで後から拡大・縮小するようにします。これによりリクエストが予測可能に保たれ、プロンプトのロジックを変えずに後から遅延に応じて品質を調整しやすくなります。

決定性と再現性

送信したすべてのパラメータをリクエスト ID をキーとして出力とともに記録します。ある画像が先週と違って見える理由を誰かが尋ねたとき、保存されたペイロードが数秒でその問いに答えます。ユーザー入力をデフォルト値にマージしてペイロードを構築する場合は、マージ後の結果を全体として検証してください——部分的な上書きは不正なリクエストの一般的な原因です。

実用的なルール：ペイロードは小さく、完全に明示的で、ログから再現可能であるべきです。ログから再構築できないものは、最終的に追加を後悔するパラメータです。

タイムアウトと並行性の処理

imagen-4.0-fast は生成時間が短いため、ほとんどの信頼性の問題はクライアント側にあります。タイムアウトが低すぎる、再試行すべきでないときに再試行する、アカウントレベルの制限に対して並行度が高すぎる、などです。

タイムアウト

一つの値ではなく二つの値を設定します。短い接続タイムアウトはネットワークと DNS の問題をすばやく捕捉し、長い読み取りタイムアウトは生成と転送の時間を許容します。読み取りタイムアウトは推測ではなく、環境で観測された p95 遅延に余裕を加えて選択すべきです。サーバーがまだ作業中にタイムアウトしたリクエストを再試行すると容量を浪費します——したがって、実際に再試行する場合は、最初の試行が無料だったと仮定せず、独立した予算を持つ新しい試行として扱ってください。

再試行

安全に再試行できるものだけを再試行します：接続エラーと 5xx レスポンスです。4xx は絶対に再試行しないでください——不正なペイロードは毎回同じように失敗します。ジッター付きの指数バックオフを使用し、総試行回数を制限します。有用な構造は、約 1s、2s、4s の遅延にランダム化を加えた三回の試行で、多くのクライアントが同時に失敗したときに負荷を分散します。

並行性

バッチ処理の作業には、無制限の asyncio.gather ではなく、有界のワーカープールを使用します。進行中の各リクエストは一つの接続を占有し、アカウントのレート予算を消費します。小さなプールから始め——少数の並行リクエスト——スループットを測定し、遅延が改善しなくなるか 429 が現れ始めるまで増やします。高速階層の短い生成時間はここで利点となります。各リクエストがすぐに完了するため、適度なプールで接続を長時間開いたままにせずに高いスループットを維持できます。

バックプレッシャー

429 を受け取ったときの正しい対応は、直ちに再試行するのではなく速度を落とすことです。上述のバックオフパターンに従って短い遅延を加え、一時的にプールサイズを減らすことを検討します。429 が発生したときの並行レベルを記録してください——その数字が実際の上限です。

よくあるリクエスト失敗のデバッグ

各ステップで最も多くの不確実性を排除できる順に失敗を処理します。まず curl で再現し、次にクライアントへ進みます。

401 Unauthorized

キーが欠けている、形式が誤っている、または Bearer トークンとして送信されていません。Authorization ヘッダーを直接確認し、環境変数が呼び出しを行うプロセス内で実際に設定されていること（コンテナや CI ランナーはシェルとは異なります）を確かめ、値の周囲に余分な引用符や末尾の空白がないことを検証します。curl がリテラルのキーで動作するのにアプリが失敗する場合、問題は環境の読み込みにあることは確実です。

400 Bad Request

ペイロードが不正か、パラメータ値が無効です。クライアントが実際に送信した正確な JSON で再現します——メモリ内の辞書ではなく、シリアライズ後のペイロードを記録します——そして動作する curl の例と比較します。よくある原因：Content-Type の欠落、model の綴り間違い、数値フィールドを文字列として送信、初期の API 形態から残ったフィールド。

422 / 検証エラー

フィールドは存在するが許容範囲外です——通常は n または size がモデルの受け付けない値に設定されています。ペイロードを最小限の必須フィールドまで削減し、成功を確認してからパラメータを一つずつ戻します。

429 レート制限またはクォータ枯渇

送信したリクエスト数または並行リクエスト数がアカウントの許容値を超えています。並行ログで確認し、プールサイズを減らし、バックオフパターンが実際に適用されていることを確かめます。低量でも続く場合は、同じキーを共有している他のプロセスがないか確認してください。

5xx とタイムアウト

サーバー側またはネットワークの問題です。バックオフ付きで一、二回再試行します。特定のペイロードの失敗が再現可能な場合は、レスポンスヘッダーからリクエスト ID と正確なペイロードを取得してください——これがエスカレーションを実りあるものにする鍵です。

一つの汎用的な習慣

本番の障害ごとに --verbose の curl 再現を保持します。アプリのエラーからコピー＆ペースト可能な単一の curl コマンドへ移行することで、デバッグの範囲をリクエスト自体に絞り込めます。これで、HiAPI API を通じた imagen-4.0-fast の利用は予測可能になります。