TokenLab

媒體指南

圖像生成

生成或編輯圖像,並處理完成的檔案或非同步任務

TokenLab 支援文字轉圖像 (text-to-image)、圖像轉圖像 (image-to-image) 以及圖像編輯。參數會因模型而異,因此請在發送請求前檢查所選模型的請求欄位。

選擇端點

需求端點使用時機不適用於
文字轉圖像POST /v1/images/generations使用者僅提供文字時編輯現有的 GPT Image 檔案
圖像轉圖像POST /v1/images/generations模型接受 operation: "image-to-image" 及圖像 URL 時需要 multipart 編輯輸入的模型
圖像編輯POST /v1/images/edits支援的編輯模型需修改現有圖像時Nano Banana 風格的參考生成
變體生成POST /v1/images/variations現有整合已使用變體 API 時新的參考圖像功能
狀態查詢GET /v1/tasks/{id}建立請求的回應包含 task_id、status: "pending" 或 poll_url 時建立請求的回應已包含最終的 data[] 時

請務必發送 model;圖像 API 不會為您選擇預設模型。

選擇模型

使用以下指令尋找目前的圖像模型:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

開啟所選模型的詳細資訊以確認:

  • 支援的操作,例如 text-to-image、image-to-image 或 image-edit。
  • 模型預期的請求端點。
  • 如何發送參考資料:image_url、image_urls、reference_image_urls、multipart image 或 JSON images[]。
  • 模型是否接受 size、aspect_ratio、resolution、quality、background、output_format 或 response_format。

模型特定欄位

  • gpt-image-2 風格的請求使用類似 OpenAI 的 size、quality 和編輯欄位。對於此模型的生成與編輯,background 接受 auto 或 opaque;不支援 transparent。省略選填欄位即可使用自動預設值。
  • Gemini 和 Nano Banana 圖像系列通常使用 aspect_ratio;僅在模型詳細資訊中顯示時才發送 resolution。在具有解析度層級的模型上,1K、2K 或 4K 的 size 會被視為 resolution 發送;若層級與 resolution 不符將會被拒絕。
  • Nano Banana 的圖像轉圖像應使用 /v1/images/generations 並搭配 operation: "image-to-image" 及參考圖像 URL。
  • /v1/images/generations 不接受頂層的 images[] 或 file_id;這些屬於編輯流程的格式。
  • 遠端圖像參考必須是公開的 http 或 https URL。請勿發送私人網路 URL、內嵌憑證、URL 片段或可能在處理開始前過期的簽章 URL。

文字轉圖像範例

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
    "size": "1024x1024",
    "response_format": "url"
  }'

參考圖像範例

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

取得圖像

圖像回應可以是同步或非同步的:

  • 同步回應會傳回包含 url 或 b64_json 的最終 data[]。
  • 非同步回應會傳回 id、task_id、status 以及通常包含的 poll_url。在支援公開非同步執行的模型上發送 "async": true,即可取得任務而非等待圖像生成。
  • 若要檢查非同步任務,請使用傳回的 id 或 task_id 呼叫 GET /v1/tasks/{id}。
  • 當您需要 b64_json 時,請使用同步請求;非同步圖像結果使用 URL。

圖像結果 URL 是 TokenLab 的媒體結果 URL,有效期為 30 天。media_retention.items 會回報每個項目的儲存狀態與 expires_at;當儲存狀態無法及時得知時,回應可能會省略 media_retention,但該 URL 仍然有效。內嵌的 Base64 結果不屬於此 URL 複製保留範圍。手動將圖像儲存至媒體庫 (Media Library) 會賦予其獨立的生命週期。請參閱 資料保留。

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

請保存傳回的圖像 URL、任務 ID、模型以及您自己的使用者/工作 ID。在達到終止狀態後,請勿繼續輪詢。

發布前準備

  • 在呼叫 TokenLab 前驗證使用者輸入:提示詞長度、圖像數量、URL 可達性及檔案類型。
  • 將 HTTP 超時時間設定得足夠長,以應對同步的高解析度請求。若模型支援,請針對長時間任務使用 async: true。
  • 儲存 request_id、task_id、poll_url、模型、端點以及發送的欄位名稱。
  • 當圖像請求傳回任務時,使用 Idempotency-Key 可確保建立請求可安全重試:在用戶端超時後,使用相同的金鑰發送相同的請求即可取得該任務。對於直接傳回圖像的請求,使用相同金鑰重試可能會傳回任務狀態而非圖像,或傳回 409 錯誤與 idempotent_response_not_replayable。若沒有金鑰,請在重試前檢查是否已建立任務。
  • 使用 Usage 和 billing_transaction_id 進行最終計費。

常見錯誤

徵狀可能原因修正方式
400 錯誤,param: "model"缺少明確的模型指定查詢 /v1/models?recommended_for=image 並發送 model
不支援的欄位該模型未記錄此欄位移除該欄位,或選擇有記錄該欄位的模型/端點
非同步結果無 b64_json非同步圖像任務傳回的是 URL 導向結果使用同步模式以取得 base64 輸出
參考圖像被拒絕端點錯誤或 URL 私有/過期符合模型記錄的參考格式,並使用可存取的 URL

API 參考

主題參考
建立圖像建立圖像
編輯圖像編輯圖像
建立圖像變體建立圖像變體
取得圖像狀態取得圖像狀態
取得任務狀態取得任務狀態

本頁內容