GPT Image 2 API の使い方：テキストから画像生成と画像から画像生成のガイド

GPT Image 2 API が開発者に提供するもの

GPT Image 2 API は、プロンプトに基づいて画像を生成するための統一され一貫したインターフェースを提供します。複数のベンダーをつなぎ合わせたり複数の SDK を保守したりする必要はなく、HiAPI.ai に HTTP リクエストを 1 つ送るだけで画像データを受け取れます。マーケティング素材の生成ツール、アプリのオンボーディング用イラスト、ユーザー向けのクリエイティブツールといった機能を構築する際に重要なのは、レイテンシー、稼働時間、そして予測可能なリクエスト構造だからです。

使用する生成モードは 2 つあります：

• テキストから画像生成：プロンプトと目標サイズを提供すると、モデルがゼロから画像を生成します。
• 画像から画像生成：プロンプトに加えて 1 枚以上の参照画像を提供し、モデルはその参照画像に導かれて画像を生成します。

どちらのモードも同じ認証とレスポンス構造を共有するため、一度動作する呼び出しを作れば、2 つ目はまったく新しい統合ではなく小さな変更に過ぎません。本ガイドでは、2 つのバリアントの選び方、最小限の curl リクエスト、参照画像の扱い、4K 出力のリクエスト、Python への移植、そして本番の画像パイプラインがサイレント障害を避けるためのエラーハンドリングパターンを順に説明します。

安定した API 契約で画像生成を必要とする機能を構築するなら、以下の内容がゼロから動作するリクエストまでの最短経路です。

テキストから画像生成と画像から画像生成：バリアントの選択

コードを書く前に、プロダクトが実際にどちらのバリアントを必要とするかを決めましょう。この選択は主に、出力をどれだけ制御したいか、そして想定ユーザーがどれだけの内容を提供する必要があるかによって決まります。

テキストから画像生成を使うべきとき

以下の場合、テキストから画像生成が適切なデフォルトの選択です：

• ユーザーが欲しいものをテキストで説明し、ソース素材がない。
• プレースホルダー画像、キービジュアル、または固定のプロンプトテンプレートに基づくバリアントを生成する。
• できるだけシンプルなリクエストボディ（プロンプトとサイズだけ）で、リクエストサイズを小さく、レイテンシーを予測可能に保ちたい。

画像から画像生成を使うべきとき

出力がすでに存在する内容に忠実でなければならない場合、画像から画像生成が正しい選択です：

• アップロードされた商品写真をスタイル変換または再レンダリングする。
• 一連の参照素材に一貫した視覚処理を適用する。
• 構図、配色、被写体を導き、結果を既存のブランドやシーンに合わせる。

実用的なルール

プロンプトだけで出力を完全に決定できるなら、テキストから画像生成を使いましょう。意図の一部がテキストではなく画像に存在し、それをプロンプトで説明すると損なわれる、冗長になる、または信頼できない場合は、画像から画像生成を使って参照画像を渡しましょう。

よくある間違いは、より良いプロンプトで解決できるのに画像から画像生成を使ってしまうことです。参照画像はアップロードのオーバーヘッドを増やし、リクエスト検証の失敗の可能性も高めます。まずテキストから画像生成から始め、プロンプトでは捉えられない具体的な視覚属性を指摘できるときにだけ参照画像バリアントへ移行しましょう。

curl で最初のテキストから画像生成リクエストを送る

curl から始めましょう。SDK の挙動という変数を排除できるため、どこかで失敗したときに、問題が認証やリクエストボディの構造にあるのか、クライアントライブラリにあるのかを特定できます。

まず API キーを環境変数に設定し、シェル履歴やソース管理に残らないようにします：

export HIAPI_API_KEY="your_api_key_here"

次に最小限のリクエストを送ります：

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

レスポンスで確認すべき内容：

