圖像
編輯圖片
根據提示詞與來源圖片編輯圖片
概觀
根據原始圖片和提示詞建立編輯後或擴展後的圖片。
此端點同時支援以下兩者:
- 下方說明的 OpenAI 相容
multipart/form-data上傳流程 - 針對支援的圖生圖模型系列,提供
image_url、image_urls或官方images引用的 JSON 請求
gpt-image-2 在此受支援。它接受 multipart image 上傳、JSON image_url / image_urls,以及官方 images[] 引用(image_url 或 file_id),最多可提供 16 張來源圖片。請先透過 /v1/files 建立 file_id 值。設定 async: true 可優先返回任務;每個在其支援參數中列出 async 的模型(例如 gpt-image-2 和 FLUX 編輯模型)皆使用相同的任務輪詢流程。
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 最多接受 3 張。若請求包含超過模型所能接受的來源圖片數量,輸入驗證將失敗並返回 400 too_many_images。它們的圖生圖請求也使用此端點。
每個模型的詳細資訊(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。
請求主體
同步請求逾時: 部分圖片請求會在內嵌中返回最終圖片,並等待生成完成。高解析度或高品質的請求可能需要將近一分鐘或更長時間,因此請將您的 HTTP 客戶端逾時時間設定為至少 120s。如果建立回應包含 status: "pending"、task_id 或 poll_url,請改為輪詢 GET /v1/tasks/{task_id}。
遠端圖片 URL:當需要 multipart 輸入時,TokenLab 會擷取 JSON 中的 image_url、image_urls 或 images[].image_url,並將其 byte 資料作為 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 的總量限制包含所有來源圖片與遮罩。
Multipart 來源圖片。可重複傳入 image 以提供多個 GPT Image 來源。檔案必須為 PNG、JPEG 或 WebP,最多 16 張來源圖片,且每張上限為 50 MiB。xAI Grok Imagine 編輯模型使用相同的輸入欄位,但限制來源圖片數量:grok-imagine-image-2.0 最多 5 張,其他 xAI 編輯模型最多 3 張。
所需編輯內容的文字描述,最多 32,000 個字元。凡是詳細資訊中列出 prompt 的模型皆為必填。沒有提示詞的工具(例如 stability-upscale-fast)調用時不需傳入。
額外的圖片,其完全透明的區域指示應編輯圖片的位置。必須是有效的 PNG 檔案,小於 50 MiB,且尺寸必須與 image 相同。
對於 JSON 請求,mask 也可以是恰好包含 image_url 或 file_id 其中之一的物件;file_id 值必須來自 /v1/files 且維持綁定至相同的圖片編輯設定。
用於圖片編輯的模型。針對 GPT Image 編輯使用 gpt-image-2,或使用 GET /v1/models?recommended_for=image 返回的其他目前圖片編輯模型。
1要生成的圖片數量(1-10,取決於模型)。
生成圖片的尺寸。對於 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。
圖片返回格式:url 或 b64_json。
- 省略:當模型返回圖片 byte 資料時,每張圖片會位於
data[].b64_json中,當 TokenLab 有儲存時也會位於data[].url中。當模型返回連結時,每張圖片會位於data[].url中。 url:每張圖片僅位於data[].url中。b64_json:每張圖片僅作為 Base64 資料位於data[].b64_json中。
連結為 TokenLab 媒體結果 URL。其有效期為 30 天。請參閱資料保留。
false設為 true 可在最終圖片準備就緒前先返回任務。僅在其支援參數中列出 async 的模型才接受此參數,例如 gpt-image-2;對於任何其他模型,請求將返回 400 unsupported_async_mode。無論請求的 response_format 為何,已完成的非同步編輯都會返回 URL;當您需要 b64_json 時,請使用同步請求。
代表您使用者的唯一識別碼,用於濫用監控。
回應
圖片建立時的 Unix 時間戳記。
生成的圖片陣列。
每個物件包含:
url(string):編輯後圖片的 TokenLab 媒體結果 URL,有效期為 30 天。當response_format為b64_json時不存在。當省略response_format且 TokenLab 無法儲存圖片時亦會缺少。b64_json(string):Base64 圖片資料。當response_format為b64_json,或省略該參數且模型返回圖片 byte 資料時出現。
對於按 token 計費的模型(例如 gpt-image-2),提供 token 計數(input_tokens、output_tokens、total_tokens 及其詳細資訊)(若有)。
非同步任務回應
在支援的模型上設定 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"回應
{
"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。對於私有或受 header 保護的資產,請直接上傳 multipart image 檔案或建立 /v1/files 引用。
在逾時後傳送 Idempotency-Key header 以安全地重試請求;請參閱使用冪等性金鑰安全重試。
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 API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
選填鍵值,若請求已建立任務,則使圖像請求可安全重試。請為每個請求發送一個新的唯一值(例如 UUID)。使用相同鍵值與相同主體的重試會回傳該任務,且不會建立、分發或扣款第二次任務。對於直接回傳圖像的請求,使用相同鍵值的重試可能會回傳任務狀態而非圖像,或回傳 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