APIMart APIを通じてGPT Image 2.5で画像を生成する

このプロジェクトで提供されるもの

image2.5 Prompt Galleryは、GPT Image 2.5で実行し、生成された画像とともに公開した12個のプロンプトを収録した実用的なコレクションです。各レシピにはプロンプト、モデルバージョン、アスペクト比、出力結果が記録されているため、自分のアプリケーション向けに調整する前にプロンプトを評価しやすくなっています。

サンプルでは、https://api.apimart.ai/v1にあるAPIMartのOpenAI互換エンドポイントを使用します。中継ルートは非同期です。アプリケーションから画像リクエストを送信し、タスクIDを受け取り、タスクエンドポイントをポーリングして、処理完了後に画像をダウンロードします。

主な機能

• OpenAI互換の生成パス: リクエストはPOST /v1/images/generationsに送信されます。
• 2種類の中継バリアント: 通常の生成にはversion: "flare"を、編集や参照画像を使った作業にはversion: "sunburst"を使用します。
• 複数の出力品質: 1K、2K、4Kから選択できます。
• 柔軟なフレーミング: auto、または1:1、16:9、9:16、4:3を含む10種類の対応アスペクト比から選択できます。
• バッチ出力: nで1～4枚の画像をリクエストできます。
• 参照画像のサポート: image_urlsに最大16個のURLまたはデータURLを指定できます。
• 呼び出しごとのコスト報告: 完了したタスクデータにはcostとcredits_costが含まれます。
• 冪等性のある再試行: APIはIdempotency-Keyヘッダーを受け付けるため、同じ送信を再試行する際の重複処理を防ぎやすくなります。

正しいモデルルートを選ぶ

APIMartでは、中継版と公式版のGPT Image 2.5ルートを利用できます。リクエストフィールドと課金方式が異なるため、統合を実装する前にルートを選択してください。

中継版の画像単位ルート

modelにgpt-image-2.5-extを設定し、version: "flare"またはversion: "sunburst"を指定します。ギャラリーのサンプルで使用しているルートで、納品された画像ごとに課金されます。

• flare: 通常の生成やバッチでの下書きに適しています。
• sunburst: 編集の精度が求められる作業や、参照画像、オブジェクト、ロゴ、商品ラベルを維持する作業に適しています。

公式のトークン課金ルート

gpt-image-2.5-flareまたはgpt-image-2.5-sunburstを直接使用します。これらのモデルIDではversionフィールドを送信しないでください。公式ルートはトークン課金で、lowからmaxまでの品質段階と、正確なピクセル寸法に対応しています。

ルート形式を混在させないでください。gpt-image-2.5-extエイリアスにはバージョンセレクターが必要ですが、公式モデルIDには指定してはいけません。

インストールとセットアップ

1. アカウントを作成して入金する

APIMartのキー取得ページからAPIキーを取得します。リポジトリによると、無料クォータはなく、1ドルからチャージできます。

2. 環境変数にキーを保存する

export APIMART_API_KEY="your-api-key"

キーをアプリケーションのソースコードに直接記述したり、バージョン管理にコミットしたりしないでください。

3. Pythonの依存関係をインストールする

Pythonのサンプルでは、サードパーティ製のrequestsパッケージを使用します。

python -m pip install requests

curlを使う場合は、シェルでcurlとuuidgenなどのUUID生成ツールを利用できることを確認してください。

curlで最初の画像リクエストを送信する

次のリクエストでは、中継版のflareバリアントを使って正方形の1K画像を作成します。

IDEMPOTENCY_KEY="$(uuidgen)"
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-APIMart-Response-Version: 2026-07-27" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "model": "gpt-image-2.5-ext",
    "version": "flare",
    "prompt": "雨の日、窓辺にある居心地のよい読書コーナー、暖かなテーブルランプ、映画のような照明",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

送信に成功すると、HTTP 202が返されます。data.idからタスク識別子を読み取るか、返されたdata.poll_urlを使用してください。

タスクをポーリングする

curl --request GET \
  --url "https://api.apimart.ai/v1/tasks/TASK_ID" \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "X-APIMart-Response-Version: 2026-07-27"

