概述
对于 coding agent,请先通过GET /v1/models?recommended_for=image 找出当前推荐的图片模型清单,然后将选定的 model 明确传给这个端点。
gpt-image-2 是按 token 计费的 GPT Image 模型。TokenLab 按 OpenAI 官方 usage 明细结算文本输入、图片输入、已上报的缓存输入以及图片输出 token;它不是固定每张图片计费的模型。
对于 gpt-image-2 图像生成,公共参数支持 prompt、n、size、quality、response_format、async、background、output_format、output_compression 或 compression、moderation 和 user。不传 size 或 quality 时 TokenLab 会使用 auto;自定义 size 必须使用下方说明的弹性 WIDTHxHEIGHT 契约。
input_fidelity 不属于当前 TokenLab 对 gpt-image-2 的支持字段;请省略该字段,否则请求会返回 400 unsupported_parameter。
模型行为说明
Google Gemini 图片模型并不共用同一套参数选择规则:gemini-3.1-flash-image、gemini-3-pro-image和nano-banana-pro在公开的文生图、图片编辑/图生图操作中支持aspect_ratio和resolution(1k、2k、4k)。nano-banana-2在当前 TokenLab 契约中仅文生图支持aspect_ratio和resolution(1k、2k、4k)。gemini-2.5-flash-image、nano-banana和nano-banana-edit支持aspect_ratio,但不提供公开的resolution选择。- Nano Banana 参考图请求请在本端点(
/v1/images/generations)使用nano-banana-edit或nano-banana-pro,并发送operation: "image-to-image"与image_urls。不要把 Nano Banana 参考图请求发送到/v1/images/edits。 - Nano Banana 图生图请求中,
nano-banana-pro可以发送resolution(1k、2k、4k);nano-banana-edit必须省略该参数。nano-banana和nano-banana-2在当前模型说明中是文生图模型。 - 本端点的参考图可以通过 JSON
image_url/image_urls传入,也可以通过 multipartimage文件直接上传。/v1/images/generations不接受images[]或file_id;只有明确支持images[].file_id的/v1/images/edits模型才使用/v1/files返回的引用。
aspect_ratio;只有模型明确支持时才发送 resolution。
xAI Grok Imagine 图片模型(grok-imagine-image、grok-imagine-image-quality 以及 legacy grok-imagine-image-pro)支持 aspect_ratio 和 resolution(1k、2k)。grok-imagine-image-pro 会作为 grok-imagine-image-quality 的兼容 ID 保留。
请求体
同步请求超时: 某些图片请求会以内联方式返回最终图片,并等待生成完成。高分辨率或高质量请求可能接近一分钟甚至更久,因此请将 HTTP 客户端超时设置为至少120s。如果创建响应包含 status: "pending"、task_id 或 poll_url,请改为跟随返回的 poll_url 轮询。
要使用的模型(例如
gpt-image-2、flux-pro、qwen-image-plus 或 nano-banana-pro)。使用 GET /v1/models?recommended_for=image 获取当前推荐列表。所需图片的文本描述。
用于图生图的公开 HTTPS 参考图 URL。Nano Banana 参考图请求请设置
operation 为 image-to-image;nano-banana-pro 可以发送 resolution,nano-banana-edit 应省略该参数。公开 HTTPS 参考图 URL 数组。JSON 请求中需要一张或多张参考图时使用此字段。本端点不支持
file_id 和 images[]。额外的模型特定参考图 URL,用于区分主输入图和参考图的供应商。
用于图生图的 multipart 参考图文件。源图是私有或需要请求头鉴权时使用直接上传。它不同于 /v1/files 的
file_id,本端点不接受 file_id。要生成的图片数量(1-10,取决于模型)。
图片尺寸。用于 OpenAI 风格的图片家族,以及接受精确像素尺寸的其他模型。对于
gpt-image-2,size 接受 auto 或 WIDTHxHEIGHT。自定义宽高必须都是 16 的倍数,最长边不超过 3840px,长边/短边比例不超过 3:1,总像素必须在 655,360 到 8,294,400 之间。aspect_ratio 和 resolution 目前不属于 TokenLab 对 gpt-image-2 的公共契约。对于 Google Gemini 图片家族,size 会被视为兼容别名,映射到模型公开的 aspect_ratio 契约,以及在支持时的 resolution 契约。建议对这些模型直接发送 aspect_ratio。依模型而定的宽高比选择器。Google 图片家族常见值包括
1:1、16:9、9:16、3:2、2:3。依模型而定的输出分辨率选择器。
gemini-3.1-flash-image 和 gemini-3-pro-image 在文生图与图片编辑中支持该参数;nano-banana-pro 在文生图与图生图中支持;nano-banana-2 仅文生图支持。常见值为 1k、2k、4k。除非模型明确说明,否则不要发送给仅支持比例选择的 Gemini 图片家族。xAI Grok Imagine 图片模型请使用 1k 或 2k。图片质量。
gpt-image-2 等 GPT Image 模型使用 auto、low、medium 或 high。其他图片系列可能使用提供者特定取值;发送非默认值前请先查看所选模型的元数据。响应格式:
url 或 b64_json,默认 url。对于 Azure Official 或 Azure-compatible 的 gpt-image-2 请求,TokenLab 会以 b64_json 接收图片数据。请求 url 时,TokenLab 会把每张图上传到 CDN 并返回 data[].url。如果 CDN 存储不可用或上传失败,请求会失败,而不是改为 Base64 响应;请求 b64_json 时直接返回原始 Base64。对
gpt-image-2 或官方 FLUX/BFL 图片模型设置为 true 时,会先创建任务。完成后的异步图片任务无论请求的 response_format 是什么,都只返回 URL;如果需要 b64_json,请使用同步请求。可选风格选择器。只有所选模型明确文档化支持时才发送;除非模型元数据另有说明,否则不要给
gpt-image-2 发送该字段。终端用户的唯一标识符。
响应
内联响应
创建时的 Unix 时间戳。
生成的图像数组。每个对象包含:
url(string):生成的图像 URLb64_json(string):Base64 编码的图像(如果请求)revised_prompt(string): 所选模型返回的可选提示词改写结果
异步任务响应
对gpt-image-2 或官方 FLUX/BFL 图片模型设置 async: true 后,创建请求会先返回任务,而不是等待最终图片生成完成。响应包含 status: "pending"、task_id 和 poll_url。请轮询 /v1/tasks/{task_id},直到任务进入 completed 或 failed。
异步图片任务最终只返回图片 URL。如果你需要原始 b64_json 图片数据,请使用同步请求。
任务创建时可能会先预留预计费用。任务完成后按实际用量结算;失败或超时的任务会释放预留费用或退回费用。
创建时的 Unix 时间戳。
用于轮询的唯一任务 ID。
初始状态:
pending。用于轮询结果的相对 URL,例如
/v1/tasks/{id}。任务处于 pending 状态时为空。图片任务完成后,生成图片的 URL 会出现在
data[].url 中。status: "pending" 后,请使用 poll_url 或 GET /v1/tasks/{task_id} 获取结果。
可用模型
下面是当前常见模型示例,不是固定目录。最新可用性和价格请查询GET /v1/models?recommended_for=image 或模型页面。
| 模型 | 类型 | 特性 |
|---|---|---|
gpt-image-2 | 内联或任务式 | 按 token 计费的 GPT Image 模型,支持灵活尺寸 |
flux-pro | 通常是任务式 | 写实、高质量 |
qwen-image-plus | 通常是任务式 | 文本渲染和提示词遵循较强 |
nano-banana-pro | 通常是任务式 | 参考图工作流和高分辨率输出 |
grok-imagine-image | 通常是任务式 | xAI 图片生成,支持比例和分辨率选择 |
ideogram-v3 | 通常是任务式 | 文本渲染较强 |
status: "pending",请跟随 poll_url 轮询直到完成。
处理任务式响应
对于图片模型,请始终检查响应是否包含status: "pending":