媒體指南
圖像生成
生成或編輯圖像,並處理完成的檔案或非同步任務
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、multipartimage或 JSONimages[]。 - 模型是否接受
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或httpsURL。請勿發送私人網路 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 |