HiAPI API で imagen-4.0 を使う方法：curl、Python、実行可能なリクエスト例

HiAPI が提供する imagen-4.0 の機能

imagen-4.0 はテキストから画像を生成するモデルです。自然言語のプロンプトを送信すると、生成された画像が返ってきます。統合開発者にとって本当に重要なのはモデルのアーキテクチャではなく、その周囲のインターフェース契約です。HiAPI を通じたその契約は 1 つの HTTP エンドポイントです——JSON を受け取り、bearer キーで認証します——これは chat completion や embedding の呼び出しで既に慣れ親しんだパターンと完全に一致します。

モデルに直接接続するのではなく HiAPI を使う実際の利点：

• 統一された認証方式。 同じ API キーがプラットフォーム上のすべてのモデルに適用されるため、複数のプロバイダーの資格情報を切り替える必要はありません。
• 統一されたリクエスト形式。 モデル識別子とプロンプトを含む 1 つの JSON リクエストボディ。SDK 固有のリクエスト構造を学ぶ必要はありません。
• 同期応答。 imagen-4.0 は同じ HTTP レスポンスで結果を返すため、基本的なシナリオではポーリングループや webhook を構築する必要がありません。

このガイドでは、curl と Python のそれぞれでゼロから動作するリクエストを構築し、その後レスポンスの読み取り方と、本番環境に投入する前に何を準備すべきかを説明します。

API キーを取得して認証を設定する

HiAPI 上のすべての imagen-4.0 呼び出しは bearer token で認証します。HiAPI アカウントで API キーを作成すると、以降そのキーがリクエストに必要な唯一の資格情報になります——個別のプロジェクト ID も、署名付きヘッダーも不要です。

ほとんどの事故を防ぐ原則：キーは環境変数に置き、絶対にソースコードにコミットしないこと。 スクリプトに貼り付けてリポジトリにプッシュされたキーは、ローテーションせざるを得ないキーです。

ローカルでの設定

シェルセッションでキーをエクスポートします：

export HIAPI_API_KEY="your-key-here"

変数を永続させたい場合は、この行をシェルの設定ファイルに追加してください。あるいは .env ファイルを使い、.gitignore に記載して、アプリ起動時に読み込みます。

デプロイ環境

CI や本番環境では、プラットフォームのシークレットマネージャーを通じて HIAPI_API_KEY を設定します——ファイルをイメージに焼き込むのではなく、実行時に環境変数を注入します。これにより、アプリケーションコードはローカルとデプロイ環境で完全に同一になり、変数の出所だけが異なります。

リクエストヘッダー

すべてのリクエストは以下を伴います：

Authorization: Bearer $HIAPI_API_KEY

401 が表示された場合、最初に確認すべきはヘッダーが実際に送信されているか、そして変数が空でない値に解決されているかです。変数を一度もエクスポートしていないシェルは、何事もなかったかのように Bearer を送信し、その後ろには何もありません。

送信する前にリクエスト構造を理解する

imagen-4.0 のリクエストボディは暗記できるほど小さい——これが要点です。一度構造を理解すれば、コピー＆ペーストしたコード片を翻訳することなく、どの言語でもリクエストを構築できます。

最低限送信する必要があるもの：

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

2 つのフィールドが主な役割を担います：

• model はどのモデルがリクエストを処理するかを識別します。文字列であり、プラットフォームが imagen-4.0 を列挙するすべての場所で使われる同じ識別子です。間違えるとエラー応答が返り、サイレントにフォールバックすることはありません。
• prompt は欲しい画像の説明です。人に画面を説明するように書いてください：被写体、シーン、スタイル、光。具体的なプロンプトは、単語 1 つのプロンプトよりも予測可能な結果を生みます。

リクエストは POST で、Content-Type: application/json を付けて、プラットフォームの画像生成エンドポイントに送信します。モデルには追加のオプションパラメータもあるかもしれませんが、上記の 2 フィールドのボディは完全で有効なリクエストです——ここから始め、必要なときにだけオプションを追加してください。

ボディは純粋な JSON なので、curl、Python、Node、そして HTTP クライアントを持つあらゆるツールが一級市民です。次の 2 つのセクションでは、同じリクエストの 2 通りの書き方を示します。

実行可能な curl リクエスト

ターミナルから始めれば、パースの干渉を受けずに生のレスポンスを確認できます。

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

行ごとの説明：

