画像連携を SeedRouter へ移行する

画像 API を SeedRouter へ移行するには、API キーとベース URL を差し替えるだけでなく、リクエストとレスポンスの契約を確認する必要があります。GPT Image 2 は見慣れた画像生成の項目を使いますが、送信で返るのはタスク ID です。アプリケーションはその ID を保存し、完了までポーリングし、仕上がった画像 URL を読む必要があります。

意味のある最小の移行は、サーバー側コードからのテキスト画像生成リクエスト 1 件です。参照画像の編集、マスク、大きなバッチに進む前に、まずこれを通してください。新しい経路が同じ受け入れ確認を通るまでは、既存の連携を使える状態にしておきます。

どの前提を変える必要がありますか？

画像リクエストを使えるファイルに変換しているコードを見つけてください。今は最初のレスポンスに画像が含まれることを期待していたり、base64 のフィールドをデコードしていたり、multipart アップロードを使っていたりするかもしれません。これらの前提は SeedRouter の GPT Image 2 リファレンスと個別に照合する必要があります。

だからこそ、ベース URL を設定できる同期的な Images SDK であっても、そのまま置き換えられるわけではありません。必要なモデル設定はそのまま残しつつ、結果を待って利用するアプリケーションコードを作り替えてください。

コードを動かす前にリクエスト項目を対応付ける

まず model、prompt、size、quality、n から始めます。モデル ID は gpt-image-2 を使ってください。サイズは 1024x1024 のように明示するか auto を使います。既存の resolution 項目や比率の文字列を、そのままサイズとして持ち込まないでください。

SeedRouter の OpenAPI ドキュメントは確認の助けになります。呼び出し箇所で見える引数だけを見るのではなく、SDK が補う値も含めて、アプリケーションが実際に送信している項目を比較してください。未知の項目は拒否されます。

このモデルでは style、response_format、設定可能な input_fidelity は受け付けられるリクエスト項目ではありません。汎用のオプションオブジェクトに隠すのではなく、これらの前提を取り除いてください。リクエストは stream と partial_images にも対応していません。この連携で進捗を伝えるのはタスクのステータスです。

出力設定には依存関係があります。透過を求めるなら PNG を選んでください。output_compression は JPEG のときだけ送り、PNG では送りません。圧縮値 0 は有効なので、真偽判定で既定値に置き換えてしまわないようにしてください。これらは、基本的なリクエストが成功しただけでは通らない細部です。

同期レスポンスという前提を置き換える

次の Node.js の例は、リクエストを 1 件送信してタスク ID を出力します。SEEDROUTER_API_KEY はサーバー上で設定してください。キーをブラウザのコードや公開される環境変数に置いてはいけません。

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',
    prompt: 'A cobalt-blue ceramic mug on a pale gray tabletop.',
    size: '1024x1024',
    quality: 'low',
    n: 1,
  }),
  signal: AbortSignal.timeout(60000),
});
const task = await response.json();
if (!response.ok) {
  // Preserve a task reference if one accompanies an uncertain submission.
  if (typeof task.id === 'string') console.log('Task reference:', task.id);
  throw new Error(`Submission needs review: HTTP ${response.status}`);
}
if (typeof task.id !== 'string' || !task.id) throw new Error('Missing task ID.');
console.log(task.id); // Persist this ID with your application's image record.

手動のスモークテストなら ID を出力するだけで十分です。ただしアプリケーションでは、ユーザーに制御を返す前に保存してください。そうすればユーザーが別の画面に移っても画像レコードは保留のまま残り、あとで確認して結果を回収できます。

進捗の確認には、同じ認可ヘッダーで GET https://api.seedrouter.ai/v1/tasks/{id} を使います。completed なら output.data[].url を読みます。failed なら文書化されたエラーを処理し、適切な失敗状態を表示してください。進捗を永続化する実行可能な例はバッチ送信とポーリングを参照してください。

画像のダウンロードリクエストに API キーを付けないでください。認可はタスク API の呼び出しに属するものであり、返されたアセット URL を別途取得する際のものではありません。

参照画像とマスクを URL 入力へ移す

既存のローカルファイル方式には準備のひと手間が増えます。参照画像を、あなたが管理するアクセス可能な HTTP(S) URL に置いてください。そして images: [{"image_url": "https://example.com/reference.png"}] の形で渡し、このアドレスはご自身のものに置き換えます。ファイルパス、blob: URL、base64 の data URL、Files ID は送らないでください。

その URL がブラウザのログイン Cookie なしで開けることを確認してください。ログイン済みセッションでしか開けない URL は、このリクエストで使える参照画像ではありません。タスクの処理中は画像へのアクセスを維持し、送信直後にアクセス権を取り消さないでください。

マスクは mask: {"image_url": "https://example.com/mask.png"} の形で指定し、参照画像が必要です。1 枚目の参照画像とサイズが一致していなければなりません。既存の編集フローを移す前に、メディア入力の制約、とくにファイル形式とファイルサイズをすべて確認してください。

移行の受け入れテストは何を確認すべきですか？

中断を含め、アプリケーションが依存している動作をテストしてください。画像が 1 枚成功したことが証明するのは、そのリクエストが動いたことだけです。保留状態が再読み込みに耐えることも、ダウンロード失敗時に二重生成を避けられることも証明しません。

• テキストのみのリクエストを送信し、ポーリング前に返された ID を保存する。
• ポーリングを止め、同じ ID で再開し、追加の POST が発生しないことを確認する。
• processing、completed、failed を別々の状態として扱う。
• API の認可ヘッダーを送らずに、完了した画像をダウンロードする。
• アクセス可能な URL で参照画像の編集を確認し、次にアクセスできない URL で失敗処理を確認する。
• 圧縮値 0 を含む任意項目を、公開されているスキーマで検証する。
• アカウントの請求額を、架空のタスクレスポンス費用項目ではなく使用履歴から読んでいることを確認する。

再現可能な失敗・タイムアウトのテストにはモックレスポンスを使ってください。これらの確認が通ってから、意図的に小さな実環境テストを行います。実際の生成は残高を消費します。送信結果が不確かな場合は、再試行する前に調査してください。ローカルで例外が出たことは、タスクが受理されなかった証拠にはなりません。

よくある質問

既存のプロンプトはそのまま使えますか？

リクエストの制約を満たしていれば、出発点としては使えます。比較用に代表的なプロンプトをいくつか残しておくとよいですが、繰り返し生成して同一の画像が得られるとは考えないでください。

新しいクライアントライブラリは必要ですか？

ここでの例には必要ありません。標準的な HTTP リクエストで十分です。どのクライアントを選ぶにせよ、完成画像がすぐ返ることを期待するのではなく、タスクの送信とポーリングを扱える必要があります。

最終的な費用はどこで分かりますか？

アカウントの使用履歴で確認できます。完了タスクにはトークン使用量が含まれることがありますが、その公開レスポンスに金額項目はありません。見積もりについては料金ガイドを参照してください。

アプリケーションの境界で移行を完了させる

画像 API の移行が完了したといえるのは、アプリケーションが結果のライフサイクル全体、すなわち受理されたタスク、保留状態、完成した出力、ダウンロード、失敗を扱えるようになったときです。最初の変更は小さく保ち、中断のケースをテストし、入力と出力の前提を確認してから残りのリクエストを移してください。