GPT画像2.5 APIガイド：SunburstとFlareを使用した画像の生成と編集

Image API を使用して、直接的な単一ステップでの生成と編集を行います。画像作成が会話や複数ステップのフローに属する場合は、Responses API を使用します。Image API では、直接 gpt-image-2.5-sunburst または gpt-image-2.5-flare を選択します。

先にインターフェースを選択

画像APIは生成および編集エンドポイントを提供します。応答APIはツールとしての反復的な画像生成をサポートし、画像の入力と出力をコンテキスト内に保持できます。このアーキテクチャ上の決定はSDKの構文よりも重要です。

最小生成モード

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();
const result = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "クリーンなデザインのイラスト、太陽光図書館を描いたもの、文字要素なし"
  size: "1536x1024",
  quality: "中程度",
  output_format: "png"
});

fs.writeFileSync("library.png", Buffer.from(result.data[0].b64_json, "base64"));

APIキーをサーバー側に保存し、ソースコード管理から遠ざけてください。

出力制御

両方のモデルは、自動から最高品質まで、公式制限内でのカスタムサイズ、PNG/JPEG/WebP形式、JPEG/WebP圧縮、および透明または不透明な背景をサポートしています。アルファチャンネルが必要な場合は、PNGまたはWebP形式を使用してください。

編集モード

1枚または複数の画像を使用して編集エンドポイントを呼び出し、変更内容と保持する詳細を分けるプロンプトを提供します。送信前に入力のタイプとサイズを検証します。各参照に役割を割り当てます。

本番検証

ストレージリクエストID、モデルまたはスナップショット、プロンプトバージョン、サイズ、品質、出力形式、参照情報、遅延、および受け入れ結果。一時的な障害のみを再試行します。リクエストを変更せずに、意味エラーの出力を自動的に再試行しないでください。

モデルルーティング

日常タスクはFlareへ、高精度タスクはSunburstへルーティングします。固定ベンチマークを使用し、より速いモデルがより安いと仮定しないでください。現在のトークンレートは一致しているためです。

エラー処理

認証、組織検証、レート制限、無効なサイズ、コンテンツモデレーション、空の出力を処理します。該当する一時的なエラーには、ジッター付きの指数バックオフ戦略を使用し、再試行回数を制限します。不必要にプライベートな画像データを記録しないでください。

下流アニメーション

画像をデコードして承認した後、ソース情報を保存し、アセットを下流のワークフローに渡します。静止画像がキャラクター主導のストーリーボード、ビデオ、または編集アニメーションになる必要がある場合、Elser AI が関連します。リアルタイム製品でサポートされているアップロードとモデルオプションを検証してください。

生成エンドポイントと編集エンドポイント

テキストから新しい画像を生成する際は生成機能を使用します。1枚以上の既存画像が主体や初期状態を定義している場合は、編集機能を使用します。複数参照編集の場合は、安定した順序で入力を送信し、プロンプトでその順序を指定してください。リクエスト前にファイルタイプとサイズを検証し、誤った入力はローカルで失敗するようにしてください。

反復作業のためのレスポンスAPI

ユーザーが画像を作成し、対話形式で画像を評価し、その後の変更をリクエストする場合、Responses API は非常に便利です。画像生成ツールはより大きな応答フローに参加でき、画像ファイル ID をコンテキスト内に保持できます。これによりアプリケーション側の結合作業が軽減されますが、製品には依然として明確な状態管理とバージョン管理が必要です。「以前と同じ」では重要な制約条件として不十分です。言い換えてください。

より安全なアプリケーションアーキテクチャ

クライアント、タスクキュー、アセットストレージ、メタデータストレージは互いに独立して維持する。クライアントは簡潔な説明を送信する。サーバーはその説明を検証し、タスクを作成する。ワーカープロセスはOpenAIを呼び出し、結果をデコードして生成されたアセットIDの下に保存する。メタデータにはモデルスナップショット、プロンプト、設定、参照、レビュー結果が記録される。クライアントは元の認証情報ではなく、短期間有効なアセットURLを受け取る。

長時間実行される呼び出しは、脆弱なブラウザリクエストを占有すべきではありません。複雑なプロンプトは多くの時間を要する可能性があるため、処理中、完了、失敗のステータスを表示する必要があります。タスクの送信を冪等にすることで、クライアントの再試行時に重複した課金が発生するのを防ぎます。

検証ルール

カスタムサイズがドキュメントで規定された16の倍数、エッジ、比率、および総ピクセル制限を満たしているか確認します。背景が透明な場合はPNGまたはWebP形式を使用する必要があります。圧縮値をサポート範囲内に制限します。既知の品質とモデルパラメータのみを許可します。API呼び出し前にプロンプトが不足している場合は拒否します。

信頼性と可観測性

リクエストID、HTTPステータス、エラーカテゴリ、試行回数、遅延を記録し、プライベートイメージや機密情報は記録しない。ジッター付き指数バックオフを使用してレート制限と該当するサーバーエラーを再試行する。認証、無効なパラメータ、ポリシーエラーはそのまま再試行しない。試行回数に上限を設定し、有用な製品メッセージを返す。

モニター：

成功率と受容画像率。
モデルと品質別のp50およびp95レイテンシ。
入力トークンと出力トークン。
リトライと重複タスク。
審査結果。
ストレージと配信に失敗しました。

セキュリティと権利

APIキーをサーバー側のキーマネージャーに保存します。ソース画像と生成された画像にアクセス制御を実施します。保持ルールを設定し、公開すべきでないメタデータを削除し、アップロードされた素材に対するユーザーの権利を記録します。OpenAIは、GPT画像モデルへのアクセスには組織の検証が必要になる可能性があると指摘しています。これを実行時の予期せぬ事態ではなく、オンボーディングの前提条件として扱ってください。

