圖像生成

​

何時使用每個端點

​

選擇模型

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。當您希望模型或 TokenLab 使用自動默認值時，請省略可選字段。
• Gemini 和 Nano Banana 圖像系列通常使用 aspect_ratio；僅在模型說明公開時發送 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": "一張乾淨的陶瓷咖啡杯在胡桃木桌上的產品照片",
    "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",
    "operation": "image-to-image",
    "prompt": "保持產品形狀，將背景更改為明亮的工作室設置",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

​

處理結果

• 同步響應返回最終的 data[]，包含 url 或 b64_json。
• 異步響應返回 id、task_id、status，通常還有 poll_url。
• 當 poll_url 存在時，優先使用它。如果您需要固定路由，請輪詢 GET /v1/tasks/{id}。
• 當您特別需要 b64_json 時，使用同步請求；異步圖像結果是以 URL 為導向的。

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

​

生產檢查清單

• 在調用 TokenLab 之前驗證用戶輸入：提示長度、圖像數量、URL 可達性和文件類型。
• 對於同步高解析度請求，設置足夠高的 HTTP 超時。對於長時間工作，使用可用的異步模式。
• 存儲 request_id、task_id、poll_url、模型、端點和清理過的請求形狀以便支持。
• 在客戶端超時時，檢查任務是否已創建，然後再重試創建請求。
• 在存在時，根據使用記錄和 billing_transaction_id 來對賬成本，而不是根據供應商任務 ID。

​

常見錯誤

​

API 參考