GPT Image API 移行ガイド:Responses から Images API へ切り替え、マルチターンの画像編集をどう保持するか?

GPT Image API 移行ガイド:Responses から Images API へ切り替え、マルチターンの画像編集をどう保持するか?

著者注:APIYIのResponsesでimage_generationを使い「チャットしながら画像を生成する」開発者は、独立したImages APIへ移行した後も、本記事の方法で連続的な画像編集を維持できます。

結論から言うと:移行するのは画像生成の部分だけで、既存のテキスト対話はそのままです。以前はprevious_response_idによって暗黙的に接続されていた「前の画像」を、今後はアプリケーション側で保存し、画像を編集するたびに明示的に選択して、元画像としてPOST /v1/images/editsにアップロードします。こうすれば、マルチターンの画像編集の仕上がりは変わりません。変わるのは「前の画像」を誰が覚えておくか、という点だけです。

この結論が成り立つ前提は、APIYIが2026-11-21 22:30(北京時間)に公開したドキュメント更新です。5つの公式転送画像モデルについて、2つの独立した画像エンドポイントを利用することが推奨されるようになりました。OpenAIはResponsesを停止しておらず、サイト内のテキスト対話もこれまでどおり利用できます。以下のインターフェース、フィールド、課金基準はすべてAPIYI(apiyi.com)のドキュメントとOpenAI公式の画像生成ガイドに基づくものです。コードはドキュメントのサンプルであり、実際の検証結果を示すものではありません。

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-ja-image-0


GPT Image API 移行ナレッジマップと索引

移行は4つのステップで進めます。各ステップの出力が、次のステップの入力になります。

旧呼び出しの識別とルーティング振り分け(第1節)
   └─> 出力: 各リクエストが対話、generations、edits のどれを通るべきか
最初の画像を生成して保存(第2.1節)
   └─> 出力: 検証済みの v1.png + アセット記録
選択した元画像を編集インターフェースに渡す(第2.2節)
   └─> 出力: v2.png + parent_asset_id の関連付け
受け入れ検査とコスト照合(第3節)
   └─> 出力: 利用可能な画像リスト + 各検査済み画像のコスト

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-ja-image-1

ステップ 依存するもの この順番である理由 目標
1 ルーティング振り分け 既存コード内の呼び出し一覧 どこを変更すべきかを先に確定すれば、テキスト対話を誤って変更しない 画像生成リクエストだけを Images API に切り替える
2.1 初回画像生成 ステップ1で確定した generations ルーティング 後続の画像編集には、実際に保存された元画像が必要 検証済みの v1 を取得して登録する
2.2 画像編集の継続 ステップ2.1で保存した v1 ファイル 独立エンドポイントは previous_response_id を認識せず、アップロードされた画像のみを認識する v2 を取得し、親子関係を記録する
3 受け入れ検査とコスト照合 ステップ2の画像とコンソールログ 受け入れ検査に合格した画像のみがコスト計算の分母に含まれる 納品可能な画像 + 説明可能な請求情報

推奨の読み進め方:第1節は必読です。第2節はコードの順番に沿って進めてください。第3節は、リリース前や接続断、請求に関する疑問が生じた際に参照してください。

To Know:GPT Image API 移行の用語

用語 簡潔な説明
官転 APIYI が提供する公式転送チャネルのモデル。本記事では5つの画像モデル ID を指す
image_generation Responses API 内の画像生成ツール。旧来の経路ではこれを通じて会話しながら画像を生成する
previous_response_id Responses が前ターンのコンテキストを継続するためのパラメータ。独立した Images リクエストでは受け付けられない
multipart フォームアップロード形式。/images/edits で実際の画像バイナリを送るために使う
b64_json 独立した画像エンドポイントが返す画像フィールド。内容は base64 エンコードされた画像
parent_asset_id 「この画像がどの画像から編集されたか」をアプリ側で独自に記録する関連フィールド

1 Responses からの移行が必要な GPT Image API 呼び出し

1.1 GPT Image API 11/21 の変更範囲と5つの公式中継モデル

今回のドキュメント更新では、次の5つの公式中継モデル ID が対象になります。

  • gpt-image-2.6-sunburst
  • gpt-image-2.6-flare
  • gpt-image-2.5-sunburst
  • gpt-image-2.5-flare
  • gpt-image-2

対応する2つの独立した画像エンドポイントは、それぞれ POST /v1/images/generations(JSON リクエストボディ)と POST /v1/images/edits(multipart フォーム)です。APIYI では、Responses の image_generation 経路を使った画像生成をそのまま続けることは推奨していません。理由は2つあり、1つは供給が不安定なこと、もう1つは余分なツール利用料が発生することです。また、Chat Completions ではこの5つの公式中継画像モデルを使った画像生成はサポートされていません。旧コードにそうした使い方がある場合も、同じく移行リストに含めてください。

