媒体指南

图片生成

生成或编辑图片,并处理直接结果与异步任务

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

选择 API

想做什么API适合不适合
文生图POST /v1/images/generations只从文字开始生成编辑已有的 GPT Image 图片
图生图POST /v1/images/generations模型接受 operation: "image-to-image" 和图片 URL必须使用 multipart 图片的编辑模型
图片编辑POST /v1/images/edits用支持编辑的模型修改已有图片Nano Banana 一类的参考图生成
图片变体POST /v1/images/variations已有功能就在使用 Variations API新建参考图功能
查询状态GET /v1/tasks/{id}创建响应带有 task_id、pending 或 poll_url响应已经返回最终 data[]

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

选择模型

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

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。在有分辨率档位的模型上,size 为 1K、2K 或 4K 时会作为 resolution 发送;与 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": "A clean product photo of a ceramic coffee cup on a walnut desk",
    "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": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

获取图片

图片可能直接返回,也可能先返回任务:

  • 直接完成时,data[] 中会有 url 或 b64_json。
  • 异步生成会返回 id、task_id、status,通常还有 poll_url。模型支持公开异步执行时,发送 "async": true 即可先拿到任务,不必等图片完成。
  • 查询异步任务时,用返回的 id 或 task_id 调用 GET /v1/tasks/{id}。
  • 需要 b64_json 时请使用同步请求,异步图片结果通过 URL 提供。

图片结果 URL 是 TokenLab 媒体结果 URL,有效期 30 天。media_retention.items 提供每项的保存状态和 expires_at;如果未能及时确定保存状态,响应可能省略 media_retention,URL 仍可使用。内联 Base64 结果不在此 URL 副本保留范围内。手动将图片保存到媒体库后,其生命周期独立计算。参见数据保留。

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

保存返回的图片 URL、任务 ID、模型,以及你自己的用户或任务 ID。任务进入终态后不要继续轮询。

上线前检查

  • 检查提示词长度、图片数量、URL 是否可访问,以及文件类型。
  • 高分辨率同步请求需要更长超时;模型支持时,耗时任务可以使用 async: true。
  • 保存 request_id、task_id、poll_url、模型、API 地址和请求字段名。
  • 图片请求返回任务时,Idempotency-Key 可以让创建请求安全重试:客户端超时后,用同一个键原样重发,就能拿到那个任务。直接返回图片的请求没有这个保证:用同一个键重试可能返回任务状态而不是图片,或者返回 409 和 idempotent_response_not_replayable。没有带键时,确认没有创建任务再重新提交。
  • 最终费用以 Usage 和 billing_transaction_id 为准。

常见错误

症状可能原因修复
400 和 param: "model"缺少显式模型查询 /v1/models?recommended_for=image 并发送 model
不支持的字段所选模型没有这个字段删除字段,或换成明确支持它的模型和 API
异步结果中没有 b64_json异步图片通过 URL 返回需要 base64 时使用同步模式
参考图被拒绝API 不对,或 URL 无法访问/已经过期按模型文档填写参考图,并使用可访问的 URL

API 参考

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

本页内容