TokenLab
取得 API Key
文件API 參考整合

圖像

編輯圖片

根據提示詞與原始圖片編輯圖片

POST
/v1/images/edits

概覽

根據原始圖片與提示詞，建立一張經過編輯或擴展的圖片。

此端點同時支援：

  • 下文記錄的 OpenAI 相容 multipart/form-data 上傳流程
  • 提供 image_url、image_urls 或官方 images 參照的 JSON 請求，適用於支援的圖對圖 (image-to-image) 模型系列

此處支援 gpt-image-2。它接受 multipart image 上傳、JSON image_url / image_urls 以及官方 images[] 參照（image_url 或 file_id），最多可包含 16 張來源圖片。請先透過 /v1/files 建立 file_id 值。設定 async: true 可先回傳任務；官方 FLUX/BFL 編輯模型也使用相同的任務輪詢流程。

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/generations，並使用 operation: "image-to-image" 和 image_urls，而非此 /v1/images/edits 端點。nano-banana-2、nano-banana-2.1、nano-banana-2-lite 和 nano-banana-pro 的圖片編輯請求同樣使用 /v1/images/generations，並搭配 operation: "image-edit"。

gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3.1-flash-lite-image 和 gemini-3-pro-image 使用此端點進行圖片編輯。它們的圖對圖請求則使用 /v1/images/generations 並搭配 operation: "image-to-image"。

xAI Grok Imagine 圖片編輯模型的來源圖片數量有上限：grok-imagine-image-2.0 最多 5 張，grok-imagine-image 和舊版 grok-imagine-image-pro 最多 3 張。超過模型上限的請求將會失敗，並回傳 400 too_many_images 的輸入驗證錯誤。

input_fidelity 並非目前 TokenLab 對 gpt-image-2 支援的欄位；請省略此欄位，否則請求將回傳 400 unsupported_parameter。

請求主體 (Request Body)

同步請求逾時： 部分圖片請求會直接回傳最終圖片並等待生成完成。高解析度或高品質請求可能需要接近一分鐘或更長時間，因此請將您的 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 範圍；每次重新導向都會再次檢查。擷取的內容必須是真實的 PNG、JPEG 或 WebP 圖片。限制為每張圖片 50 MiB，單次請求中透過 URL 擷取的圖片總計 200 MiB，擷取逾時為 30s，最多允許 3 次重新導向。

對於 JSON 請求，請提供 image_url、image_urls 或 images 中的其中一種。每個 images[] 物件必須包含 image_url 或 file_id 中的其中一個。200 MiB 的總量限制包含所有來源圖片與遮罩 (mask)。

imagefile

Multipart 來源圖片。重複 image 欄位可提供多個 GPT Image 來源。檔案必須為 PNG、JPEG 或 WebP 格式，最多 16 張來源圖片，每張上限 50 MiB。xAI Grok Imagine 編輯模型使用相同的輸入欄位，但來源圖片有上限：grok-imagine-image-2.0 最多 5 張，其他 xAI 編輯模型最多 3 張。

promptstring必填

所需編輯內容的文字描述。

maskfile | object

額外的圖片，其完全透明的區域表示應編輯圖片的位置。必須是有效的 PNG 檔案，小於 50 MiB，且尺寸必須與 image 相同。

對於 JSON 請求，mask 也可以是一個物件，其中包含 image_url 或 file_id 中的其中一個；file_id 值必須來自 /v1/files 並保持綁定到相同的圖片編輯配置。

modelstring必填

用於圖片編輯的模型。請使用 gpt-image-2 進行 GPT Image 編輯，或使用 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 不同，將回傳 400 並帶有 invalid_image_size_contract 代碼。建議格式為 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

與 gpt-image-2 或官方 FLUX/BFL 編輯模型搭配使用時，設定為 true 可在最終圖片準備好之前先回傳任務。已完成的非同步編輯無論請求的 response_format 為何，皆會回傳 URL；若需要 b64_json，請使用同步請求。

userstring

代表您終端使用者的唯一識別碼，用於濫用監控。

回應 (Response)

createdinteger

圖片建立時的 Unix 時間戳記。

dataarray

生成的圖片陣列。

每個物件包含：

  • url (string)：編輯後圖片的 TokenLab 媒體結果 URL，有效期 30 天。當 response_format 為 b64_json 時不存在。當省略 response_format 且 TokenLab 無法儲存圖片時，此欄位亦會缺失。
  • b64_json (string)：Base64 圖片資料。當 response_format 為 b64_json，或省略該欄位且模型回傳圖片位元組時存在。

非同步任務回應 (Async Task Response)

與 gpt-image-2 或官方 FLUX/BFL 編輯模型搭配使用時，設定 async: true 可建立任務，而非在請求中等待編輯後的圖片。回應包含 status: "pending"、task_id 和 poll_url。請輪詢 /v1/tasks/{task_id} 直到任務狀態變為 completed 或 failed。

非同步編輯任務僅回傳最終圖片 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] 輸入。對於私有或受標頭保護的資產，請直接上傳 multipart image 檔案或建立 /v1/files 參照。

Hy Image 3.5 Preview 可從文字建立 1024 像素的正方形圖片，並根據書面指令編輯參考圖片。它適用於視覺草圖繪製與構圖優化。

{
  "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 Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified，並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"

請求主體

回應

application/json

application/json

application/json

application/json

application/json

application/json

建立圖片

上一頁

建立圖像變體

下一頁