TokenLab 上的 GPT Image 编辑 API：正确的端点与图像输入格式

图像编辑是 AI 产品界面中要求较高的部分之一：用户上传一张照片，描述修改要求，然后期待得到结果。涉及多张源图像、大画布或较复杂提示词的编辑，所需时间通常会超出典型同步 HTTP 调用所能轻松承受的范围。本指南将介绍正确的 TokenLab 端点、两种受支持的图像输入形式、多图编辑，以及针对慢速请求的异步路径。

端点

图像编辑端点位于 POST /v1/images/edits——请注意复数形式 edits。（常见错误是写成 /images/edit，这并不是文档所规定的路径。）

该端点支持两种请求格式：

• 兼容 OpenAI 的 multipart/form-data 上传流程。
• 提供 image_url、image_urls 或针对受支持图生图（image-to-image）系列的官方 images[] 引用的 JSON 请求。

完整的请求与响应字段记录在编辑图像 API 参考中。

gpt-image-2 在此支持的内容

• Multipart image 上传。
• JSON 格式的 image_url 或 image_urls。
• 官方 images[] 引用，其中每个对象必须恰好包含 image_url 或 file_id 中的一个。
• 每次请求最多支持 16 张源图像。

编写代码前值得了解的几项约束条件：

• gpt-image-2 编辑不接受 resolution；请使用 size 指定输出尺寸（可为 auto 或 WIDTHxHEIGHT，尺寸须为 16 的倍数，长边最大为 3840px，长宽比最大为 3:1）。
• background 接受 auto 或 opaque；不支持 transparent。
• input_fidelity 不在 gpt-image-2 支持的字段中；传入该参数将返回 400 unsupported_parameter。
• 对于 JSON 请求，请恰好提供 image_url、image_urls 或 images 中的一个。每个 images[] 对象必须恰好包含 image_url 或 file_id 中的一个。file_id 的值必须先通过 /v1/files 创建。
• Nano Banana 参考图像请求应发送至 /v1/images/generations，并携带 operation: "image-to-image" 和 image_urls——而不是发送至 /v1/images/edits。

Multipart 上传与 JSON 图像引用对比

两者均适用于 gpt-image-2。根据图像字节数据当前所在的位置进行选择即可。

Multipart——当应用程序本身持有文件时使用此方式（无论是来自用户上传还是先前生成的资源）。重复使用 image 字段可发送多个源图像。文件格式必须为 PNG、JPEG 或 WebP，每个文件最大为 50 MiB。

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

JSON 图像 URL——当图像已托管在公开 URL 上，或者是在早先的 TokenLab 请求中生成并已拥有 URL 时使用此方式。

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

远程 URL 必须是公开的 http/https，不得内嵌凭据或片段标识符（fragments），且解析结果不得为 localhost、私有或保留 IP 地址段。TokenLab 会拉取对应字节，并作为 multipart image 数据传递给模型。单张图像限制为 50 MiB；单个请求中通过 URL 获取的图像总大小限制为 200 MiB；获取超时时间为 30 秒；最多跟随 3 次重定向。

多图编辑与异步轮询

多图编辑是使用 async: true 最典型的场景。通过同步调用发送多张图像以及复杂的指令集，意味着无论模型需要多久，连接都必须一直保持打开状态。在 gpt-image-2（以及官方 FLUX/BFL 编辑模型）上设置 async: true 即可改为接收一个任务：

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

对返回的 poll_url 进行轮询，或退回使用 GET /v1/tasks/{task_id}。任务状态包括 pending、processing、completed 和 failed。已完成的图像任务会返回 data[].url。每 3–5 秒检查一次即可；当状态变为终态时应停止，而不是继续轮询。

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

无论请求的 response_format 为何，异步编辑任务均返回最终的图像 URL。如果您需要原始的 b64_json，请使用同步请求。

计费系统可能会在创建任务时预扣预估金额；任务完成后按实际用量结算，若任务失败或超时则释放预扣额或进行退款。有关完整生命周期请参阅异步任务与轮询，响应字段请参阅获取图像状态。

何时使用各模式

在以下情况下使用 async: true：

• 在一个请求中发送多张源图像。
• 提示词或指令集较为复杂，生成时间无法预估。
• 在后台作业、队列或批处理进程中运行编辑任务，而非面向用户的实时请求。

在以下情况下保持同步：

• 执行带简短提示词的单图编辑。
• 客户端倾向于快速失败而非轮询。

对于同步调用，请将 HTTP 客户端超时时间设置为至少 120s；高分辨率或高画质请求可能需要近一分钟甚至更久。如果创建响应仍然返回 status: "pending"、task_id 或 poll_url，请切换至返回的轮询流程。

常见的输入错误

远程图像获取失败会在生成开始前作为输入错误返回。无法访问的 URL、超时、403/404 响应、私有或内部主机、URL 中包含凭据或片段、非图像内容、不支持的格式以及超出大小限制等，都会返回 400 或 413，并指出有问题的 image_url 或 image_urls[n]。对于私有或受 Header 保护的资源，请直接通过 multipart 上传 image 文件，或创建 /v1/files 引用并作为 images[].file_id 传入。

xAI Grok Imagine 图像编辑模型（例如 grok-imagine-image 和 grok-imagine-image-quality）使用相同的输入字段，但源图像数量上限为 3 张；超出该限制将返回 400 too_many_images。

集成检查清单

• 请求目标为 POST /v1/images/edits，并显式传递 model。
• 根据图像当前所在位置，选择 multipart 上传或 JSON 引用。
• 在 JSON 请求中恰好传递 image_url、image_urls 或 images[] 中的一个；每个 images[] 条目必须恰好包含 image_url 或 file_id 中的一个。
• 对于多图或重度编辑，使用 async: true；轮询返回的 poll_url 直至任务达到 completed 或 failed。
• 对于同步请求，将客户端超时时间设置为至少 120 秒，并根据 poll_url 处理 pending 响应。
• 客户端发生超时时，在重试创建请求前先检查是否已生成任务，以避免重复扣费。

开始使用

查询 GET /v1/models?recommended_for=image 以查看当前的图像模型，然后在发送请求前打开模型的详情页面以确认其支持的操作和请求字段。从控制台创建 API 密钥，即可使用您自己的图像测试编辑端点。