APIMart経由でGPT-Image-2.5を使って画像を生成・編集する

image2.5 APIMartゲートウェイの機能

image2.5ゲートウェイは、APIMart APIを通じてGPT Image 2.5の生成・編集ファミリーにアクセスできます。画像モデルごとに別の認証情報やリクエスト形式を統合する代わりに、1つのベースURL、1つのベアラートークン、OpenAI形式の/v1/images/generationsエンドポイントを使用します。

このAPIは非同期で動作します。画像生成リクエストは、画像を直接返すのではなくタスクIDを返します。その後、処理が完了または失敗するまで、アプリケーションでタスクエンドポイントをポーリングします。成功したタスクには一時的な出力URLが含まれるため、有効期限が切れる前にダウンロードしてください。

APIMartは、リポジトリで文書化されているサービスです。gpt-image-2.5-extエンドポイントはサードパーティのリレールートであり、gpt-image-2.5-flareとgpt-image-2.5-sunburstはトークン課金ルートです。本番実行の前に、現在の制限と料金を確認してください。

主な機能

• 1つのAPIベースURL: リクエストにはhttps://api.apimart.ai/v1を使用します。
• 2つのモデルバリアント: 日常的な生成やバッチ下書きにはFlareを、精密な編集や本番向けアセットにはSunburstを選択できます。
• 2種類の課金方式: リレールートは納品画像ごとの課金、公式ルートはトークンベースの課金です。
• 非同期処理: リクエストを送信し、GET /v1/tasks/{task_id}をポーリングして進捗を確認します。
• 複数の出力品質: リレールートは1K、2K、4Kに対応します。
• 柔軟な構図: 10種類のアスペクト比から選択するか、autoを使用できます。
• 参照画像による生成: image_urlsに最大16件を指定して、画像間変換や編集に利用できます。
• 少量バッチ: リレールートのnで、1～4枚の画像をリクエストできます。

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

画像単位で課金されるリレールート

納品画像ごとの定額課金を利用したい場合は、model: "gpt-image-2.5-ext"を使用します。version: "flare"またはversion: "sunburst"で基盤となるバリアントを選択します。

• flareは、大量生成、日常的な画像、下書き向けです。
• sunburstは、編集や参照画像を使った本番向け制作に適しています。

リポジトリでは、2026年9月16日時点で、両バリアントの納品済み1K画像1枚あたり$0.0085という料金が確認されています。また、2Kは$0.014、4K Flareは$0.021と記録されており、4K Sunburstについては実際の料金を確認するよう案内されています。これらは確認日時点の数値であり、恒久的な保証ではありません。

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

トークンベースの課金を利用する場合は、gpt-image-2.5-flareまたはgpt-image-2.5-sunburstを直接使用します。これらのルートではversionフィールドを省略し、low、medium、high、xhigh、maxの品質段階に対応します。公式ルートでは、ピクセル単位で正確なサイズも指定できます。

実用上は、画像ごとのコストを予測しやすくしたい場合はリレールートを使い、品質制御や正確なサイズ指定が必要な場合は公式ルートを検討するとよいでしょう。

出力例

リポジトリには、商品写真、ポートレート、建築、UIアセット、イラスト、ゲームアート、料理写真、マクロ画像のプロンプト例が収録されています。以下の提供画像は、プロジェクトに含まれるビジュアル出力の種類を示しています。

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

1. APIキーを作成する

APIMartのAPIキーページからキーを取得します。ソースコードに直接記述せず、環境変数に保存してください。

export APIMART_API_KEY="your-api-key"

2. クライアントを選択する

cURLには、標準的なコマンドライン環境以外のプロジェクト依存関係は必要ありません。Pythonの例では、requestsパッケージをインストールします。

python -m pip install requests

リポジトリには、fetchをグローバルに利用できるNode.js 18以降向けのJavaScript例も含まれています。

3. リクエストヘッダーを理解する

AuthorizationヘッダーにAPIキーを指定します。リレールートの例では、レスポンスバージョンヘッダーと一意の冪等性キーも使用します。

• Authorization: Bearer $APIMART_API_KEY
• Content-Type: application/json
• X-APIMart-Response-Version: 2026-07-27
• Idempotency-Key: unique-request-value

同じ送信を再試行する場合は、同じ冪等性キーを再利用します。新しい画像タスクを意図的に作成する場合は、新しいキーを生成してください。

基本的な使用方法: cURLで画像を生成する

次のリクエストは画像単位の課金ルートを使用し、Flareを選択して、正方形の1K画像を1枚生成します。

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": "A cozy reading nook beside a window on a rainy day, warm table lamp, cinematic lighting",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

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

タスクをポーリングする

