图片生成

​

选择 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。
• 应该使用哪个 API。
• 参考图应该放在 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。
• Nano Banana 图像到图像应在 /v1/images/generations 上，带有 operation: "image-to-image" 和参考图像 URL。
• /v1/images/generations 不接受顶层 images[] 或 file_id；这些字段用于图片编辑。
• 远程图片必须能通过 http 或 https 访问。不要使用内网地址、带凭据的地址、URL fragment，或即将过期的签名 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-2",
    "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"

​

上线前检查

• 检查提示词长度、图片数量、URL 是否可访问，以及文件类型。
• 高分辨率同步请求需要更长超时；模型支持异步时，耗时任务可以使用异步模式。
• 保存 request_id、task_id、poll_url、模型、API 地址和请求字段名。
• 客户端超时后，确认没有创建任务再重新提交。
• 最终费用以 Usage 和 billing_transaction_id 为准。

​

常见错误

​

API 参考