图像
编辑图片
根据提示词和源图片生成编辑结果
概述
根据原图和提示词修改或扩展图片。
此端点同时支持：
- OpenAI 兼容的
multipart/form-data文件上传 - 为支持的图像到图像模型提供
image_url、image_urls或官方images引用的 JSON 请求
gpt-image-2 支持 multipart image、JSON image_url / image_urls 和 images[]（其中可用 image_url 或 file_id），最多 16 张源图。file_id 需要先通过 /v1/files 创建。设置 async: true 时先返回任务。
gpt-image-2 编辑不接受 resolution，输出尺寸使用 size。background 可以是 auto 或 opaque，暂不支持 transparent。多图或耗时较长时可以设置 async: true，再通过返回地址查询。
Nano Banana 参考图请求（nano-banana-edit、nano-banana-2 和 nano-banana-pro）公开在 /v1/images/generations，应使用 operation: "image-to-image" 和 image_urls，不要发送到本 /v1/images/edits 端点。
xAI Grok Imagine 图像编辑模型（grok-imagine-image、grok-imagine-image-quality 以及 legacy grok-imagine-image-pro）最多接受 3 张源图。超过 3 张的请求会在输入校验阶段返回 400 too_many_images。
input_fidelity 不属于当前 TokenLab 对 gpt-image-2 的支持字段；请省略该字段，否则请求会返回 400 unsupported_parameter。
请求体
请求超时： 同步图片编辑可能需要较长时间，建议把 HTTP 超时设为至少 120s。响应包含 pending、task_id 或 poll_url 时，通过 poll_url 查询结果。
远程图片必须使用公网 http / https URL，不能包含用户名密码或 fragment，也不能指向 localhost、内网或保留 IP。图片必须是 PNG、JPEG 或 WebP。单张不超过 50 MiB，单次请求中的远程图片合计不超过 200 MiB；读取超时为 30s，最多跟随 3 次重定向。
JSON 请求必须且只能选择 image_url、image_urls、images 中的一项。每个 images[] 对象必须且只能包含 image_url 或 file_id 中的一项。200 MiB 总量限制包括所有源图片和遮罩。
multipart 源图片。需要多张 GPT Image 源图时，可以重复发送 image 字段。文件必须是 PNG、JPEG 或 WebP，最多 16 张源图，每张不超过 50 MiB。xAI Grok Imagine 编辑模型使用相同输入字段，但源图最多 3 张。
描述所需编辑的文本。
一个附加图像，其完全透明的区域指示应编辑图像的位置。必须是有效的 PNG 文件，小于 50 MiB，且与 image 具有相同的尺寸。
对于 JSON 请求，mask 也可以是一个对象，并且只能包含 image_url 或 file_id 其中之一；file_id 必须来自 /v1/files，并且绑定到同一套图像编辑配置。
用于图片编辑的模型。GPT Image 编辑请使用 gpt-image-2，也可以使用 GET /v1/models?recommended_for=image 返回的其他当前图片编辑模型。
1要生成的图片数量（1-10，取决于模型）。
生成图片的尺寸。对于 gpt-image-2，使用 auto 或 WIDTHxHEIGHT；宽高必须是 16 的倍数，最长边不超过 3840px，长边/短边比例不超过 3:1，总像素在 655,360 到 8,294,400 之间。
url返回生成图像的格式。必须是 url 或 b64_json，默认 url。
url 通过 data[].url 返回图片地址；b64_json 通过 data[].b64_json 返回 Base64 图片数据。
false对 gpt-image-2 或官方 FLUX/BFL 编辑模型设置为 true 时，会在最终图片完成前先返回任务。完成后的异步编辑无论请求的 response_format 是什么，都只返回 URL；如果需要 b64_json，请使用同步请求。
代表终端用户的唯一标识符，用于滥用监控。
响应
图像创建时间的 Unix 时间戳。
生成的图像数组。
每个对象包含：
url(string): 编辑后图像的 URL（如果 response_format 是url）b64_json(string): Base64 编码的图像（如果 response_format 是b64_json）
异步任务
支持异步编辑的模型设置 async: true 后，会先返回 pending、task_id 和 poll_url。通过 poll_url 查询，直到状态变为 completed 或 failed。
异步编辑任务最终只返回图片 URL。如果你需要原始 b64_json 图片数据，请使用同步请求。
任务创建时可能会先预留预计费用。任务完成后按实际用量结算；失败或超时的任务会释放预留费用或退回费用。
请求
curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=gpt-image-2" \
-F "image=@sunlit_lounge.png" \
-F "mask=@mask.png" \
-F "prompt=阳光明媚的室内休息区，带有游泳池" \
-F "n=1" \
-F "size=1024x1024"响应
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}注意事项
远程图片拉取失败会在生成开始前作为输入错误返回。URL 不可访问、超时、403/404、私有或内网主机、URL 中包含用户名密码或 fragment、非图片内容、不支持的格式、超过大小限制，都会返回 400 或 413，并指向 image_url / image_urls[n] 输入。私有或需要请求头鉴权的素材，请直接用 multipart image 上传，或创建 /v1/files 引用。
Hy Image 3.5 Preview 可根据文本生成 1024 像素方形图像，并按文字指令编辑参考图，适用于视觉草稿与构图调整。
{
"model": "hy-image-v3.5-preview",
"prompt": "Change the table to pale blue",
"image_url": "https://example.com/reference.png",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}授权
BearerAuth API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
请求头
单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified，并在输出、请求接受或持久资源创建之前，可能会切换一次至仅限 Official。
可选值
- "auto"
- "verified"
- "official"
响应
application/json
application/json
application/json
application/json
application/json
application/json