> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 画像を編集

> プロンプトとソース画像を使用して画像を編集します

## 概要

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

このルートは次の両方をサポートします:

* 下記で説明する OpenAI 互換の `multipart/form-data` アップロードフロー
* サポートされる画像-to-画像ファミリー向けの `image_url`、`image_urls`、または公式 `images` 参照を含む JSON リクエスト

<Note>
  `gpt-image-2` はこのエンドポイントで利用できます。multipart `image` アップロード、JSON `image_url` / `image_urls`、公式 `images[]` 参照（`image_url` または `file_id`）に対応し、最大 16 枚のソース画像を受け付けます。`file_id` は先に `/v1/files` で作成してください。`async: true` を指定すると先にタスクを返します。公式 FLUX/BFL 編集モデルも同じタスクポーリングフローを使用します。

  `gpt-image-2` の編集では `resolution` と `background` は受け付けません。出力寸法には `size` を使用してください。複数画像または高レイテンシの編集では `async: true` を推奨し、返されたタスクをポーリングしてください。

  Nano Banana の参照画像リクエスト（`nano-banana`、`nano-banana-2`、`nano-banana-pro`）は `/v1/images/generations` で公開され、`operation: "image-to-image"` と `image_urls` を使用します。この `/v1/images/edits` エンドポイントには送信しないでください。

  xAI Grok Imagine 画像編集モデル（`grok-imagine-image`、`grok-imagine-image-quality`、および legacy `grok-imagine-image-pro`）はソース画像を最大 3 枚まで受け付けます。3 枚を超えるリクエストは入力検証で `400 too_many_images` として失敗します。

  `input_fidelity` は現在の TokenLab の `gpt-image-2` 支援欄位には含まれません。省略してください。送信すると `400 unsupported_parameter` が返ります。
</Note>

## リクエストボディ

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

リモート画像 URL: multipart 入力が必要な場合、TokenLab は JSON `image_url`、`image_urls`、または `images[].image_url` を取得し、そのバイト列を multipart の `image` パートとして送信します。URL は公開 `http`/`https` で、埋め込み認証情報やフラグメントを含まず、localhost、プライベート IP、予約済み IP 範囲へ解決されてはいけません。リダイレクト先も毎回再検証されます。取得される内容は実際の PNG、JPEG、または WebP 画像である必要があります。制限は画像 1 枚あたり `50MB`、URL 取得画像の合計 `200MB`/リクエスト、取得 timeout `10s`、最大 `3` リダイレクトです。

<ParamField body="image" type="file">
  multipart のソース画像。複数の GPT Image ソースを渡す場合は `image` を繰り返してください。ファイルは PNG、JPEG、または WebP、最大 16 枚、各 `50MB` までです。xAI Grok Imagine 編集モデルは同じ入力フィールドを使用しますが、ソース画像は 3 枚までです。
</ParamField>

<ParamField body="prompt" type="string" required>
  希望する編集内容のテキスト説明。
</ParamField>

<ParamField body="mask" type="file">
  完全に透明な領域が編集箇所を示す追加画像。有効な PNG ファイルで、50MB 未満、`image` と同じサイズである必要があります。

  JSON リクエストでは、`mask` を `image_url` または `file_id` のどちらか一方だけを含むオブジェクトとして送信できます。`file_id` は `/v1/files` で作成され、同じ画像編集設定に紐づいている必要があります。
</ParamField>

<ParamField body="model" type="string" required>
  画像編集に使用するモデル。GPT Image 編集には `gpt-image-2` を使用するか、`GET /v1/models?recommended_for=image` が返す現在の画像編集モデルを使用してください。
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成する画像の数。1 から 10 の間である必要があります。
</ParamField>

<ParamField body="size" type="string">
  生成画像のサイズ。`gpt-image-2` では `auto` または `WIDTHxHEIGHT` を使用します。寸法は 16 の倍数、最長辺は `3840px` 以下、長辺/短辺比は `3:1` 以下、総ピクセル数は `655,360` から `8,294,400` の範囲である必要があります。
</ParamField>

<ParamField body="response_format" type="string" default="url">
  生成画像の返却形式。`url` または `b64_json` である必要があり、デフォルトは `url` です。

  Azure Official または Azure-compatible の `gpt-image-2` リクエストでは、TokenLab は画像データを `b64_json` として受け取ります。`url` リクエストでは各画像を CDN にアップロードして `data[].url` を返します。CDN ストレージが利用できない、またはアップロードに失敗した場合は、Base64 レスポンスへ変換せずリクエストを失敗させます。`b64_json` では生の Base64 を返します。