なお、今回の調整は画像生成にのみ影響します。OpenAI は Responses を停止していませんし、APIYI サイト内のテキスト対話も停止していません。したがって移行の範囲は、「リクエスト内で画像ツールまたは画像モデルを呼び出している」コード部分に限られます。5つのモデルのどれを選ぶかはまた別の話題です。APIYI apiyi.com ヘルプセンターのモデル選定記事をご覧ください。本記事では詳しく触れません。

1.2 GPT Image API におけるテキスト対話・初回画像生成・追加編集のルーティング

APIYI の FAQ が示している組み合わせ方は、次のとおりです。対話モデルがユーザーの意図を判断し、アプリが個別に Images API を呼び出して画像を自分で管理します。この考え方に沿えば、もともと1つの Responses リクエストで完結していた3つの処理を、3つのルートに分けられます。

ユーザーの意図 新しいルート リクエスト形式 画像ソース
純粋なテキストチャット・Q&A 既存のテキスト対話エンドポイントを維持 変更なし なし
初回の画像生成 POST /v1/images/generations JSON プロンプトのみ
ある画像をさらに編集 POST /v1/images/edits multipart アプリがアップロードした、選択済みの元画像

ネイティブな Responses では、編集の継続は previous_response_id で実現できますし、画像を直接渡すこともできます。独立した Images リクエストは previous_response_id を受け取りません。これが「複数ラウンドの編集」をアプリ側で引き継ぐ必要がある根本的な理由です。モデルはもう前の画像を覚えてくれません。その画像のファイルを自分で渡す必要があります。

ユーザーが「もう少し赤く」と言っても、会話内に v1、v2、v3 と複数バージョンがある場合、アプリはどれを指しているのか判断できません。こうしたときは推測せず、まずユーザーに確認してください。デフォルトで最新バージョンを使うのは楽に見えますが、ユーザーが実は v2 に戻して再編集したいと思っていた場合、無駄に1回分の課金が発生し、ユーザーも混乱させてしまいます。

レスポンスの解析も合わせて変更が必要です。

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-ja-image-2

経路 レスポンス内の画像の位置 コンテキストの継続方法
Responses + image_generation output 内の type=image_generation_call の項目にある result previous_response_id、または画像を渡す
独立した Images API data[0].b64_json アプリが選択済みの元画像をアップロード

2 GPT Image API で前回の画像を続けて修正する方法

ここでは 2 ラウンドの例を使って全体の流れを説明します。1 回目で青いマグカップを生成し、2 回目ではカップ本体だけをれんが色に変更します。パラメータは APIYI のドキュメント例に沿って、モデル gpt-image-2.5-sunburst、サイズ 1024x1024、quality=medium、output_format=png とします。トークンは環境変数 APIYI_KEY から読み取り、Bearer 形式で渡します。

2.1 GPT Image API で青いマグカップの PNG を生成して検証する

1 回目の呼び出しは generations エンドポイントに対して行い、プロンプトには「薄いグレーの背景、青い陶器のマグカップを中央に配置、取っ手は右向き、柔らかなサイドライト、画面内に文字はなし」と記述します。レスポンスを受け取ったら、次の順序で処理します。

  1. raise_for_status() を呼び出し、まず HTTP レベルの失敗を排除します。
  2. b64_json を厳密に base64 デコードし、デコードできなければ失敗とみなします。
  3. Pillow で開いて load() を呼び出し、本当に画像としてデコードできることを確認します。
  4. フォーマットが PNG、サイズが 1024×1024 であることを確認してから v1.png として保存します。
  5. アプリ内にこのアセットを登録し、以降の画像修正ではここから元画像を取得します。

3 番目のステップは省略できません。open() はファイルヘッダーしか読み取らないため、画像データが途中で切れていないかどうかは load() の時点で初めて明らかになります。

2.2 GPT Image API で選択済みの元画像をアップロードし、カップ本体だけをレンガ色に変更

2回目の呼び出しでは、edits エンドポイントを使います。data に model、prompt、size、quality、output_format を渡し、files の image[] フィールドで v1.png の実際のバイナリをアップロードします。プロンプトの意味は、カップ本体だけをレンガ色に変更し、カップの形状、ハンドル、構図、ライティング、背景はすべて変更しない、というものです。

このステップでは、つまずきやすいポイントがいくつかあります。

  • response_format は渡さないでください。
  • Content-Type を手動で設定しないでください。requests が boundary 付きの multipart ヘッダーを自動生成します。手動で設定すると、かえって boundary が失われます。
  • base64 文字列をファイルとしてアップロードしないでください。アップロードするのは、画像の元のバイト列である必要があります。