1. HTTP ステータスコード。200 はリクエストが受け付けられ処理されたことを意味します。それ以外のステータスコードでは、何かを変更する前にまずエラーレスポンスボディを読みましょう。
2. 認証。401 はほぼ常に、キーが欠落している、形式が誤っている、または期限切れであることを意味します。Authorization ヘッダーが Bearer の後にキーを続ける形式になっているか確認してください。
3. リクエストボディ。400 は通常、特定のフィールドを指します：パラメータの綴り間違い、モデルが受け付けないサイズ文字列、または検証を通らないプロンプトなどです。
4. 画像ペイロード。レスポンスモードによって、取得可能な URL または base64 画像データのいずれかを受け取ります。クライアントが後で不意を突かれないよう、両方を処理しましょう。

この呼び出しが成功すれば、同時に 3 つのことを検証できたことになります：キーが有効、エンドポイントパスが正しい、JSON 構造が受け入れられる。本ガイドの以降のすべての変更は、この既知の良好なベースラインから始まります。

参照画像で出力を導く

画像から画像生成リクエストはテキストから画像生成と同じリクエストの外枠を保ち、参照画像入力が加わります。プロンプトは依然として指示を担い、参照画像は視覚的なコンテキストを担います。

リクエストボディの変化は、プロンプトに加えて画像データを提供するようになることです。実際には、統合がサポートする形式に応じて、サービスが取得可能な URL を提供するか、インラインの base64 エンコード画像を提供するかのいずれかになります。以下のルールに留意してください：

• プロンプトと参照画像は一致させる。プロンプトが赤い製品を説明しているのに参照画像が青い場合、モデルは矛盾した信号を受け取ります。プロンプトは参照画像と矛盾する説明ではなく、参照画像についての指示（「このシーンを水彩画風に描き直す」）として書きましょう。
• 必要なものだけを送る。1 枚の強い参照画像は、複数の弱い参照画像より通常は優れています。複数の参照画像はアップロード量を増やし、どれが出力を駆動したかを判断しにくくします。
• リクエストサイズに注意。base64 エンコードされた画像はリクエストペイロードを大きく膨らませます。大きな写真をアップロードする場合、リクエストが遅くなったり拒否されたりしたときにまず確認すべきはここです。
• 送信前に検証する。画像がサポートされる形式か、クリーンにデコードできるかを確認しましょう。形式が誤った base64 文字列は理解しにくい失敗を生み、診断に時間がかかります。

利用可能なリクエスト構造は以下のとおりです：

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

リクエストの外枠は変わらないため、以前検証した curl 呼び出しは引き続きデバッグツールになります：リクエストボディを置き換え、ヘッダーを保ち、フィールドごとにレスポンスを比較しましょう。

4K 出力をリクエストする

出力解像度はモデルが勝手に仮定するものではなく、リクエストで指定します。高解像度の出力が必要なら、size パラメータで明示的に指定しましょう。デフォルトが大きいだろうと期待してはいけません。

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

より高解像度に移行する際に検証すべき事柄：

• サポートされるサイズ文字列。サイズ値はモデルが受け付ける範囲に基づいて検証されます。拒否されたサイズはサイレントにダウングレードされるのではなく 400 を返すため、近いが誤った値を推測するのではなく、必要な正確なサイズ文字列を確認しましょう。
• レスポンスサイズ。4K 画像データは 1K の結果よりはるかに大きくなります。レスポンスが base64 を含む場合や、すぐにダウンロードする URL を含む場合は、メモリとタイムアウト設定にその分の予算を見込みましょう。
• レイテンシー。高解像度の生成にはより時間がかかります。遅いけれど成功するリクエストがこちら側でタイムアウトしないよう、クライアントのタイムアウトを余裕をもって設定しましょう。
• コストモデル。課金はリクエストした出力サイズと数量によって決まるため、意識的に選択しましょう：機能が実際に必要とする解像度で生成し、UI がフル解像度を必要としないなら独自のパイプライン内でダウンサンプリングします。現在の価格はウェブサイトの価格パネルを参照してください。
• 慎重に拡大する。モデルの出力より大きな出力が必要なら、生成後のアップスケーリングはそれ自体の品質トレードオフを持つ独立したステップです。どちらの道を取るかを意識的に決めましょう。