• -sS は進捗バーを抑制しつつエラーは表示するので、出力は読みやすく、失敗を隠しません。
• -X POST はリクエストメソッドを設定します。画像生成はコンテンツを作成するので POST です。
• URL はプラットフォームの画像生成エンドポイントで、ベース URL とパスで構成されます。ベース URL を変数に保存しておけば、同じコマンドを異なる環境で使えます。
• 最初のヘッダーは bearer キーを運び、先ほどエクスポートした環境変数から読み取ります。
• Content-Type: application/json はサーバーにボディの解析方法を伝えます。
• -d は JSON ボディを提供します。シングルクォートはシェルが波括弧や引用符を解釈するのを防ぎます。中の JSON はリテラルです。

出力を確認したい場合は、JSON 整形ツールを通します：

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4.0","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

レスポンスに画像参照が含まれていれば、リクエストは成功です。次のセクションでこれをアプリケーションコードに変換します。

Python で同じリクエストを書く

curl 呼び出しはそのまま変換できます。唯一の実質的な選択は HTTP クライアントです。標準ライブラリの urllib はどこでも使えますが、requests はコードが短く、ほとんどのコードベースが既に依存しているライブラリです。

再利用可能なヘルパー関数

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

注目すべき点が 3 つあります：

• os.environ["HIAPI_API_KEY"] は変数が欠落していると直ちに KeyError を発生させ、空の token を送信するのではなく、迅速かつ大きな音で失敗します。
• json= は辞書を自動シリアライズしてコンテンツタイプを設定するので、リクエストの動作は curl 版と完全に一致します。
• timeout=120 は呼び出し時間を制限します。画像生成はテキスト補完より時間がかかるため、デフォルトのタイムアウトなしではなく、寛容なタイムアウトを使います。

この関数はプロンプトを引数に取り、解析済みの JSON を返すので、コードの残りの部分は HTTP の詳細に触れる必要がありません。何かに接続する前に、REPL でテストしてください。

同期レスポンスを読み取り、エラーを処理する

imagen-4.0 は同期応答です：生成された画像は同じ HTTP レスポンスのボディで返されます。基本的なシナリオではポーリングすべきジョブ ID も、書くべきポーリングループもありません——この呼び出しは他のあらゆるリクエスト-レスポンスのやり取りと同様に扱ってください。

返される内容

成功レスポンスは JSON オブジェクトです。Python では response.json() で解析するか、curl 出力を JSON 整形ツールに通し、返却された構造の中から画像データを特定します——通常は URL またはエンコードされた画像ペイロード、および生成に関するメタデータです。実際のレスポンスから正確なフィールド名を一度読み取り、それに基づいてコードを書いてください。

警戒すべき問題

呼び出しをラップし、解析前にステータスを確認します：

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

明示的に処理する価値のある失敗モード：

• 401 — キーが欠落または無効。コードではなく環境変数を修正してください。
• 一般的な 4xx — ボディの形式エラー、モデル識別子の誤り、またはプロンプトの拒否。レスポンスボディが通常どれかを示します。ログに記録してください。
• 5xx — サーバー側の障害。これらはバックオフ付きでリトライする価値があります。
• タイムアウト — 成功ではなく結果不明として扱ってください。画像が生成されたと仮定しないでください。

失敗時は常にステータスコードと切り詰めたレスポンスボディをログに記録してください。この情報なしでのデバッグは推測に過ぎません。

最初のリクエストから本番環境へ

リクエストは動作しました。スケールを拡大する前に、項目ごとに確認してください：

• 設定。 ベース URL と API キーはどちらも環境から取得します。ソースコードにリテラルはなく、イメージにキーはありません。
• タイムアウト。 すべての画像呼び出しにタイムアウトを設定します。タイムアウトがないと、停滞したリクエストがワーカープロセスを無期限に占有する可能性があります。
• リトライ。 5xx とタイムアウトのみをリトライし、指数バックオフに上限を設けます。401 やボディ形式エラーの 4xx は絶対にリトライしないでください——全く同じように失敗します。
• ログ記録。 各呼び出しのモデル、プロンプト長、ステータスコード、レイテンシを記録します。キーは記録せず、プロンプトにユーザーデータが含まれる可能性がある場合は完全なプロンプトも記録しないでください。
• コスト意識。 画像生成は生成された出力に対して課金されるため、ユーザーごとまたはジョブごとに何枚の画像がリクエストされたかを追跡し、アプリケーション層で上限を設定します。現在の料金は本ガイドではなくプラットフォームの料金パネルを参照してください。
• 並行性。 画像呼び出しはテキスト呼び出しより遅いです。chat-completion のレイテンシを仮定せず、これを基準にワーカープールのサイズを設定してください。

これらが整えば、同じ generate_image ヘルパー関数は変更なしにバッチジョブ、ユーザー向け機能、内部ツールで使用できます。統合の詳細については、プラットフォームのドキュメントを参照してください。