スナップショットポリシー

日付なしのIDを使用して、継続的なモデル更新を取得します。再現性がより重要な場合は、日付付きのスナップショットを固定します。本番トラフィックを変更する前に、同じベースラインを使用して新しいスナップショットを評価します。各アセットが返す、または設定された実際のモデル識別子を保存します。

起動記事にコードが含まれている場合は、その横に日付付きの検証日を表示してください。読者は、モデルの可用性、SDK の構文、レート制限、組織要件が、記事の概念的なアーキテクチャとは独立して変更される可能性があることを理解する必要があります。

型付きリクエスト契約

即使图像模型本身が構造化出力を提供しなくても、内部スキーマを定義する。タスクにはprompt（プロンプト）、workflow（ワークフロー）、model（モデル）、quality（品質）、width（幅）、height（高さ）、format（形式）、background（背景）、compression（圧縮）、参照リソースID、および冪等キーが含まれる場合がある。SDK呼び出しに変換する前に検証する。

ブラウザから任意のモデル名やファイルパスを露出しないでください。クライアント側で見える少数のオプションを、サーバーが承認した値にマッピングする必要があります。アクセス制御されたアセットIDを介して参照を解決し、現在のユーザーがこれらのアセットを読み取る権限を持っているかどうかを検証してください。

編集リクエスト草案

var i = [1, 2, 3];
function f() { return i; }

import OpenAI from "openai"; import fs from "fs";

const client = new OpenAI();

const result = await client.images.edit({ model: "gpt-image-2.5-sunburst", image: [fs.createReadStream("approved-character.png")], prompt: `コートだけを濃い緑色のウールに変更してください。顔、髪、目の色、姿勢、手、構図、背景を保持します。テキスト、宝石、または他の人を追加しないでください。 size: "1024x1536", quality: "高", output_format: "png" });

const bytes = Buffer.from(result.data[0].b64_json, "base64"); fs.writeFileSync("character-green-coat.png", bytes);


正確なSDKインターフェースは進化する可能性があるため、デプロイ前に現在の公式ガイドと照合してサンプルを検証してください。本番コードは、毎回の呼び出しが利用可能なデータを返すと想定するのではなく、責任を持ってストリーミング処理またはバッファリングし、レスポンスの存在を検証し、アトミックに保存する必要があります。

## 冪等性と重複コスト

ユーザーのダブルクリックやネットワークの再試行により、同じ高コストな生成タスクが二回送信される可能性があります。タスク作成時に冪等キーを割り当て、配布前にタスクを永続化し、同じキーが再度現れた場合には既存のタスクを返します。ワーカープロセスはタスクを一度だけ取得し、最終状態を記録する必要があります。

複数のバリエーションを生成する場合は、予期しない再試行ではなく、明確な製品操作として表現してください。画像APIはドキュメント上で`n`パラメータによる複数画像生成をサポートしていますが、コストと審査モデルでは出力ごとに統計を取る必要があります。

## レビューと失敗ユーザー体験

すべてのプロンプトと画像は安全フィルターを通過する必要があります。機密性の高い内部審査の詳細を漏らさないようにしつつ、ユーザーが合法的なリクエストを修正するための十分なガイダンスを提供してください。ポリシーによる拒否を、無効な設定、認証、レート制限、一時的なサービス障害と区別してください。

Sunburstが利用できない場合、他のモデルに静かに置き換えてはなりません。これは品質や契約条件に違反する可能性があります。明確なステータスを返すか、製品がその動作を開示し記録している場合にのみ代替案を使用すべきです。

## アセットの保存と配信

メモリ内でbase64をデコードし、サイズ制限を設定、宣言された形式を検証、チェックサムを生成し、不変の元ファイルを保存します。サムネイルは別途生成します。短期有効な署名付きURLと適切なコンテンツタイプで提供します。透明なPNG/WebPのアルファチャンネルを保持し、可逆変換による成果物の破損を防ぎます。

適切なアクセス制御を伴って、その機密レベルに応じたヒントや参考資料を保存してください。保存と削除の動作を定義してください。出典のない生成ファイルは、Elserアニメーションプロジェクトにとって監査、再現、または安全な引き渡しが困難です。

## 公開前チェックリスト

- アカウントと組織のアクセス権限が確認されました。
- APIキーはサーバー側でローテーション可能です。
- モデルIDと次元ルールはホワイトリストに追加されました。
- 課題提出は冪等です。
- リトライ回数は限られており、分類されています。
- 使用状況、遅延、受容性が監視されています。
- 画像とメタデータには保持ルールがあります。
- 身元、ブランド、およびテキストに敏感な出力については、人間による審査が存在します。
- 日付付きのスナップショットポリシーとロールバックパスが1件記録されました。

## よくある質問

### どちらのAPIを選ぶべきですか？
Image API は直接生成・編集に使用されます。Responses API は会話形式または複数ステップの画像体験に使用されます。

### 複数の画像をリクエストできますか？
Image APIは、ドキュメント内で複数の出力に対応する `n` パラメータをサポートしています。

### API は URL を返しますか？
現在のガイドでは、画像APIのbase64エンコードされた画像データを示しています。デコードして安全に保存してください。

## 結論

信頼性の高い統合は、明確なモデルルーティングと厳格な検証、可観測性、資産レビューを組み合わせます。まず最小限の直接リクエストを構築し、コア画像パスが信頼できる場合にのみ、会話状態や下流のアニメーションを追加します。