GPT Image 2.5 API を Python で使う：動作するサンプル

GPT Image 2.5 API を呼び出すには、gpt-image-2.5-flare などのモデル ID とプロンプトを付けて https://api.seedrouter.ai/v1/images/generations に POST を送り、レスポンスのタスク id を保持して、ステータスが completed になるまで GET /v1/tasks/{id} をポーリングします。完了したタスクには画像の URL が入っています。同じエンドポイントで、テキストからの画像生成、参照画像での編集、マスクでの編集を扱えます。

このガイドでは、Python で最後まで実行できる手順とそれに相当する JavaScript を示し、そのあとよく遭遇するエラーとそれぞれの意味を説明します。

最初のリクエストの前に必要なものは？

必要なのは 2 つ、API キーとモデル ID です。

API キーのページでキーを作成し、サーバーの環境変数に保管してください。ブラウザのコードには決して入れないでください:

export SEEDROUTER_API_KEY="your-key"

次に、GPT Image 2.5 の 4 つのモデル ID から 1 つを選びます。正確にコピーしてください。ティアのない gpt-image-2.5 という ID はありません。

どのモデルから始めるか迷ったら Flare を使ってください。Sunburst を使う価値があるのはどんなときかは、Flare と Sunburst の比較で説明しています。

Python で画像を生成するには？

送信するとすぐに返ります。レスポンスは画像ではなく、タスクへの参照です。

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

何よりも先に task_id を保存してください。これは今支払った処理への唯一の手がかりで、画像のレンダリング中にプロセスが再起動しても、これがあれば復旧できます。

画像はどう取得する？

終わるまで数秒ごとにタスクをポーリングします。このループは最大 10 分待ちます。期限に達して止まるのはループであって、タスクではありません。

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

残したい URL はダウンロードして、ご自身で保存してください。結果の URL は受け渡しのためのもので、長期保存用ではありません。

同じ呼び出しを JavaScript で書くと？

リクエストは同じで、変わるのは HTTP クライアントだけです。キーがブラウザに渡らないよう、サーバー側で実行してください。

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

同じヘッダーを付けて、Python のループとまったく同じように GET https://api.seedrouter.ai/v1/tasks/${taskId} をポーリングしてください。

既存の画像を編集するには？

同じリクエストに参照画像を追加します。編集専用のエンドポイントもモードのフィールドもありません。images を送れば編集になり、mask を加えると変更が 1 つの領域に限定されます。

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Make the bottle blue. Preserve the composition and lighting.",
  "images": [{"image_url": "https://example.com/reference.png"}],
  "mask": {"image_url": "https://example.com/mask.png"}
}

入力は公開された HTTPS の URL でなければなりません。参照画像は PNG、JPEG、WebP で、それぞれ 50 MB 未満のものを最大 16 枚送れます。マスクは 4 MB 未満の PNG で、最初の参照画像と同じサイズにし、その透明な部分が変更する箇所を示します。base64 文字列、data: URL、ファイルのアップロードは拒否されるため、先にご自身のストレージにファイルをアップロードし、その URL を送ってください。

API が「モデルを利用できない」と返すのはなぜ？

HTTP 400 のエラーコード 20002（“The requested model is not available.”）は、model の値が API で提供されている ID ではないことを意味します。よくある原因は惜しい間違いです。ティアのない gpt-image-2.5、ドットではなくダッシュを使った gpt-image-2-5-flare、あるいは sunburst のタイプミスなどです。上の表から ID をコピーしてください。

パラメータのエラーは、モデルの確認より前に報告されます。リクエストに不正なフィールドもある場合は 20001 が返り、メッセージにフィールド名（例: quality）が示されます。まずそれを直してください。ID がまだ間違っていれば、次の試行でモデルのエラーが出ます。

受け付けられたあとにタスクが失敗することもあります。その場合もクエリは HTTP 200 を返し、status: "failed" と、コード 60001（コンテンツポリシー）や 60002（生成失敗）などの error オブジェクトが含まれます。失敗したタスクは課金されません。エラーカタログには、残高やレート制限のエラーを含むすべてのコードと、それぞれの次の対処が記載されています。

よくある質問

画像を直接返す公式の Python SDK の呼び出しはありますか？

この API にはありません。納品は非同期で、必ず送信してタスク ID を保持し、ポーリングします。stream と partial_images には対応していません。

複数の画像を一度にリクエストできますか？

はい。n を 1 から 10 の範囲で設定してください。完了したタスクには納品した画像 1 枚ごとに URL が 1 つ並び、課金は納品された画像の分です。

透過 PNG を取得するにはどうすればいいですか？

background を transparent、output_format を png に設定してください。JPEG にはアルファチャネルがないため、その組み合わせは実行前に拒否されます。

タスク ID を軸に連携を組み立てる

タスク ID は受け取った瞬間に保存し、期限を決めてポーリングし、ポーリングのタイムアウトは「失敗」ではなく「まだ実行中」として扱ってください。それ以外のすべて、つまり各フィールドと上限は GPT Image 2.5 API リファレンスにあり、コードを書かずにリクエストを試すなら Playground を使えます。