返されたタスクIDで task_01EXAMPLE を置き換えてください。

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

タスクのステータスは pending、processing の順に進み、その後 completed または failed に到達します。レスポンスには progress、cost、credits_cost も含まれる場合があります。完了したら、result.images[].url から画像URLを取得し、expires_at を確認してください。

エンドツーエンドのPython例

この例では画像を1枚送信し、終端状態に到達するまで5秒ごとにタスクを確認します。

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
COMMON_HEADERS = {
    "Authorization": f"Bearer {os.environ['APIMART_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,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
        timeout=60,
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        task_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        task_response.raise_for_status()
        task = task_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(
    "A sky garden at dawn, architectural photography",
    version="flare",
    resolution="1K",
    size="16:9",
)

for image in result["result"]["images"]:
    print(image["url"], image.get("expires_at"))

本番環境のクライアントでは、URLだけを返すのではなく、コスト、進行状況、有効期限、エラー情報を保持できるよう、タスクオブジェクト全体を返すか保存してください。

参照画像を編集に使用する

画像から画像への生成や、中継ルートでの編集を行うには、image_urls 配列を追加します。この配列には、URLまたはデータURLを最大16個含めることができます。リポジトリによると、このルートでは参照画像に別途料金はかかりません。

{
  "model": "gpt-image-2.5-ext",
  "version": "sunburst",
  "prompt": "Preserve the product label, replace the background with soft off-white, and add a natural cast shadow",
  "image_urls": [
    "https://example.com/source-product.jpg"
  ],
  "size": "1:1",
  "resolution": "2K",
  "n": 1
}

Sunburstは、編集の精度と参照画像を使った作業に適したバリアントとして、リポジトリで推奨されています。アクセス可能なURLまたは有効なデータURLを使用し、リストはドキュメントに記載された上限以内に収めてください。

中継ルートのリクエストフィールドリファレンス

• 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: 参照URLまたはデータURLを最大16個含められる任意の配列です。

トークン課金ルートを呼び出す

公式ルートは同じ生成パスを使用しますが、モデルIDを変更し、version を削除して、品質設定を追加します。この例では、高品質のSunburstを選択しています。

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": "Preserve the product label, replace the background with soft off-white, add a natural cast shadow",
    "size": "1:1",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }'

現在のフィールド定義については、公式ルートのリファレンスおよびリレールートのリファレンスを参照してください。

信頼性の高い統合のための高度なヒント

1. 再試行を冪等にする。送信がタイムアウトし、タスクが作成されたか不明な場合は、元の冪等性キーを保持してください。新しいキーを使うと、課金対象の生成が重複する可能性があります。
2. ポーリングを通常のワークフローとして扱う。completedとfailedの両方に対応してください。短い間隔でのポーリングは避けます。リポジトリの例では、チェックの間隔を5秒空けています。
3. 返されたポーリングURLを使用する。レスポンスにはdata.poll_urlが含まれているため、タスクエンドポイントを手動で再構築する必要がありません。
4. 出力を速やかにダウンロードする。生成された画像URLは一時的なものです。各出力をexpires_atの時刻までに自分のストレージへコピーしてください。
5. 実際のコストを記録する。タスクのレスポンスに含まれるcostとcredits_costを保存してください。公開価格と実際の請求額を比較できます。
6. 有料リクエスト1件でコストを検証する。価格やプロモーションによるルーティングは変更される可能性があるため、大規模なバッチを開始する前に小規模なテストを実行してください。
7. 適切なルートを使用する。画像ごとの予測可能な課金と最大4件のバッチ処理にはリレールートを選択してください。品質の段階や正確なピクセル制御が重要な場合は、公式モデルIDを選択します。
8. クライアントを書き換えずにバリアントを切り替える。リレールートでは、versionをflareとsunburstの間で変更するだけです。
9. 認証情報を保護する。APIキーは環境変数またはシークレット管理ツールで管理し、ブラウザ側のコードに決して公開しないでください。

まとめ

APIMartのimage2.5ゲートウェイは、GPT Image 2.5の生成および編集機能に一貫した方法でアクセスできます。予測可能な高ボリューム生成にはgpt-image-2.5-extとFlareから始め、編集や参照画像を使った作業にはSunburstへ切り替えてください。トークン課金と拡張された品質制御がタスクに適している場合は、公式モデルIDを使用します。

基本的な統合パターンはシンプルです。画像リクエストを送信し、返されたタスクIDを保存し、完了するまでポーリングし、報告されたコストを確認して、一時URLの有効期限が切れる前にすべての結果をダウンロードします。規模を拡大する前に、現在のAPIMartの価格を確認し、少額の有料リクエストで選択したルートを検証してください。