Skip to main content

概覽

對於 coding agent,請先透過 GET /v1/models?recommended_for=image 找出目前推薦的圖片模型清單,然後把選定的 model 明確傳給這個端點。 gpt-image-2 是按 token 計費的 GPT Image 模型。TokenLab 依 OpenAI 官方 usage 明細結算文字輸入、圖片輸入、已回報的快取輸入與圖片輸出 token;它不是固定每張圖片計費的模型。 對於 gpt-image-2 圖像生成,公共參數支援 promptnsizequalityresponse_formatasyncbackgroundoutput_formatoutput_compressioncompressionmoderationuserbackground 接受 autoopaque,不支援 transparent。未傳 sizequality 時 TokenLab 會使用 auto;自訂 size 必須使用下方說明的彈性 WIDTHxHEIGHT 契約。 input_fidelity 不屬於目前 TokenLab 對 gpt-image-2 的支援欄位;請省略該欄位,否則請求會返回 400 unsupported_parameter

模型行為說明

Google Gemini 圖片系列不共用同一套選擇器契約:
  • gemini-3.1-flash-imagegemini-3-pro-imagenano-banana-pro 在公開的文字生圖、圖片編輯/圖生圖操作中支援 aspect_ratioresolution1k2k4k)。
  • nano-banana-2 在目前 TokenLab 契約中僅文字生圖支援 aspect_ratioresolution1k2k4k)。
  • gemini-2.5-flash-imagenano-banananano-banana-edit 支援 aspect_ratio,但不提供公開的 resolution 選項。
  • Nano Banana 參考圖請求請在本端點(/v1/images/generations)使用 nano-banana-editnano-banana-pro,並傳送 operation: "image-to-image"image_urls。不要把 Nano Banana 參考圖請求送到 /v1/images/edits
  • Nano Banana 圖生圖請求中,nano-banana-pro 可以傳送 resolution1k2k4k);nano-banana-edit 必須省略此參數。nano-banananano-banana-2 在目前対応状況中是文字生圖模型。
  • 本端點的參考圖可以透過 JSON image_url / image_urls 傳入,也可以用 multipart image 檔案直接上傳。/v1/images/generations 不接受 images[]file_id;只有明確支援 images[].file_id/v1/images/edits 模型才使用 /v1/files 回傳的引用。
Google 圖片系列請優先使用 aspect_ratio,只有模型明確支援時才傳送 resolution xAI Grok Imagine 圖片模型(grok-imagine-imagegrok-imagine-image-quality 以及 legacy grok-imagine-image-pro)支援 aspect_ratioresolution1k2k)。grok-imagine-image-pro 會作為 grok-imagine-image-quality 的相容 ID 保留。

請求本文

同步請求逾時: 某些圖片請求會以内嵌方式返回最終圖片,並等待生成完成。高解析度或高品質請求可能接近一分鐘甚至更久,因此請將 HTTP 用戶端逾時設定為至少 120s。如果建立回應包含 status: "pending"task_idpoll_url,請改為依照返回的 poll_url 輪詢。
string
必填
要使用的模型(例如 gpt-image-2flux-proqwen-image-plusnano-banana-pro)。使用 GET /v1/models?recommended_for=image 取得目前推薦清單。
string
必填
所需圖片的文字描述。
string
用於圖生圖的公開 HTTPS 參考圖 URL。Nano Banana 參考圖請求請將 operation 設為 image-to-imagenano-banana-pro 可以傳送 resolutionnano-banana-edit 應省略此參數。
string[]
公開 HTTPS 參考圖 URL 陣列。JSON 請求需要一張或多張參考圖時使用此欄位。本端點不支援 file_idimages[]
string[]
額外的模型特定參考圖 URL,用於區分主要輸入圖與參考圖的供應商。
file
用於圖生圖的 multipart 參考圖檔案。來源圖片是私有或需要請求標頭授權時,請使用直接上傳。這不同於 /v1/files 的 file_id;本端點不接受 file_id
integer
預設值:"1"
要產生的圖片數量(1-10,依模型而定)。
string
預設值:"1024x1024"
圖片尺寸。用於 OpenAI 風格的圖片系列,以及接受精確像素尺寸的其他模型。對於 gpt-image-2size 接受 autoWIDTHxHEIGHT。自訂寬高都必須是 16 的倍數,最長邊不超過 3840px,長邊/短邊比例不超過 3:1,總像素必須介於 655,3608,294,400 之間。aspect_ratioresolution 目前不屬於 TokenLab 對 gpt-image-2 的対応状況。對於 Google Gemini 圖片系列,size 會被視為相容別名,映射到模型公開的 aspect_ratio 契約,以及在支援時的 resolution 契約。建議對這些模型直接傳送 aspect_ratio
string
依模型而定的長寬比選擇器。Google 圖片系列常見值包括 1:116:99:163:22:3
string
依模型而定的輸出解析度選擇器。gemini-3.1-flash-imagegemini-3-pro-image 在文字生圖與圖片編輯中支援此參數;nano-banana-pro 在文字生圖與圖生圖中支援;nano-banana-2 僅文字生圖支援。常見值為 1k2k4k。除非模型明確說明,否則不要傳給僅支援比例選擇的 Gemini 圖片系列。xAI Grok Imagine 圖片模型請使用 1k2k
string
預設值:"standard"
圖片品質。gpt-image-2 等 GPT Image 模型使用 autolowmediumhigh。其他圖片系列可能使用提供者特定取值;傳送非預設值前請先查看所選模型的 metadata。
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
選填風格選擇器。只有所選模型明確文件化支援時才傳送;除非模型 metadata 另有說明,否則不要對 gpt-image-2 傳送此欄位。
string
終端使用者的唯一識別碼。

回應

即時回應

integer
建立時間的 Unix timestamp。
array
產生圖片的陣列。每個物件包含:
  • url(string):產生圖片的 URL
  • b64_json(string):Base64 編碼的圖片(若有要求)
  • revised_prompt (string): 所選模型回傳的選填 prompt 改寫結果

非同步任務回應

搭配 gpt-image-2 或官方 FLUX/BFL 圖像模型設定 async: true 後,建立請求會先返回任務,而不是等待最終圖片完成。回應包含 status: "pending"task_idpoll_url。請輪詢 /v1/tasks/{task_id},直到任務進入 completedfailed 非同步圖片任務最終只返回圖片 URL。如果你需要原始 b64_json 圖片資料,請使用同步請求。 任務建立時可能會先預留預估費用。任務完成後按實際用量結算;失敗或逾時的任務會釋放預留費用或退回費用。
integer
建立時間的 Unix 時間戳。
string
用於輪詢的唯一任務識別碼。
string
初始狀態:pending
string
用於輪詢結果的相對 URL,例如 /v1/tasks/{id}
array
任務處於 pending 時為空。已完成的圖片任務會在 data[].url 中回傳產生的圖片 URL。
當你收到 status: "pending" 時,請使用 poll_urlGET /v1/tasks/{task_id} 來取得結果。

可用模型

以下是目前常見模型範例,不是固定目錄。最新可用性和價格請查詢 GET /v1/models?recommended_for=image 或模型頁面。 不要把模型硬編碼為永遠同步或永遠非同步。如果建立回應返回 status: "pending",請跟隨 poll_url 輪詢直到完成。

處理任務式回應

對於圖片模型,請一律檢查回應是否包含 status: "pending"