圖像生成

TokenLab 支援透過公共圖像端點進行文本到圖像、圖像到圖像和圖像編輯。圖像模型不共享一組通用參數，因此生產客戶端應首先選擇端點，然後選擇模型，然後僅發送該模型支持的字段。

何時使用每個端點Copy Anchor Link

始終發送 model。圖像端點故意不依賴於歷史隱式默認模型來處理生產流量。

選擇模型Copy Anchor Link

從模型發現開始，然後檢查所選模型的 TokenLab 合約：

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

對於非聊天模型，列表響應可能包括 GET /v1/models。模型詳細頁面可能會顯示更完整的 GET /v1/models/{model}。使用這些字段來確認：

• 支持的操作，例如 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。

請求形狀規則Copy Anchor Link

• 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。

文本到圖像範例Copy Anchor Link

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"
  }'

參考圖像範例Copy Anchor Link

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": "保持產品形狀，將背景更改為明亮的工作室設置",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

處理結果Copy Anchor Link

圖像響應可以是同步或異步的：

• 同步響應返回最終的 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"

持久化返回的圖像 URL、任務 ID、模型和您自己的用戶/作業 ID。在終端狀態後請勿繼續輪詢。

生產檢查清單Copy Anchor Link

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

常見錯誤Copy Anchor Link

API 參考Copy Anchor Link