TokenLabでのGPT Image Edit API：正しいエンドポイントと画像入力形式

画像編集は、AI製品の機能の中でも特に負荷の高い部分の1つです。ユーザーが写真をアップロードし、変更内容を指示すると、結果が返ってくることが期待されます。複数のソース画像を使用する編集、大きなキャンバス、またはより重いプロンプトを伴う編集は、一般的な同期HTTP呼び出しで快適に処理できる時間を超えることがあります。このガイドでは、正しいTokenLabエンドポイント、サポートされている2つの画像入力形式、複数画像の編集、および処理が遅いリクエスト向けの非同期パスについて説明します。

エンドポイント

画像編集は POST /v1/images/edits にあります。複数形の edits である点に注意してください。（よくある間違いとして /images/edit と記述されることがありますが、これはドキュメントに記載されたパスではありません。）

このエンドポイントは、以下の2つのリクエスト形式をサポートしています：

• OpenAI互換の multipart/form-data アップロードフロー。
• サポートされているimage-to-imageファミリー向けに image_url、image_urls、または公式の images[] 参照を提供するJSONリクエスト。

リクエストとレスポンスの全フィールドについては、Edit Image API リファレンス に記載されています。

ここでgpt-image-2が受け付けるもの

• Multipartの image アップロード。
• JSONの image_url または image_urls。
• 各オブジェクトに image_url または file_id のいずれか1つのみが含まれる、公式の images[] 参照。
• 1リクエストあたり最大 16枚のソース画像。

コードを記述する前に知っておくべき制約事項がいくつかあります：

• gpt-image-2 の編集では resolution を受け付けません。出力サイズには size を使用してください（auto、または16の倍数の寸法で最長辺が最大3840px、長辺/短辺の比率が最大3:1の WIDTHxHEIGHT）。
• background は auto または opaque を受け付けます。transparent はサポートされていません。
• input_fidelity は gpt-image-2 でサポートされているフィールドではありません。これを送信すると 400 unsupported_parameter が返されます。
• JSONリクエストの場合は、image_url、image_urls、または images のうち、正確に1つだけを指定してください。各 images[] オブジェクトには、image_url または file_id のいずれか1つのみを含める必要があります。file_id の値は、事前に /v1/files を通じて作成されている必要があります。
• Nano Bananaの参照画像リクエストは /v1/images/edits ではなく、operation: "image-to-image" および image_urls を指定して /v1/images/generations に送信する必要があります。

Multipartアップロード vs JSON画像参照

gpt-image-2 ではどちらも機能します。画像バイトがすでにどこに存在しているかに応じて選択してください。

Multipart — ユーザーによるアップロードや生成されたアセットなど、アプリケーションがファイルを保持している場合に使用します。複数のソースを送信するには、image フィールドを繰り返します。ファイルはPNG、JPEG、またはWebPである必要があり、それぞれ最大50 MiBです。

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

JSON画像URL — 画像がすでにパブリックURL上に存在する場合、または以前のTokenLabリクエストで生成してすでにURLを持っている場合に使用します。

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

リモートURLは、埋め込み認証情報やフラグメントを含まないパブリックな http/https である必要があり、localhost、プライベート、または予約済みのIP範囲に解決されてはなりません。TokenLabはバイトを取得し、multipartの image パートとしてモデルに渡します。画像1枚あたりの制限は50 MiB、1リクエストでURL取得される画像の合計制限は200 MiB、取得タイムアウトは30秒、リダイレクトは最大3回まで追跡されます。

複数画像の編集と非同期ポーリング

複数画像の編集は、async: true を使用する最も明確なユースケースです。複数の画像を複雑な指示セットとともに同期呼び出しで送信すると、モデルが必要とする時間だけ接続を開いたまま維持することになります。gpt-image-2（および公式のFLUX/BFL編集モデル）で async: true を設定すると、代わりにタスクを受け取ります：

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

返された poll_url をポーリングするか、フォールバックとして GET /v1/tasks/{task_id} を使用します。ステータスは pending、processing、completed、および failed です。完了した画像タスクは data[].url を返します。3〜5秒ごとに確認すれば十分です。ポーリングを続けるのではなく、終端ステータスで停止してください。

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

非同期編集タスクは、リクエストされた response_format に関わらず、最終的な画像URLを返します。生の b64_json が必要な場合は、同期リクエストを使用してください。

請求に関しては、タスク作成時に推定金額が仮確保される場合があります。完了したタスクは実際の使用量に応じて請求され、失敗したタスクやタイムアウトしたタスクは仮確保が解除または返金されます。ライフサイクルの詳細については 非同期ジョブとポーリング を、レスポンスフィールドについては 画像ステータスの取得 を参照してください。

各モードをいつ使用すべきか

次のような場合は async: true を使用します：

• 1つのリクエストで複数のソース画像を送信する場合。
• プロンプトまたは指示セットが複雑で、生成時間が予測できない場合。
• リアルタイムなユーザー向けリクエストではなく、バックグラウンドジョブ、キュー、またはバッチ処理で編集を実行する場合。

次のような場合は同期のままにします：

• 短いプロンプトで単一画像の編集を行う場合。
• クライアントがポーリングを行うよりも即時失敗（fail-fast）を好む場合。

同期呼び出しの場合、HTTPクライアントのタイムアウトは少なくとも 120s に設定してください。高解像度または高品質のリクエストは、1分近く、あるいはそれ以上かかることがあります。作成レスポンスに依然として status: "pending"、task_id、または poll_url が返された場合は、返されたポーリングフローに切り替えてください。

想定される入力エラー

リモート画像の取得エラーは、生成が開始される前に入力エラーとして返されます。到達不能なURL、タイムアウト、403/404レスポンス、プライベートまたは内部ホスト、URL内の認証情報やフラグメント、画像以外のコンテンツ、サポートされていない形式、およびサイズ制限違反は 400 または 413 を返し、問題のある image_url または image_urls[n] を特定します。プライベートまたはヘッダーで保護されたアセットの場合は、multipartの image ファイルを直接アップロードするか、/v1/files 参照を作成して images[].file_id として渡してください。

xAI Grok Imagine画像編集モデル（たとえば grok-imagine-image や grok-imagine-image-quality）は同じ入力フィールドを使用しますが、ソース画像は最大3枚に制限されています。それを超えると 400 too_many_images が返されます。

統合チェックリスト

• POST /v1/images/edits を対象にし、model を明示的に送信する。
• 画像がすでにどこにあるかに応じて、multipartアップロードまたはJSON参照を選択する。
• JSONリクエストでは image_url、image_urls、または images[] のうち正確に1つだけを送信する。各 images[] エントリには image_url または file_id のいずれか1つのみを含める。
• 複数画像や重い編集には async: true を使用する。タスクが completed または failed に達するまで、返された poll_url をポーリングする。
• 同期リクエストの場合はクライアントのタイムアウトを少なくとも120秒に設定し、pending レスポンスが返された場合は poll_url に従って処理する。
• クライアント側でタイムアウトが発生した場合は、二重課金を避けるため、作成リクエストを再試行する前にタスクが作成されたかどうかを確認する。

はじめに

GET /v1/models?recommended_for=image をクエリして現在の画像モデルを確認し、リクエストを送信する前にモデルの詳細ページを開いてサポートされている操作とリクエストフィールドを確認してください。コンソールからAPIキーを作成し、独自の画像を使用して編集エンドポイントをテストしましょう。