画像

画像の編集

プロンプトとソース画像を指定して画像を編集

POST
/v1/images/edits

概要

元の画像とプロンプトを指定して、編集または拡張された画像を作成します。

このエンドポイントは、以下の両方をサポートしています:

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

ここでは gpt-image-2 がサポートされています。マルチパートの image アップロード、JSON の image_url / image_urls、および公式の images[] 参照(image_url または file_id)を受け入れ、最大 16 個のソース画像に対応します。file_id の値は、事前に /v1/files で作成してください。最初にタスクを返すには async: true を設定します。gpt-image-2 や FLUX 編集モデルなど、サポートされているパラメータに async がリストされているすべてのモデルは、同じタスクポーリングフローを使用します。

gpt-image-2 の編集では resolution は受け入れられません。出力寸法には size を使用してください。background は auto または opaque を受け付けますが、transparent はサポートされていません。複数画像の編集や高レイテンシの編集の場合は、async: true を指定して、返されたタスクをポーリングすることをおすすめします。

Nano Banana の参照画像リクエスト(nano-banana-2、nano-banana-2.1、nano-banana-2-lite、nano-banana-pro)は、この /v1/images/edits エンドポイントではなく、operation: "image-to-image" および image_urls を指定して /v1/images/generations で公開されています。nano-banana-2、nano-banana-2.1、nano-banana-2-lite、nano-banana-pro の画像編集リクエストも、operation: "image-edit" を指定して /v1/images/generations を使用します。

gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3.1-flash-lite-image、および gemini-3-pro-image は、画像編集にこのエンドポイントを使用します。これらの image-to-image リクエストは、operation: "image-to-image" を指定して /v1/images/generations を使用します。

xAI Grok Imagine 画像編集モデルが受け付けるソース画像の数には制限があります。grok-imagine-image-2.0 は最大 5 個、grok-imagine-image は最大 3 個まで受け付けます。モデルが受け付ける数を超えるソース画像を含むリクエストは、入力検証に失敗し、400 too_many_images が返されます。これらの image-to-image リクエストもこのエンドポイントを使用します。

各モデルの詳細(GET /v1/models/{model}、モデルの取得 を参照)では、各操作のエンドポイントが tokenlab.request_format_summary.request_endpoint_by_operation に、受け入れ可能なフィールドと制限が tokenlab.request_format_details.operation_constraints に記載されています。誤ったエンドポイントに送信された操作は 400 unsupported_endpoint を返します。

input_fidelity は現在の TokenLab の gpt-image-2 対応フィールドには含まれていません。省略しない場合、リクエストは 400 unsupported_parameter を返します。

リクエストボディ

同期リクエストのタイムアウト: 一部の画像リクエストは最終画像をインラインで返し、生成が完了するまで待機します。高解像度または高品質のリクエストは 1 分近く、またはそれ以上かかる場合があるため、HTTP クライアントのタイムアウトを少なくとも 120s に設定してください。作成レスポンスに status: "pending"、task_id、または poll_url が含まれている場合は、代わりに GET /v1/tasks/{task_id} をポーリングしてください。

リモート画像 URL:マルチパート入力が必要な場合、TokenLab は JSON の image_url、image_urls、または images[].image_url を取得し、そのバイトデータをマルチパートの image パートとして送信します。URL は、埋め込み認証情報やフラグメントを含まない公開 http/https でなければならず、localhost、プライベート IP、または予約済み IP の範囲に解決されてはなりません。リダイレクトのたびに再確認されます。取得されるペイロードは、実際の PNG、JPEG、または WebP 画像である必要があります。制限は、画像 1 枚あたり 50 MiB、1 回のリクエストで URL から取得する画像全体で合計 200 MiB、フェッチタイムアウトは 30s、リダイレクトは最大 3 回までです。

JSON リクエストの場合は、image_url、image_urls、または images のいずれか 1 つだけを指定してください。各 images[] オブジェクトには、image_url または file_id のいずれか 1 つのみを含める必要があります。合計 200 MiB の制限には、すべてのソース画像とマスクが含まれます。

imagefile

マルチパートのソース画像。image を繰り返して指定することで、複数の GPT Image ソースを提供できます。ファイルは PNG、JPEG、または WebP である必要があり、ソース画像は最大 16 個、各 50 MiB までです。xAI Grok Imagine 編集モデルも同じ入力フィールドを使用しますが、ソース画像の上限が異なります。grok-imagine-image-2.0 は最大 5 個、その他の xAI 編集モデルは最大 3 個までです。

promptstring必須

希望する編集内容のテキスト説明。最大 32,000 文字。詳細に prompt がリストされているすべてのモデルで必須です。stability-upscale-fast などのプロンプトを使用しないツールは、プロンプトなしで呼び出されます。

maskfile | object

完全に透明な領域によって画像の編集すべき場所を示す追加画像。有効な PNG ファイルであり、50 MiB 未満で、image と同じ寸法である必要があります。

JSON リクエストの場合、mask は image_url または file_id のいずれか 1 つのみを含むオブジェクトとすることもできます。file_id の値は /v1/files から取得したものであり、同じ画像編集設定に関連付けられたままである必要があります。