タスクは通常、pendingからprocessingへ進み、その後completedまたはfailedとして終了します。完了したら、result.images[].urlから生成画像のURLを取得します。

生成画像のURLにはexpires_atのタイムスタンプが含まれます。URLの有効期限が切れる前に各ファイルをダウンロードして保存してください。

エンドツーエンドのPythonクライアントを構築する

このサンプルは1件のリクエストを送信し、HTTPエラーを確認して、5秒ごとにポーリングし、完了したタスクレコードを返します。新しい生成ごとに新しい冪等性キーを作成します。

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
API_KEY = os.environ["APIMART_API_KEY"]

COMMON_HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-APIMart-Response-Version": "2026-07-27",
}

def generate_image(prompt, version="flare", resolution="1K", size="1:1"):
    submit_headers = {
        **COMMON_HEADERS,
        "Idempotency-Key": str(uuid.uuid4()),
    }

    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=submit_headers,
        timeout=60,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        poll_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        poll_response.raise_for_status()
        task = poll_response.json()["data"]

        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(f"Generation failed: {task}")

        time.sleep(5)

result = generate_image(
    "マットなセラミック製エスプレッソカップを温かみのある石の台座に置いた、スタジオ撮影の商品ヒーロー画像。柔らかな窓からの光、85mmレンズ風、ミニマルなベージュの背景、鮮明な影"
)

print("Cost:", result.get("cost"))
for image in result["result"]["images"]:
    print("Image URL:", image["url"])
    print("Expires at:", image.get("expires_at"))

安全に再試行する

送信がタイムアウトした場合や再試行可能なレスポンスを受け取った場合は、同じ Idempotency-Key を使って同じ論理リクエストを再送信します。新しい画像を意図的に作成する場合は、新しいキーを使用してください。完成済みのタスクを、元画像や参照画像の変更を理由に再作成する場合も、新しいキーを使用します。

主なリクエストフィールドを理解する

• model: 必須。中継ルートでは gpt-image-2.5-ext を使用します。
• version: flare または sunburst。デフォルトは flare です。
• prompt: 必須。空白以外のテキストを含める必要があります。
• resolution: 1K、2K、または 4K。デフォルトは 1K です。
• size: デフォルトは auto です。対応する比率は 1:1、16:9、9:16、4:3、3:4、3:2、2:3、5:4、4:5、21:9 です。
• n: 生成する画像の数。中継ルートでは1枚から4枚まで指定できます。
• image_urls: オプションの配列。最大16個の画像URLまたはデータURLを含められます。

より信頼性の高いプロンプトを書く

ギャラリーでは、プロンプトを曖昧な形容詞の羅列ではなく、簡潔な制作指示として扱います。役立つ構成は、被写体、素材、ライティング、構図またはレンズ、仕上がりです。

1. 被写体を明示する: 主な物体、人物、場面、または環境を特定します。
2. 物理的な素材を指定する: マットなセラミック、すりガラス、粘土のレンダー などの表現を使います。
3. 光を設定する: 柔らかな窓からの光、自然なサイドライト、ハイキーのスタジオ照明、ドラマチックな逆光などを説明します。
4. 構図を固定する: 中央配置、俯瞰のフラットレイ、ワイドなシネマティック構図など、意図したレイアウトを指定します。
5. レンズの表現を加える: 85mm、24mm、マクロ、フォーカススタッキング などの用語で、遠近感やディテールを調整できます。
6. 仕上がりを選ぶ: 絵画的なディテール、商用商品写真、鮮明なベクターエッジなどの表現で、ビジュアルの処理方法を指定します。

例:

すりガラスのボトルに入ったアンバー色の美容液の化粧品パックショット、
表面に水滴、継ぎ目のない淡いピンクの背景、
高精細な商用商品写真

参照画像を使用する

画像から画像への変換や参照画像を使った生成では、中継リクエストに image_urls 配列を追加します。このルートでは最大16個の参照画像を受け付けます。

