Skip to main content

概述

根據原始圖像和提示詞建立編輯或擴展的圖像。 此端點同時支援:
  • 下方文件中的 OpenAI 相容 multipart/form-data 上傳流程
  • 為受支援的圖像到圖像模型提供 image_urlimage_urls 或官方 images 參照的 JSON 請求
gpt-image-2 已支援此端點。它支援 multipart image 上傳、JSON image_url / image_urls,以及官方 images[] 參照(image_urlfile_id),最多 16 張來源圖。file_id 需先透過 /v1/files 建立。設定 async: true 會先返回任務;官方 FLUX/BFL 編輯模型也使用同一套任務輪詢流程。gpt-image-2 編輯不接受 resolution;輸出尺寸請使用 sizebackground 接受 autoopaque,不支援 transparent。多圖或高延遲編輯建議設定 async: true 並輪詢返回任務。Nano Banana 參考圖請求(nano-banananano-banana-2nano-banana-pro)公開在 /v1/images/generations,應使用 operation: "image-to-image"image_urls,不要送到本 /v1/images/edits 端點。xAI Grok Imagine 圖像編輯模型(grok-imagine-imagegrok-imagine-image-quality 以及 legacy grok-imagine-image-pro)最多接受 3 張來源圖。超過 3 張的請求會在輸入校驗階段返回 400 too_many_imagesinput_fidelity 不屬於目前 TokenLab 對 gpt-image-2 的支援欄位;請省略該欄位,否則請求會返回 400 unsupported_parameter

請求主體

同步請求逾時: 某些圖片請求會以内嵌方式返回最終圖片,並等待生成完成。高解析度或高品質請求可能接近一分鐘甚至更久,因此請將 HTTP 用戶端逾時設定為至少 120s。如果建立回應包含 status: "pending"task_idpoll_url,請改為依照返回的 poll_url 輪詢。 遠端圖片 URL:當需要 multipart 輸入時,TokenLab 會抓取 JSON image_urlimage_urlsimages[].image_url,並把圖片位元組作為 multipart image 檔案送出。URL 必須是公網 http/https,不能包含使用者名稱密碼或 fragment,不能解析到 localhost、內網或保留 IP;每次重新導向後的目標也會重新校驗。抓取到的內容必須是真實 PNG、JPEG 或 WebP 圖片。限制為單圖 50MB、單次請求 URL 抓取圖片總計 200MB、抓取逾時 10s、最多 3 次重新導向。
file
multipart 來源圖片。需要多張 GPT Image 來源圖時,可以重複傳送 image 欄位。檔案必須是 PNG、JPEG 或 WebP,最多 16 張來源圖,每張不超過 50MB。xAI Grok Imagine 編輯模型使用相同輸入欄位,但來源圖最多 3 張。
string
必填
描述所需編輯的文字。
file
一個附加圖像,其完全透明的區域指示應編輯圖像的位置。必須是有效的 PNG 檔案,小於 50MB,且與 image 具有相同的尺寸。對於 JSON 請求,mask 也可以是一個物件,且只能包含 image_urlfile_id 其中之一;file_id 必須來自 /v1/files,並且綁定到同一套圖像編輯設定。
string
必填
用於圖片編輯的模型。GPT Image 編輯請使用 gpt-image-2,也可以使用 GET /v1/models?recommended_for=image 回傳的其他目前圖片編輯模型。
integer
預設值:"1"
要生成的圖像數量。必須在 1 到 10 之間。
string
生成圖片的尺寸。對於 gpt-image-2,使用 autoWIDTHxHEIGHT;寬高必須是 16 的倍數,最長邊不超過 3840px,長邊/短邊比例不超過 3:1,總像素介於 655,3608,294,400 之間。
string
預設值:"url"
回傳生成圖像的格式。必須是 urlb64_json,預設為 url對於 Azure Official 或 Azure-compatible 的 gpt-image-2 請求,TokenLab 會以 b64_json 接收圖片資料。請求 url 時,TokenLab 會把每張圖上傳到 CDN 並返回 data[].url。如果 CDN 儲存不可用或上傳失敗,請求會失敗,而不是改為 Base64 回應;請求 b64_json 時直接返回原始 Base64。
boolean
預設值:"false"
搭配 gpt-image-2 或官方 FLUX/BFL 編輯模型設為 true 時,會在最終圖片完成前先返回任務。完成後的非同步編輯無論請求的 response_format 是什麼,都只返回 URL;如果需要 b64_json,請使用同步請求。
string
代表終端使用者的唯一識別碼,用於濫用監控。

回應

integer
圖像建立時間的 Unix 時間戳。
array
生成的圖像陣列。每個物件包含:
  • url (string): 編輯後圖像的 URL(如果 response_format 是 url
  • b64_json (string): Base64 編碼的圖像(如果 response_format 是 b64_json

非同步任務回應

搭配 gpt-image-2 或官方 FLUX/BFL 編輯模型設定 async: true 後,請求會先建立任務,而不是等待編輯後圖片完成。回應包含 status: "pending"task_idpoll_url。請輪詢 /v1/tasks/{task_id},直到任務進入 completedfailed 非同步編輯任務最終只返回圖片 URL。如果你需要原始 b64_json 圖片資料,請使用同步請求。 任務建立時可能會先預留預估費用。任務完成後按實際用量結算;失敗或逾時的任務會釋放預留費用或退回費用。

注意事項

遠端圖片抓取失敗會在生成開始前作為輸入錯誤返回。URL 無法存取、逾時、403/404、私有或內網主機、URL 中包含使用者名稱密碼或 fragment、非圖片內容、不支援的格式、超過大小限制,都會返回 400413,並指向 image_url / image_urls[n] 輸入。私有或需要請求標頭鑑權的素材,請直接用 multipart image 上傳,或建立 /v1/files 參照。