跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
概覽

對於 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、partial_images 和 user。未傳 size 或 quality 時 TokenLab 會使用 auto；自訂 size 必須使用下方說明的彈性 WIDTHxHEIGHT 契約。 相容性說明：如果 gpt-image-2 請求帶上 input_fidelity，TokenLab 會在轉送前移除該欄位，因為 GPT Image 2 已自動以高保真處理圖片輸入。

​
模型行為說明

Google Gemini 圖片系列不共用同一套選擇器契約：
  • gemini-3.1-flash-image-preview、gemini-3-pro-image-preview、nano-banana-2 和 nano-banana-pro 在文字生圖生成中支援 aspect_ratio 以及 resolution（1k、2k、4k）。
  • gemini-2.5-flash-image、nano-banana 和 nano-banana-edit 支援 aspect_ratio，但不提供公開的 resolution 選項。
  • gemini-2.0-flash-preview-image-generation 在此文件中被描述為僅以提示文字進行文字轉圖片。
  • 對於 nano-banana、nano-banana-2 和 nano-banana-pro 的參考圖請求，請使用本端點（/v1/images/generations），並傳送 operation: "image-to-image" 與 image_urls。不要把 Nano Banana 參考圖請求送到 /v1/images/edits。
  • Nano Banana 圖生圖請求請省略 resolution。nano-banana-2 和 nano-banana-pro 只在文字生圖中公開 resolution，nano-banana 不公開此參數。
  • 本端點的參考圖可以透過 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-image、grok-imagine-image-quality 以及 legacy grok-imagine-image-pro）支援 aspect_ratio 與 resolution（1k、2k）。grok-imagine-image-pro 會保留為相容 ID，並在 upstream 路由至 grok-imagine-image-quality。

​
請求本文

同步請求逾時： 某些路由到的圖片提供者會以内嵌方式返回最終圖片，並等待生成完成。高解析度或高品質請求可能接近一分鐘甚至更久，因此請將 HTTP 用戶端逾時設定為至少 120s。如果建立回應包含 status: "pending"、task_id 或 poll_url，請改為依照返回的 poll_url 輪詢。
​
model
string
預設值:"dall-e-3"
要使用的模型（例如：gpt-image-2、dall-e-3、flux-pro、midjourney）。
​
prompt
string
必填
所需圖片的文字描述。
​
image_url
string
用於圖生圖的公開 HTTPS 參考圖 URL。Nano Banana 系列請將 operation 設為 image-to-image，並且除非該模型明確支援此操作的 resolution，否則不要傳送 resolution。
​
image_urls
string[]
公開 HTTPS 參考圖 URL 陣列。JSON 請求需要一張或多張參考圖時使用此欄位。本端點不支援 file_id 和 images[]。
​
reference_image_urls
string[]
額外的模型特定參考圖 URL，用於區分主要輸入圖與參考圖的供應商。
​
image
file
用於圖生圖的 multipart 參考圖檔案。來源圖片是私有或需要請求標頭授權時，請使用直接上傳。這不同於 /v1/files 的 file_id；本端點不接受 file_id。
​
n
integer
預設值:"1"
要產生的圖片數量（1-10，依模型而定）。
​
size
string
預設值:"1024x1024"
圖片尺寸。用於 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。
​
aspect_ratio
string
依模型而定的長寬比選擇器。Google 圖片系列常見值包括 1:1、16:9、9:16、3:2、2:3。
​
resolution
string
依模型而定的輸出解析度選擇器。支援於 gemini-3.1-flash-image-preview、gemini-3-pro-image-preview、nano-banana-2、nano-banana-pro 以及類似的高解析度系列。常見值為 1k、2k、4k。除非模型明確說明，否則不要傳給僅支援比例選擇的 Gemini 圖片系列。xAI Grok Imagine 圖片模型請使用 1k 或 2k。
​
quality
string
預設值:"standard"
圖像品質。DALL-E 模型使用 standard 或 hd；gpt-image-2 等 GPT Image 模型使用 auto、low、medium 或 high。
​
response_format
string
預設值:"url"
回應格式：url 或 b64_json，預設為 url。對於 Azure Official 或 Azure-compatible 的 gpt-image-2 路由，TokenLab 不會把 response_format 傳給上游。閘道始終從上游取得 b64_json 圖片資料；請求 url 時會把每張圖上傳到 CDN 並返回 data[].url。如果 CDN 儲存不可用或上傳失敗，請求會失敗，而不是降級返回 Base64；請求 b64_json 時直接返回原始 Base64。
​
async
boolean
預設值:"false"
搭配 gpt-image-2 或官方 FLUX/BFL 圖像模型設為 true 時，會先建立任務。完成後的非同步圖片任務無論請求的 response_format 是什麼，都只返回 URL；如果需要 b64_json，請使用同步請求。
​
style
string
預設值:"vivid"
DALL-E 3 的風格：vivid 或 natural。
​
user
string
終端使用者的唯一識別碼。

​
回應

​
即時回應

​
created
integer
建立時間的 Unix timestamp。
​
data
array
產生圖片的陣列。每個物件包含：
  • url（string）：產生圖片的 URL
  • b64_json（string）：Base64 編碼的圖片（若有要求）
  • revised_prompt（string）：實際使用的 prompt（DALL-E 3）

​
非同步任務回應

搭配 gpt-image-2 或官方 FLUX/BFL 圖像模型設定 async: true 後，建立請求會先返回任務，而不是等待最終圖片完成。回應包含 status: "pending"、task_id 和 poll_url。請輪詢 /v1/tasks/{task_id}，直到任務進入 completed 或 failed。 非同步圖片任務最終只返回圖片 URL。如果你需要原始 b64_json 圖片資料，請使用同步請求。 任務建立時可能會先預留預估費用。任務完成後按實際用量結算；失敗或逾時的任務會釋放預留費用或退回費用。
​
created
integer
建立時間的 Unix 時間戳。
​
task_id
string
用於輪詢的唯一任務識別碼。
​
status
string
初始狀態：pending。
​
poll_url
string
用於輪詢結果的相對 URL，例如 /v1/tasks/{id}。
​
data
array
任務處於 pending 時為空。已完成的圖片任務會在 data[].url 中回傳產生的圖片 URL。
當你收到 status: "pending" 時，請使用 poll_url 或 GET /v1/tasks/{task_id} 來取得結果。 
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
    }
  ]
}