{
  "model": "gpt-image-2.5-ext",
  "version": "sunburst",
  "prompt": "商品とラベルは維持し、背景を柔らかなオフホワイトに置き換え、自然な落ち影を加える",
  "image_urls": [
    "https://example.com/product-reference.jpg"
  ],
  "size": "1:1",
  "resolution": "2K",
  "n": 1
}

安定してアクセスできる参照URLを使用してください。参照URLの有効期限切れが原因でタスクが失敗した場合は、画像を再ホストし、新しい冪等性キーで新しいタスクを送信します。

公式ルートを呼び出す

公式ルートでは、直接的なモデルIDと、 中継ルートの version セレクターではなく quality 設定を使用します。

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "商品ラベルは維持し、背景を柔らかなオフホワイトに置き換え、自然な落ち影を加える",
    "size": "1:1",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }'

現在のフィールドの詳細については、公式ルートのドキュメントとリレールートのドキュメントを参照してください。

高度な本番運用のヒント

送信と処理を分離する

Webリクエストを開いたままにせず、返されたタスクIDをキューまたはデータベースに保存します。バックグラウンドワーカーで未完了のタスクをポーリングし、完了した結果を保存できます。

適度な間隔でポーリングする

リポジトリのサンプルでは5秒ごとにポーリングしています。不要なトラフィックを生む短いループは避けてください。大規模なワークロードでは、タスクが保留中または処理中の間、バックオフを追加します。

実際のコストを記録する

完了したすべてのタスクからcostまたはcredits_costを保存します。これにより、見積もりだけに頼らず、呼び出しごとの支出を記録できます。

READMEには、リレールートの価格として、納品される1K画像あたり$0.0085、2Kで$0.014、4Kのflareで$0.021という観測値が記載されています。4Kのsunburstの価格は表では固定されていません。これらの数値は2026年9月時点の観測値であるため、予算策定やスケーリングの前に最新の価格を確認してください。

結果をすぐにダウンロードする

result.images[].urlを永続ストレージとして扱わないでください。expires_atより前にファイルをダウンロードし、その後アプリケーションが管理するストレージへ移動します。

スケールする前に小さく始める

n: 1で1Kのプロンプトを検証します。被写体、構図、スタイルが安定してから、解像度を上げるか複数の出力をリクエストしてください。

用途に合わせてアスペクト比を選ぶ

• アイコン、商品カード、正方形のソーシャル向け素材には1:1。
• 映画的なシーン、ダッシュボード、プレゼンテーションのヘッダーには16:9。
• 縦向きのモバイル画面やソーシャルレイアウトには9:16。
• エディトリアルイラストや料理写真には4:3。
• ポートレートやファッション構図には3:4。

トラブルシューティング

• 401または無効なAPIキー: キーを再度コピーし、スペースや改行文字が含まれていないことを確認してください。ヘッダーはAuthorization: Bearer $APIMART_API_KEYで指定する必要があります。
• 残高またはクレジットエラー: アカウントに資金を追加してください。リポジトリによると、無料の代替クォータはありません。
• 429レスポンス: 同時実行数を減らし、バックオフして、同じべき等性キーで同じ送信を再試行します。
• 400またはモデルが見つからない: gpt-image-2.5-extにバージョンが含まれていること、また直接指定する公式モデルIDにはバージョンが含まれていないことを確認してください。
• タスクのステータスがfailed: プロンプトが拒否されたか、参照URLの有効期限が切れていないかを確認します。入力を修正し、新しいキーで新しいタスクを送信してください。
• 出力URLが機能しなくなった: 一時URLの有効期限が切れている可能性があります。今後、完了した出力は速やかにダウンロードしてください。

まとめ

image2.5 Prompt Galleryは、GPT Image 2.5で素材を生成するための再現可能なワークフローを示しています。適切なルートを選び、本番運用向けのプロンプトを作成し、非同期リクエストを送信してタスクIDをポーリングし、報告されたコストを記録して、有効期限が切れる前に結果をダウンロードします。まずは1K画像を1枚生成して品質と請求を確認し、その後、高解像度、バッチ処理、または参照画像を使ったsunburstワークフローへ拡張してください。