概覽
對於 coding agent,請先透過GET /v1/models?recommended_for=image 找出目前推薦的圖片模型清單,然後把選定的 model 明確傳給這個端點。
gpt-image-2 是按 token 計費的 GPT Image 模型。TokenLab 依 OpenAI 官方 usage 明細結算文字輸入、圖片輸入、已回報的快取輸入與圖片輸出 token;它不是固定每張圖片計費的模型。
對於 gpt-image-2 圖像生成,公共參數支援 prompt、n、size、quality、response_format、async、background、output_format、output_compression 或 compression、moderation 和 user。未傳 size 或 quality 時 TokenLab 會使用 auto;自訂 size 必須使用下方說明的彈性 WIDTHxHEIGHT 契約。
input_fidelity 不屬於目前 TokenLab 對 gpt-image-2 的支援欄位;請省略該欄位,否則請求會返回 400 unsupported_parameter。
模型行為說明
Google Gemini 圖片系列不共用同一套選擇器契約:gemini-3.1-flash-image、gemini-3-pro-image和nano-banana-pro在公開的文字生圖、圖片編輯/圖生圖操作中支援aspect_ratio和resolution(1k、2k、4k)。nano-banana-2在目前 TokenLab 契約中僅文字生圖支援aspect_ratio和resolution(1k、2k、4k)。gemini-2.5-flash-image、nano-banana和nano-banana-edit支援aspect_ratio,但不提供公開的resolution選項。- Nano Banana 參考圖請求請在本端點(
/v1/images/generations)使用nano-banana-edit或nano-banana-pro,並傳送operation: "image-to-image"與image_urls。不要把 Nano Banana 參考圖請求送到/v1/images/edits。 - Nano Banana 圖生圖請求中,
nano-banana-pro可以傳送resolution(1k、2k、4k);nano-banana-edit必須省略此參數。nano-banana和nano-banana-2在目前対応状況中是文字生圖模型。 - 本端點的參考圖可以透過 JSON
image_url/image_urls傳入,也可以用 multipartimage檔案直接上傳。/v1/images/generations不接受images[]或file_id;只有明確支援images[].file_id的/v1/images/edits模型才使用/v1/files回傳的引用。
aspect_ratio,只有模型明確支援時才傳送 resolution。
xAI Grok Imagine 圖片模型(grok-imagine-image、grok-imagine-image-quality 以及 legacy grok-imagine-image-pro)支援 aspect_ratio 與 resolution(1k、2k)。grok-imagine-image-pro 會作為 grok-imagine-image-quality 的相容 ID 保留。
請求本文
同步請求逾時: 某些圖片請求會以内嵌方式返回最終圖片,並等待生成完成。高解析度或高品質請求可能接近一分鐘甚至更久,因此請將 HTTP 用戶端逾時設定為至少120s。如果建立回應包含 status: "pending"、task_id 或 poll_url,請改為依照返回的 poll_url 輪詢。
要使用的模型(例如
gpt-image-2、flux-pro、qwen-image-plus 或 nano-banana-pro)。使用 GET /v1/models?recommended_for=image 取得目前推薦清單。所需圖片的文字描述。
用於圖生圖的公開 HTTPS 參考圖 URL。Nano Banana 參考圖請求請將
operation 設為 image-to-image;nano-banana-pro 可以傳送 resolution,nano-banana-edit 應省略此參數。公開 HTTPS 參考圖 URL 陣列。JSON 請求需要一張或多張參考圖時使用此欄位。本端點不支援
file_id 和 images[]。額外的模型特定參考圖 URL,用於區分主要輸入圖與參考圖的供應商。
用於圖生圖的 multipart 參考圖檔案。來源圖片是私有或需要請求標頭授權時,請使用直接上傳。這不同於 /v1/files 的
file_id;本端點不接受 file_id。要產生的圖片數量(1-10,依模型而定)。
圖片尺寸。用於 OpenAI 風格的圖片系列,以及接受精確像素尺寸的其他模型。對於
gpt-image-2,size 接受 auto 或 WIDTHxHEIGHT。自訂寬高都必須是 16 的倍數,最長邊不超過 3840px,長邊/短邊比例不超過 3:1,總像素必須介於 655,360 到 8,294,400 之間。aspect_ratio 與 resolution 目前不屬於 TokenLab 對 gpt-image-2 的対応状況。對於 Google Gemini 圖片系列,size 會被視為相容別名,映射到模型公開的 aspect_ratio 契約,以及在支援時的 resolution 契約。建議對這些模型直接傳送 aspect_ratio。依模型而定的長寬比選擇器。Google 圖片系列常見值包括
1:1、16:9、9:16、3:2、2:3。依模型而定的輸出解析度選擇器。
gemini-3.1-flash-image 和 gemini-3-pro-image 在文字生圖與圖片編輯中支援此參數;nano-banana-pro 在文字生圖與圖生圖中支援;nano-banana-2 僅文字生圖支援。常見值為 1k、2k、4k。除非模型明確說明,否則不要傳給僅支援比例選擇的 Gemini 圖片系列。xAI Grok Imagine 圖片模型請使用 1k 或 2k。圖片品質。
gpt-image-2 等 GPT Image 模型使用 auto、low、medium 或 high。其他圖片系列可能使用提供者特定取值;傳送非預設值前請先查看所選模型的 metadata。回應格式:
url 或 b64_json,預設為 url。對於 Azure Official 或 Azure-compatible 的 gpt-image-2 請求,TokenLab 會以 b64_json 接收圖片資料。請求 url 時,TokenLab 會把每張圖上傳到 CDN 並返回 data[].url。如果 CDN 儲存不可用或上傳失敗,請求會失敗,而不是改為 Base64 回應;請求 b64_json 時直接返回原始 Base64。搭配
gpt-image-2 或官方 FLUX/BFL 圖像模型設為 true 時,會先建立任務。完成後的非同步圖片任務無論請求的 response_format 是什麼,都只返回 URL;如果需要 b64_json,請使用同步請求。選填風格選擇器。只有所選模型明確文件化支援時才傳送;除非模型 metadata 另有說明,否則不要對
gpt-image-2 傳送此欄位。終端使用者的唯一識別碼。
回應
即時回應
建立時間的 Unix timestamp。
產生圖片的陣列。每個物件包含:
url(string):產生圖片的 URLb64_json(string):Base64 編碼的圖片(若有要求)revised_prompt(string): 所選模型回傳的選填 prompt 改寫結果
非同步任務回應
搭配gpt-image-2 或官方 FLUX/BFL 圖像模型設定 async: true 後,建立請求會先返回任務,而不是等待最終圖片完成。回應包含 status: "pending"、task_id 和 poll_url。請輪詢 /v1/tasks/{task_id},直到任務進入 completed 或 failed。
非同步圖片任務最終只返回圖片 URL。如果你需要原始 b64_json 圖片資料,請使用同步請求。
任務建立時可能會先預留預估費用。任務完成後按實際用量結算;失敗或逾時的任務會釋放預留費用或退回費用。
建立時間的 Unix 時間戳。
用於輪詢的唯一任務識別碼。
初始狀態:
pending。用於輪詢結果的相對 URL,例如
/v1/tasks/{id}。任務處於 pending 時為空。已完成的圖片任務會在
data[].url 中回傳產生的圖片 URL。status: "pending" 時,請使用 poll_url 或 GET /v1/tasks/{task_id} 來取得結果。
可用模型
以下是目前常見模型範例,不是固定目錄。最新可用性和價格請查詢GET /v1/models?recommended_for=image 或模型頁面。
| 模型 | 類型 | 特性 |
|---|---|---|
gpt-image-2 | Inline 或 task-based | 按 token 計費的 GPT Image 模型,支援彈性尺寸 |
flux-pro | 通常為 task-based | 寫實、高品質 |
qwen-image-plus | 通常為 task-based | 文字渲染與 prompt 遵循較強 |
nano-banana-pro | 通常為 task-based | 參考圖工作流與高解析度輸出 |
grok-imagine-image | 通常為 task-based | xAI 圖片生成,支援比例與解析度選擇 |
ideogram-v3 | 通常為 task-based | 文字渲染較強 |
status: "pending",請跟隨 poll_url 輪詢直到完成。
處理任務式回應
對於圖片模型,請一律檢查回應是否包含status: "pending":