変更後は同じ方法でデコード・検証し、v2.png として保存します。v1 は保持し、アセットレコードに parent_asset_id = v1 と記録します。この親子関係が、新しいアーキテクチャにおける「マルチターンのコンテキスト」です。また、これは生成型の編集であるため、モデルは他の領域をできるだけ保持しますが、カップ本体以外のピクセルが1つ残らず同一であることは保証されません。

以下は最小限の完全なサンプルです(ドキュメント用の例で、本記事では実測していません):

import base64
import io
import os
import uuid

import requests
from PIL import Image

BASE_URL = "https://api.apiyi.com/v1"  # APIYI の統合エンドポイント
API_KEY = os.environ["APIYI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
MODEL = "gpt-image-2.5-sunburst"
SIZE = "1024x1024"
# 中程度のタイムアウトの例。ネットワークと画質に合わせて調整してください。自動リトライはありません。
TIMEOUT = (10, 360)

assets = {}  # asset_id -> {"path": ..., "parent_asset_id": ...}


def decode_and_check(resp, path):
    resp.raise_for_status()
    item = resp.json()["data"][0]
    b64 = item.get("b64_json")
    if not b64:
        raise ValueError("no b64_json in response, check body before any resend")
    raw = base64.b64decode(b64, validate=True)
    img = Image.open(io.BytesIO(raw))
    img.load()
    if img.format != "PNG" or img.size != (1024, 1024):
        raise ValueError(f"unexpected image: {img.format} {img.size}")
    with open(path, "wb") as f:
        f.write(raw)
    return path


def save_asset(path, parent_asset_id=None):
    asset_id = str(uuid.uuid4())
    assets[asset_id] = {"path": path, "parent_asset_id": parent_asset_id}
    return asset_id


# ラウンド1: JSON 経由でテキストから画像生成
gen_resp = requests.post(
    f"{BASE_URL}/images/generations",
    headers=HEADERS,
    json={
        "model": MODEL,
        "prompt": (
            "Light gray background, a blue ceramic mug centered, "
            "handle facing right, soft side lighting, no text."
        ),
        "size": SIZE,
        "quality": "medium",
        "output_format": "png",
    },
    timeout=TIMEOUT,
)
v1_id = save_asset(decode_and_check(gen_resp, "v1.png"))

# ラウンド2: 明示的に選択した元画像を multipart 経由で編集
selected_id = v1_id  # ユーザーの対象バージョンが不明な場合は、まず確認する
with open(assets[selected_id]["path"], "rb") as f:
    edit_resp = requests.post(
        f"{BASE_URL}/images/edits",
        headers=HEADERS,  # Content-Type を手動で設定しない。requests が boundary を設定する
        data={
            "model": MODEL,
            "prompt": (
                "Change only the mug body to brick red. Keep the mug shape, "
                "handle, composition, lighting and background unchanged."
            ),
            "size": SIZE,
            "quality": "medium",
            "output_format": "png",
        },
        files={"image[]": ("v1.png", f, "image/png")},
        timeout=TIMEOUT,
    )
v2_id = save_asset(decode_and_check(edit_resp, "v2.png"), parent_asset_id=selected_id)
print(assets)

サンプル内の timeout=(10, 360) はあくまでドキュメント上の中程度の設定です。実際の値は、ご利用のネットワーク経路と画質設定に合わせて決めてください。また、サンプルでは自動リトライをあえて実装していません。その理由は 3.2 節で説明します。

🚀 クイック検証:APIYI_KEY に、APIYI(apiyi.com)のコンソールで作成したトークンを設定すれば、上記のスクリプトで2ラウンドのフローを最後まで実行できます。新規ユーザーはまず無料テスト枠でルーティングとパース処理を確認し、その後で本番トラフィックに切り替えるとよいでしょう。

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-ja-image-3

3 GPT Image API 移行後の受け入れ確認とコスト照合

3.1 GPT Image API 画像受け入れの4つの関門

4つの関門すべてを通過した画像だけが、アプリ内で「利用可能」とマークできます。

  1. HTTP 成功:raise_for_status() が例外を投げない。
  2. デコード可能:厳密な base64 デコードに成功し、Pillow の load() も成功する。
  3. 仕様が正しい:形式とサイズがリクエストと一致している。本例は PNG、1024×1024。
  4. 視覚的な変化が実際に起きている:v2 のカップ本体が実際にレンガ色になり、カップの形、取っ手、構図、背景はほぼ維持されている。

第4の関門には人手による確認、または独立したレビュー工程が必要です。HTTP ステータスコードからは、モデルが正しく修正したかどうかを判断できないからです。最初の3つの関門だけを通過した画像は、せいぜい「技術的に有効」であって、まだ納品できるものではありません。レスポンスに画像がまったく含まれていない場合は、まずレスポンスの内容を確認してからリトライするかどうかを決めましょう。この問題はヘルプセンターに専用の記事があるため、本記事では繰り返しません。

3.2 GPT Image API 旧ツール課金と受け入れ画像1枚あたりのコスト

移行前後で、課金の集計基準は異なります。

項目 旧 Responses image_generation 経路 独立 Images API
追加費用 約 $0.20 の APIYI 画像ツール追加呼び出し費用 このツール費用はなし
この数字の意味 この追加ツール費用のみを指し、請求全体の価格でも OpenAI の一般価格でもない 従量課金
適した比較方法 「受け入れ画像1枚あたりのコスト」で比較 「受け入れ画像1枚あたりのコスト」で比較

単価だけで比べないでください。以下の公式で統一して評価することをおすすめします。

受け入れ画像1枚あたりのコスト = 関連する実際の課金(必要なテキスト呼び出し、課金済みの失敗リクエストとリトライを含む)÷ 受け入れに通過した画像数

分子には、関連するすべての課金を計上します。意図を判定する対話呼び出し、課金済みの失敗リクエスト、リトライを含めます。分母には、3.1 節の4つの関門を通過した画像だけを数えます。通過した画像が1枚もない場合は、1枚あたりのコストを計算しないでください。そのときの結論は「単価が高い」ではなく「フローに問題がある」だからです。移行でいくら節約できるかは、リトライ率と受け入れ通過率によって変わります。本記事では具体的な割合は示しません。

コスト照合のデータはコンソールの消費ログにあり、消費記録は type=2 です。quota フィールドを読む場合は、プラットフォームのドキュメントに従って quota ÷ 500000 で金額に換算します。

接続断の扱いには特に注意が必要です。独立画像エンドポイントは同期的に結果を返すため、接続の途中で切れた場合、そのリクエストはすでに課金されている可能性があり、request ID から画像を取得することもできません。正しい順序は、まず APIYI apiyi.com コンソールの消費ログでこのリクエストが課金されたかどうかを確認し、それから再送するかどうかを決めることです。サンプルコードに自動リトライを書いていないのもこのためで、自動リトライは接続断のときに二重課金を招きやすいからです。レート制限に遭ったりチャネルを切り替えたりする必要がある場合は、ヘルプセンターのチャネル選択と 429 降級に関する記事を参照してください。

移行完了の判定基準はとてもシンプルです。テキスト対話が通常どおり使えること。初回の画像生成が安定して、4つの関門を通過できる v1 を返すこと。画像を変更するたびに、アセット記録で明確な parent_asset_id を確認できること。コンソールログの画像課金の各項目が、受け入れ済みの画像1枚、既知の失敗1回、または記録済みの再送1回のいずれかに対応すること。これらがすべて満たされれば、残りの Responses 画像生成トラフィックを Images API に切り替えられます。複数モデルで比較テストを行う場合、APIYI apiyi.com は統一された OpenAI 互換インターフェースを提供しているので、モデルを変えるときは MODEL パラメータを1つ変更するだけです。


参考資料

  1. APIYI ドキュメント更新:公式中継画像モデルが Images API 経由に変更

    • リンク: docs.apiyi.com/live/2026-11/gpt-image-official-relay-images-api
    • 説明:5つの公式中継ID、2つの独立エンドポイント、旧ルートを推奨しない理由
  2. APIYI FAQ:1つのAPIでテキストと画像を同時に処理する

    • リンク: docs.apiyi.com/faq/text-and-image-in-one-api
    • 説明:対話モデルが意図を判断し、アプリ側で Images API を個別に呼び出す組み合わせ方法
  3. OpenAI 画像生成ガイド

    • リンク: developers.openai.com/api/docs/guides/image-generation
    • 説明:Responses による継続的な編集方法とレスポンス構造
  4. APIYI GPT Image 2 テキストから画像生成 / 画像編集

    • リンク: docs.apiyi.com/api-capabilities/gpt-image-2/text-to-image
    • リンク: docs.apiyi.com/api-capabilities/gpt-image-2/image-edit
    • 説明:リクエストパラメータ、multipart アップロード、デコード検証のサンプル
  5. APIYI Responses 画像ツール / 画像 API ベストプラクティス / ログ照会

    • リンク: docs.apiyi.com/api-capabilities/gpt-image-2/responses-image-tool
    • リンク: docs.apiyi.com/api-capabilities/image-api-best-practices
    • リンク: docs.apiyi.com/api-capabilities/log-query
    • 説明:ツール利用料の基準、接続切断時の処理、消費ログの換算

著者: APIYI 技術チーム
技術交流: 移行中にルーティングや請求に関する問題が発生した場合は、APIYI apiyi.com のトップページからお気軽にお問い合わせください。インターフェースの詳細については docs.apiyi.com のドキュメントセンターをご覧ください。

関連記事

類似投稿