modelstring必須

画像編集に使用するモデル。GPT Image の編集には gpt-image-2 を使用するか、GET /v1/models?recommended_for=image によって返されるその他の現在の画像編集モデルを使用します。

nintegerデフォルト: 1

生成する画像の数(1〜10、モデルに依存)。

sizestring

生成される画像のサイズ。gpt-image-2 の場合は、auto または WIDTHxHEIGHT を使用します。寸法は 16 の倍数、最長辺は最大 3840px、長辺と短辺の比率は最大 3:1、総ピクセル数は 655,360 から 8,294,400 の間である必要があります。

gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3-pro-image、および gemini-3.1-flash-lite-image の場合、size はモデルのサイズテーブルの出力サイズ、または解像度ティア(1K、2K、4K)を受け入れます。TokenLab はティアを resolution として送信します。モデルがサポートしていないティア、または resolution と異なるティアを指定すると、コード invalid_image_size_contract とともに 400 が返されます。推奨される形式は、aspect_ratio と resolution の組み合わせです。

response_formatstring

画像の返却形式:url または b64_json。

  • 省略時:モデルが画像バイトを返す場合、各画像は data[].b64_json に格納され、TokenLab が保存した場合は data[].url にも格納されます。モデルがリンクを返す場合、各画像は data[].url に格納されます。
  • url:各画像は data[].url にのみ格納されます。
  • b64_json:各画像は Base64 データとして data[].b64_json にのみ格納されます。

リンクは TokenLab のメディア結果 URL です。30 日間有効です。データ保持 を参照してください。

asyncbooleanデフォルト: false

最終的な画像の準備ができる前にタスクを返す場合は true に設定します。gpt-image-2 など、サポートされているパラメータに async がリストされているモデルのみがこれを受け入れます。その他のモデルの場合、リクエストは 400 unsupported_async_mode を返します。完了した非同期編集は、リクエストされた response_format に関わらず URL を返します。b64_json が必要な場合は同期リクエストを使用してください。

userstring

不正利用の監視を目的とした、エンドユーザーを表す一意の識別子。

レスポンス

createdinteger

画像が作成されたときの Unix タイムスタンプ。

dataarray

生成された画像の配列。

各オブジェクトには以下が含まれます:

  • url (string):編集された画像の TokenLab メディア結果 URL(30 日間有効)。response_format が b64_json の場合は存在しません。response_format が省略されている場合、TokenLab が画像を保存できなかったときは欠落します。
  • b64_json (string):Base64 画像データ。response_format が b64_json の場合、または省略されてモデルが画像バイトを返す場合に存在します。
usageobject

利用可能な場合、gpt-image-2 などのトークン課金モデルのトークン数(input_tokens、output_tokens、total_tokens、およびそれらの詳細)。

非同期タスクのレスポンス

これをサポートするモデルで async: true を設定すると、リクエスト内で編集された画像を待つ代わりにタスクが作成されます。レスポンスには status: "pending"、task_id、および poll_url が含まれます。タスクが completed または failed に達するまで、/v1/tasks/{task_id} をポーリングしてください。

非同期編集タスクは最終画像の URL のみを返します。生の b64_json 画像データが必要な場合は、同期リクエストを使用してください。

課金では、タスク作成時に見積もり金額が仮確保される場合があります。完了したタスクには実際の使用量に応じて課金され、失敗またはタイムアウトしたタスクは解放または返金されます。

リクエスト

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

レスポンス

Response
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

注意事項

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

タイムアウト後にリクエストを安全に再試行するには、Idempotency-Key ヘッダーを送信してください。Idempotency Key で安全に再試行 を参照してください。

Hy Image 3.5 Preview は、テキストの指示に基づいて参照画像を編集します。size は 1024x1024、n は 1 のみを受け付けます:

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

認証

BearerAuth
AuthorizationBearer <token>

APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。

場所: header

ヘッダー

X-TokenLab-Delivery-Policy?string

リクエストごとの配信ポリシー。APIキーおよびWorkspaceのデフォルト設定を上書きします。自動的にまず TokenLab Verified を試行し、出力、リクエストの受け入れ、または永続的なリソース作成の前に、一度だけ Official に切り替える場合があります。

指定できる値

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

リクエストによってタスクが作成された場合に、画像リクエストを安全に再試行するためのオプションのキー。リクエストごとに新しい一意の値(UUIDなど)を送信してください。同じキーとボディで再試行すると、そのタスクが返され、2つ目のタスクの作成、ディスパッチ、課金は行われません。画像を直接返すリクエストの場合、同じキーでの再試行は画像ではなくタスクステータス、または409とidempotent_response_not_replayableを返すことがあります。すでに受け入れられたキーで異なるボディを指定すると拒否されますが、その場合のステータスコードとエラーコードは保証されません。255文字を超えるキーは無視され、そのリクエストには冪等性保護が適用されません。詳細は冪等性キーを使用した安全な再試行を参照してください。

長さ1 <= length <= 255

リクエストボディ

レスポンス

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json