跳转到主要内容
TokenLab 支持通过公共图像端点进行文本到图像、图像到图像和图像编辑。图像模型不共享一个通用的参数集，因此生产客户端应首先选择端点，然后选择模型，然后仅发送该模型支持的字段。

​
何时使用每个端点

用户工作流程端点使用时机避免时机
文本到图像POST /v1/images/generations用户仅从提示开始需要官方的 GPT 图像编辑流程
图像到图像POST /v1/images/generations模型文档通过 operation: "image-to-image" 以及 image_url、image_urls 或 reference_image_urls 引用图像模型期望多部分编辑输入
图像编辑POST /v1/images/edits您正在使用支持的编辑模型（如 GPT 图像系列模型）编辑现有图像您正在使用 Nano Banana 风格的图像到图像生成
变体POST /v1/images/variations您维护一个遗留的变体兼容集成您正在构建新的参考图像工作流程
状态GET /v1/tasks/{id}创建响应返回 task_id、status: "pending" 或 poll_url创建响应已经包含最终的 data[]
始终发送 model。图像端点故意不依赖于历史隐式默认模型来处理生产流量。

​
选择模型

从模型发现开始，然后检查所选模型的 TokenLab 契约： 
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"
对于非聊天模型，列表响应可能包括 tokenlab.public_contract_summary。模型详细页面可能会暴露更完整的 tokenlab.public_contract。使用这些字段进行确认：
  • 支持的操作，例如 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 和编辑字段。当您希望模型或 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"
保存返回的图像 URL、任务 ID、模型和您自己的用户/作业 ID。在终端状态后请勿继续轮询。

​
生产检查清单

  • 在调用 TokenLab 之前验证用户输入：提示长度、图像数量、URL 可达性和文件类型。
  • 将 HTTP 超时设置得足够高，以便进行同步高分辨率请求。在可用的情况下使用异步模式以处理长时间工作。
  • 存储 request_id、task_id、poll_url、模型、端点和清理后的请求形状以供支持。
  • 在客户端超时的情况下，检查任务是否已创建，然后再重试创建请求。
  • 在存在时与使用记录和 billing_transaction_id 对账，而不是与供应商任务 ID 对账。

​
常见错误

症状可能原因修复
400 和 param: "model"缺少显式模型查询 /v1/models?recommended_for=image 并发送 model
不支持的字段字段不在该模型的公共契约中删除该字段或选择文档中包含该字段的模型/端点
异步结果中没有 b64_json异步图像任务返回以 URL 为导向的结果使用同步模式以获取 base64 输出
参考图像被拒绝错误的端点或私有/过期的 URL匹配模型文档中的参考形状并使用可达的 URL

​
API 参考

主题参考
创建图像创建图像
编辑图像编辑图像
创建图像变体创建图像变体
获取图像状态获取图像状态
获取任务状态获取任务状态