4K をバッチ処理に組み込む前に、既知の良好なプロンプトで 4K をテストし、解像度関連の失敗が認証やリクエストボディの問題と混同されないようにしましょう。

リクエストを Python に移植する

Python でリクエストをゼロから書き直さないでください。curl ですでに検証した正確なリクエストボディを移植し、レスポンスの処理は別途確認しましょう。

import os
import base64
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

移植に関する注意点：

• キーを環境変数に保つ、curl とまったく同じです。絶対にインライン化しないでください。
• 明示的なタイムアウトを設定する。画像生成は典型的な JSON API 呼び出しより遅いため、デフォルトの短いタイムアウトは偽の失敗を招くよくある原因です。
• 両方のレスポンスモードを処理する。b64_json と url で分岐させれば、レスポンスがどう構成されていてもコードが動作します。
• 関数を再利用する。これを小さな generate_image(prompt, size) ヘルパー関数にまとめれば、テキストから画像生成と画像から画像生成は payload 内の任意の image フィールドだけが異なるようになります。

payload 辞書は curl でテストしたのと同じオブジェクトなので、Python で観察される挙動の変化はほぼすべてクライアント側（ヘッダー、エンコーディング、タイムアウト）に由来し、デバッグ範囲が大幅に狭まります。

エラーを処理しレスポンスを検証する

画像生成は本質的に失敗しやすい呼び出しです：ほとんどの API エンドポイントより遅く、大きなペイロードを伴い、モデルの可用性に依存します。一度きりの操作ではなく、時々失敗して再試行が必要な操作として扱いましょう。

レスポンス確認チェックリスト

1. 解析前にステータスを確認する。raise_for_status() を呼ぶかステータスコードを確認し、エラーレスポンスボディを読みましょう。問題のあるフィールドを通常示してくれます。
2. 構造を検証する。インデックス参照の前に data が存在し空でないことを確認しましょう。data[0] が必ず存在すると仮定してはいけません。
3. 画像バイトを検証する。デコード後、出力が空でなく有効な画像シグネチャで始まることを確認しましょう。ゼロバイトのファイルはサイレント障害であり、ずっと後になってから露見します。
4. リクエスト ID を記録する。レスポンスのリクエスト識別子をログに残し、失敗した生成を再現せずに追跡できるようにしましょう。

再試行戦略

• 一時的な失敗のみ再試行する。タイムアウト、接続リセット、5xx レスポンスは再試行する価値があります。401 や 400 は毎回同じように失敗するため、リクエストを修正すべきで、再試行してはいけません。
• ジッター付きの指数バックオフを使う。短い遅延から始めて徐々に増やします。ジッターはワーカー群が同期して再試行するのを防ぎます。
• 試行回数を制限する。通常 2〜3 回の再試行で十分です。それ以降はエラーをユーザーに通知するか、タスクをデッドレターパスに移しましょう。
• 冪等にする。再試行が重複生成を生む可能性があるため、結果を元のタスク ID に関連付けて保存し、再試行がユーザーに見える操作を二重に課金しないようにしましょう。

非同期に適合させる

高解像度の生成には時間がかかるため、アーキテクチャが許すならリクエストスレッドを占有し続けないでください。タスクをキューに入れ、呼び出し元にタスク ID を返し、ワーカーが上記の再試行戦略で呼び出しを実行するようにします。これにより Web 層の応答性を保ち、遅く失敗しやすい処理を再試行コストの低い場所に閉じ込められます。

最初の本番障害の後ではなく、最初の動作する呼び出しからこれらのチェックを組み込みましょう。小さな検証ヘルパー関数のコストは、3 週間後に空の画像ファイルをデバッグするコストよりはるかに低いのです。認証、リクエストボディ構造、解像度、再試行がすべて確認できれば、GPT Image 2 API はデモ専用の統合ではなく、信頼できるビルディングブロックになります。