</ParamField>

<ParamField body="async" type="boolean" default="false">
  `gpt-image-2` または公式 FLUX/BFL 編集モデルで `true` にすると、最終画像が準備できる前にタスクを返します。完了した非同期編集は、要求された `response_format` に関係なく URL を返します。`b64_json` が必要な場合は同期リクエストを使用してください。
</ParamField>

<ParamField body="user" type="string">
  不正利用監視のためのエンドユーザーの一意識別子。
</ParamField>

## レスポンス

<ResponseField name="created" type="integer">
  画像が作成された時の Unix タイムスタンプ。
</ResponseField>

<ResponseField name="data" type="array">
  生成された画像の配列。

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

  * `url` (string): 編集された画像の URL（response\_format が `url` の場合）
  * `b64_json` (string): Base64 エンコードされた画像（response\_format が `b64_json` の場合）
</ResponseField>

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

`gpt-image-2` または公式 FLUX/BFL 編集モデルで `async: true` を指定すると、リクエスト内で編集済み画像を待たずにタスクを作成します。レスポンスには `status: "pending"`、`task_id`、`poll_url` が含まれます。タスクが `completed` または `failed` になるまで `/v1/tasks/{task_id}` をポーリングしてください。

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

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

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.tokenlab.sh/v1"
  )

  response = client.images.edit(
      model="gpt-image-2",
      image=open("sunlit_lounge.png", "rb"),
      mask=open("mask.png", "rb"),
      prompt="A sunlit indoor lounge area with a pool",
      n=1,
      size="1024x1024"
  )

  print(response.data[0].url)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';
  import fs from 'fs';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.tokenlab.sh/v1'
  });

  const response = await client.images.edit({
    model: 'gpt-image-2',
    image: fs.createReadStream('sunlit_lounge.png'),
    mask: fs.createReadStream('mask.png'),
    prompt: 'A sunlit indoor lounge area with a pool',
    n: 1,
    size: '1024x1024'
  });

  console.log(response.data[0].url);
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "fmt"
      "io"
      "mime/multipart"
      "net/http"
      "os"
  )

  func main() {
      body := &bytes.Buffer{}
      writer := multipart.NewWriter(body)

      writer.WriteField("model", "gpt-image-2")

      image, _ := os.Open("sunlit_lounge.png")
      defer image.Close()
      part, _ := writer.CreateFormFile("image", "sunlit_lounge.png")
      io.Copy(part, image)

      mask, _ := os.Open("mask.png")
      defer mask.Close()
      maskPart, _ := writer.CreateFormFile("mask", "mask.png")
      io.Copy(maskPart, mask)

      writer.WriteField("prompt", "A sunlit indoor lounge area with a pool")
      writer.WriteField("n", "1")
      writer.WriteField("size", "1024x1024")
      writer.Close()

      req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/images/edits", body)
      req.Header.Set("Authorization", "Bearer sk-your-api-key")
      req.Header.Set("Content-Type", writer.FormDataContentType())

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      result, _ := io.ReadAll(resp.Body)
      fmt.Println(string(result))
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/images/edits');

  $image = new CURLFile('sunlit_lounge.png', 'image/png', 'sunlit_lounge.png');
  $mask = new CURLFile('mask.png', 'image/png', 'mask.png');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => [
          'model' => 'gpt-image-2',
          'image' => $image,
          'mask' => $mask,
          'prompt' => 'A sunlit indoor lounge area with a pool',
          'n' => 1,
          'size' => '1024x1024'
      ]
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  echo $data['data'][0]['url'];
  ```
</RequestExample>

<ResponseExample>
  ```json レスポンス theme={null}
  {
    "created": 1706000000,
    "data": [
      {
        "url": "https://..."
      }
    ]
  }
  ```
</ResponseExample>

## 注意事項

<Note>
  リモート画像の取得失敗は、生成開始前に入力エラーとして返されます。アクセスできない URL、timeout、403/404 応答、プライベート/内部ホスト、URL 内の認証情報やフラグメント、画像ではないコンテンツ、未対応形式、サイズ制限超過は `400` または `413` を返し、`image_url` / `image_urls[n]` 入力を示します。プライベートまたはヘッダー保護された素材は、multipart `image` ファイルとして直接アップロードするか、`/v1/files` 参照を作成してください。
</Note>