图片生成

TokenLab 支持文生图、图生图和图片编辑。不同模型的参数不一样，发送请求前请查看所选模型支持的字段。

选择 APICopy Anchor Link

请求中必须包含 model，图片端点没有默认模型。

选择模型Copy Anchor Link

用下面的请求查找当前图片模型：

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。

不同模型使用不同字段Copy Anchor Link

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

文生图示例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。状态已经是 completed 或 failed 后不再继续查询。

上线前检查Copy Anchor Link

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

常见错误Copy Anchor Link

API 参考Copy Anchor Link