TokenLab
获取 API 密钥
文档API 参考集成

图像

编辑图片

根据提示词和源图片生成编辑结果

POST
/v1/images/edits

概述

根据原图和提示词修改或扩展图片。

此端点同时支持：

  • 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 时先返回任务；官方 FLUX/BFL 编辑模型也使用相同的任务轮询流程。

gpt-image-2 编辑不接受 resolution，输出尺寸使用 size。background 可以是 auto 或 opaque，暂不支持 transparent。多图或耗时较长的编辑建议使用 async: true，并轮询返回的任务。

Nano Banana 参考图请求（nano-banana-2、nano-banana-2.1、nano-banana-2-lite 和 nano-banana-pro）公开在 /v1/images/generations，应使用 operation: "image-to-image" 和 image_urls，不要发送到本 /v1/images/edits 端点。nano-banana-2、nano-banana-2.1、nano-banana-2-lite 和 nano-banana-pro 的图片编辑请求同样使用 /v1/images/generations，并发送 operation: "image-edit"。

gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3.1-flash-lite-image 和 gemini-3-pro-image 的图片编辑使用本端点；它们的图生图请求使用 /v1/images/generations，并发送 operation: "image-to-image"。

xAI Grok Imagine 图像编辑模型的源图数量有上限：grok-imagine-image-2.0 最多 5 张，grok-imagine-image 和 legacy grok-imagine-image-pro 最多 3 张。超过模型上限的请求会在输入校验阶段返回 400 too_many_images。

input_fidelity 不属于当前 TokenLab 对 gpt-image-2 的支持字段；请省略该字段，否则请求会返回 400 unsupported_parameter。

请求体

同步请求超时： 部分图片请求会内联返回最终图片，并等待生成完成。高分辨率或高质量请求可能需要接近一分钟甚至更久，请把 HTTP 客户端超时设为至少 120s。如果创建响应包含 status: "pending"、task_id 或 poll_url，请改为跟随返回的 poll_url。

远程图片 URL：需要 multipart 输入时，TokenLab 会拉取 JSON 中的 image_url、image_urls 或 images[].image_url，并把字节作为 multipart image 部分发送。URL 必须是公网 http/https，不能包含用户名密码或 fragment，也不能解析到 localhost、内网或保留 IP 段；每次重定向都会重新检查。拉取到的内容必须是真实的 PNG、JPEG 或 WebP 图片。限制为单张 50 MiB，单次请求中通过 URL 拉取的图片合计 200 MiB，拉取超时 30s，最多 3 次重定向。

JSON 请求必须且只能选择 image_url、image_urls、images 中的一项。每个 images[] 对象必须且只能包含 image_url 或 file_id 中的一项。200 MiB 总量限制包括所有源图片和遮罩。

imagefile

multipart 源图片。需要多张 GPT Image 源图时，可以重复发送 image 字段。文件必须是 PNG、JPEG 或 WebP，最多 16 张源图，每张不超过 50 MiB。xAI Grok Imagine 编辑模型使用相同输入字段，但源图数量有上限：grok-imagine-image-2.0 最多 5 张，其他 xAI 编辑模型最多 3 张。

promptstring必填

描述所需编辑的文本。

maskfile | object

一个附加图像，其完全透明的区域指示应编辑图像的位置。必须是有效的 PNG 文件，小于 50 MiB，且与 image 具有相同的尺寸。

对于 JSON 请求，mask 也可以是一个对象，并且只能包含 image_url 或 file_id 其中之一；file_id 必须来自 /v1/files，并且绑定到同一套图像编辑配置。

modelstring必填

用于图片编辑的模型。GPT Image 编辑请使用 gpt-image-2，也可以使用 GET /v1/models?recommended_for=image 返回的其他当前图片编辑模型。

ninteger默认值: 1

要生成的图片数量（1-10，取决于模型）。

sizestring

生成图片的尺寸。对于 gpt-image-2，使用 auto 或 WIDTHxHEIGHT；宽高必须是 16 的倍数，最长边不超过 3840px，长边/短边比例不超过 3:1，总像素在 655,360 到 8,294,400 之间。

对于 gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3-pro-image 和 gemini-3.1-flash-lite-image，size 接受该模型尺寸表中的输出尺寸，或分辨率档位 1K、2K、4K。TokenLab 会把档位作为 resolution 发送。模型不支持的档位，或与 resolution 不一致的档位，会返回 400，错误码为 invalid_image_size_contract。推荐使用 aspect_ratio 加 resolution。

response_formatstring

图片的返回方式：url 或 b64_json。

  • 不传：如果模型返回图片字节，每张图片在 data[].b64_json 中返回；TokenLab 保存成功时也在 data[].url 中返回。如果模型返回链接，每张图片在 data[].url 中返回。
  • url：每张图片只在 data[].url 中返回。
  • b64_json：每张图片只在 data[].b64_json 中以 Base64 数据返回。

链接是 TokenLab 媒体结果 URL，有效期 30 天。参见数据保留。

asyncboolean默认值: false

对 gpt-image-2 或官方 FLUX/BFL 编辑模型设置为 true 时，会在最终图片完成前先返回任务。完成后的异步编辑无论请求的 response_format 是什么，都只返回 URL；如果需要 b64_json，请使用同步请求。

userstring

代表终端用户的唯一标识符，用于滥用监控。

响应

createdinteger

图像创建时间的 Unix 时间戳。

dataarray

生成的图像数组。

每个对象包含：

  • url (string)：编辑后图片的 TokenLab 媒体结果 URL，有效期 30 天。response_format 为 b64_json 时不返回。不传 response_format 时，如果 TokenLab 未能保存图片，则不返回。
  • b64_json (string)：Base64 图片数据。response_format 为 b64_json 时返回；不传 response_format 且模型返回图片字节时也返回。

异步任务响应

对 gpt-image-2 或官方 FLUX/BFL 编辑模型设置 async: true，会创建任务，而不是在请求中等待编辑后的图片。响应包含 status: "pending"、task_id 和 poll_url。轮询 /v1/tasks/{task_id}，直到任务变为 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=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

响应

Response
{
  "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
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified，并在输出、请求接受或持久资源创建之前，可能会切换一次至仅限 Official。

可选值

  • "auto"
  • "verified"
  • "official"

请求体

响应

application/json

application/json

application/json

application/json

application/json

application/json

生成图片

上一页

创建图像变体

下一页