图像生成

​

何时使用每个端点

​

选择模型

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、多部分 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 参考