AI 图像编辑 API 选择指南：端点、输入与成本单位

最好的 AI 图像编辑 API 往往不是演示效果最好的那一个，而是其端点、输入形状和计费单位与您产品实际执行的编辑需求相匹配的那一个。蒙版编辑（Mask edits）、参考引导的图像到图像（reference-guided image-to-image）以及特定模型的编辑操作并不共享同一个契约。我们在 2026 年 10 月 3 日查阅了 TokenLab 的编辑文档和实时模型页面，以下所有内容均来自这些页面。图像端点不会为您选择默认模型，因此请务必显式发送 model 参数。

关键要点

• 基于蒙版的编辑请使用 POST /v1/images/edits。Nano Banana 的参考编辑请使用 POST /v1/images/generations 并设置 operation: "image-to-image"。
• 计费单位各不相同。gpt-image-2 和 Gemini 图像模型按 token 计费，而 flux-kontext-pro 按请求计费，价格为 0.04 美元。
• 现有证据中不包含关于修复质量（inpainting quality）、文本渲染、风格保留或产品拍摄保真度的基准测试。请务必在您自己的图像上进行测试。
• 对于长任务或多图像编辑，如果模型支持，应使用 async: true。存储任务 ID 并从 Usage 中查看最终扣费。
• 在提交请求前，请检查每个模型页面的价格和单位，因为实时 API 会发生变化。

按用例推荐的起步模型

这些推荐遵循了文档化的契约和列出的价格。它们并非质量排名，因为证据中缺乏编辑质量的基准测试。请将它们视为放入您测试集中的首选模型。

您的需求	起步推荐	原因	来源
基于蒙版的修复 (Inpainting)	gpt-image-2	这是唯一明确说明蒙版契约的模型：PNG 格式、相同尺寸、透明区域即为编辑区域。	Edit Image 参考文档, 2026-10-03
单次编辑包含多个源图像	gpt-image-2	文档记录上限为 16 张源图像。Grok Imagine 编辑模型的上限为 3 张。	Edit Image 参考文档, 2026-10-03
最便宜的固定价格参考编辑	grok-imagine-image	每次请求 0.02 美元，是我们表中最低的固定价格。	实时模型 API, 2026-10-03
保持产品形状，更换场景	nano-banana-pro	文档中的参考示例正是执行此操作，价格为每张图像 0.067 美元。	Create Image 参考文档, 2026-10-03
编辑后的图像内包含文本	无推荐	证据中没有任何编辑模型的文本渲染数据。	n/a

最佳 AI 图像编辑 API 候选者：模型、单位与价格

下表列出了我们证据集中所有被列为具备编辑能力，或在编辑文档中被命名为编辑模型的模型。所有价格均为 TokenLab 美元公开价格。实时 API 报告的定价更新于 2026-10-02T16:53:30.068Z，我们在 2026-10-03 观察了每个页面。

模型 ID	实时 API 列出的能力	计费单位	TokenLab 价格 (USD)	来源	观察日期
gpt-image-2	文本转图像（文档记录在 /v1/images/edits 中可进行编辑）	per_token	$3.50/1M 文本输入, $5.60/1M 图像输入, $21/1M 图像输出; 缓存文本输入 $0.875/1M	实时模型 API	2026-10-03
flux-kontext-pro	图像编辑, 图像转图像, 文本转图像	per_request	$0.04	实时模型 API	2026-10-03
flux-pro-1.0-fill	图像转图像	per_image	$0.035	实时模型 API	2026-10-03
flux-2-pro	图像转图像, 文本转图像	per_image	$0.03	实时模型 API	2026-10-03
nano-banana-pro	图像编辑, 图像转图像, 文本转图像	per_image	$0.067 (价格区间汇总最高至 $0.12)	实时模型 API	2026-10-03
gemini-3-pro-image	图像转图像, 文本转图像, 视觉	per_token	$1/1M 输入, $6/1M 文本输出, $60/1M 图像输出	实时模型 API	2026-10-03
gemini-3.1-flash-image	图像转图像, 文本转图像, 视觉	per_token	$0.25/1M 输入, $1.50/1M 文本输出, $30/1M 图像输出	实时模型 API	2026-10-03
grok-imagine-image	图像转图像, 文本转图像	per_request	$0.02	实时模型 API	2026-10-03

在比对页面时，我们发现了三处不一致。实时 API 将 gpt-image-2 列为仅支持文本转图像，但 Edit Image 参考文档称其在 /v1/images/edits 上受支持。flux-pro-1.0-fill 和 flux-2-pro 的实时页面列出了图像转图像，而我们的目录快照将两者都标记为图像编辑。nano-banana-pro 列出了图像编辑能力，但其文档将其路由至 /v1/images/generations。我们视文档为路由的权威，视实时 API 为定价的权威。

对于固定价格模型，粗略估算只需简单乘法。这些是估算值而非报价，且假设每个完成的请求收取一次费用：

• 在 grok-imagine-image 上进行 100 次编辑：100 × $0.02 = $2.00。
• 在 flux-2-pro 上进行 100 次编辑：100 × $0.03 = $3.00。
• 在 flux-pro-1.0-fill 上进行 100 次编辑：100 × $0.035 = $3.50。
• 在 flux-kontext-pro 上进行 100 次编辑：100 × $0.04 = $4.00。

证据中没有提供按 token 计费模型的单次编辑估算。gpt-image-2 对文本输入、图像输入、已报告的缓存输入和图像输出 token 进行计费，因此它不是固定的单图像计费模型。证据中不包含典型编辑的 token 计数。请运行几次实际编辑并在 Usage 中查看费用，如 Billing 指南所述。nano-banana-pro 的价格区间暗示了分辨率层级，但证据中并未将层级与价格对应。

编辑端点接受的内容及未记录的内容

Edit Image 参考文档（2026-10-03 观察）支持 OpenAI 兼容的多部分（multipart）流和 JSON 请求。以下是其针对 gpt-image-2 的说明：

• 输入图像。 发送 multipart image、JSON image_url / image_urls，或官方的 images[] 对象。每个 images[] 对象必须包含 image_url 或 file_id 中的一个。请先通过 /v1/files 创建 file_id 值。
• 多个参考。 最多 16 张源图像，每张均为 PNG、JPEG 或 WebP 格式，最大 50 MiB。在 multipart 请求中重复 image 字段。在 JSON 中，提供 image_url、image_urls 或 images 中的一个。
• 蒙版。 一个小于 50 MiB 的 PNG，尺寸与源图像相同。完全透明的区域标记编辑应用的位置。在 JSON 中，mask 可以是一个对象，包含 image_url 或 file_id 中的一个。
• 输出。 size 接受 auto 或 WIDTHxHEIGHT。尺寸必须是 16 的倍数，最长边不超过 3840px，长宽比不超过 3:1，总像素在 655,360 到 8,294,400 之间。不要发送 resolution。background 接受 auto 或 opaque，不支持 transparent。
• 拒绝字段。 input_fidelity 不受 gpt-image-2 支持，发送该字段会返回 400 unsupported_parameter。
• 远程 URL。 必须是公开的 http/https，且不含嵌入的凭据或片段。不得解析为 localhost、私有或保留地址段。限制为每张图像 50 MiB，每个请求总计 200 MiB（含蒙版），30 秒获取超时，最多 3 次重定向。获取的负载必须是真实的 PNG、JPEG 或 WebP。

Grok Imagine 编辑模型（grok-imagine-image, grok-imagine-image-quality）使用相同的输入字段，但源图像上限为 3 张。超过此限制的请求会失败并返回 400 too_many_images。

Nano Banana 则不同。文档称 nano-banana-2 和 nano-banana-pro 在 /v1/images/generations 上接收参考图像请求，并使用 operation: "image-to-image" 和 image_urls。它们不属于 /v1/images/edits。顶层的 images[] 和 file_id 是编辑流的形状，在生成端点会被拒绝。以下是 nano-banana-pro 的文档示例，它接受 resolution：

{
  "model": "nano-banana-pro",
  "prompt": "Keep the product shape, change the background to a bright studio setup",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/input/product.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}

对于 Google 图像系列，Create Image 参考文档建议优先使用 aspect_ratio，仅在模型支持的情况下发送 resolution（1k, 2k, 4k）。nano-banana-2 的模型详情链接在此，但证据集中不包含其价格。

证据中未记录的内容：

• 除 gpt-image-2 外，是否有其他模型在 /v1/images/edits 上接受 mask，包括 flux-pro-1.0-fill 和 stability-inpaint。
• 当您发送多个源图像时，单个蒙版如何应用。
• FLUX 和 Nano Banana 模型的源图像限制。
• 多图像请求中的图像顺序是否影响结果。

在基于这些模型构建之前，请阅读模型的详情页面。

一个完整的编辑请求

此请求仅使用 gpt-image-2 的文档化字段：源图像、蒙版、提示词、size 和 async。它遵循了 Edit Image 参考文档中的 multipart 示例。

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@source.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "async=true"

使用 async=true 时，响应包含 status: "pending"、task_id 和 poll_url，且 data 为空。如需同步调用，请去掉 async 行。同步调用默认返回 data[].url，如果设置了 response_format 则返回 data[].b64_json。轮询任务如下：

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

gpt-image-2 的模型详情在其模型页面上。对于同步调用，请将 HTTP 客户端超时设置为至少 120 秒，因为高分辨率请求可能需要近一分钟或更长时间。

按任务选择最佳 AI 图像编辑 API

证据说明了路由、输入和价格。它不包含编辑质量的基准测试，因此下方的每一个“哪个更好”的问题都需要您自己的测试集。

修复 (Inpainting)。 gpt-image-2 是唯一在文档中明确了蒙版契约的模型。目录中还列出了专用的区域和结构工具：stability-inpaint、stability-control-structure 和 stability-control-sketch。对于填充和上下文编辑，有价格为每张图像 0.035 美元的 flux-pro-1.0-fill 和价格为每次请求 0.04 美元的 flux-kontext-pro。证据中未说明哪种模型产生的接缝更干净。

风格保留编辑。 文档中的参考示例保持了产品的形状并改变了周围环境。这是 /v1/images/generations 上 nano-banana-pro 的模式。flux-kontext-pro 列出了图像编辑能力。此处未对两者的身份或风格保留能力进行基准测试。

图像中的文本。 证据中没有任何编辑模型的文本渲染信息。ideogram-edit-v3 和 ideogram-reframe-v3 存在于目录中，但我们未找到文本质量数据。请使用您自己的文案、字体和语言进行测试。

产品拍摄。 想象一个目录团队需要更换数千张包装照片的背景。实用工具是自然的初步选择：image-background-remover、image-upscaler 和 stability-upscale-fast。它们的定价和输入规则不在我们的证据中，请阅读每个模型页面。对于生成式背景更换，固定的按请求定价使批量成本易于预测。Token 计费则使其取决于图像大小和输出。

输入要求是按模型而非按提供商划分的。有些模型接受一个源图像加一个提示词，有些接受蒙版，有些接受结构输入。请在每个模型的详情页面检查其支持的操作和请求字段。您可以在 模型目录 中浏览当前选项。

异步处理与编辑成本确认

图像生成指南和异步任务轮询指南（均于 2026-10-03 观察）描述了该流程。async: true 已记录在 gpt-image-2 和官方 FLUX/BFL 编辑模型中。创建响应返回 status: "pending"、task_id 和 poll_url。当存在时轮询 poll_url，或使用 GET /v1/tasks/{id} 获取固定 URL。状态包括 pending、processing、completed 和 failed。文档建议对于长媒体任务每 5–10 秒检查一次，并在达到终端状态时停止。

四个细节会导致大多数 Bug：

• 即使任务失败，状态读取也会返回 HTTP 200。请根据 status 以及 error_details.code 和 type 来判断失败情况。
• 无论 response_format 如何，已完成的异步编辑都会返回 URL。当您需要 b64_json 时，请使用同步请求。
• 在客户端超时后，请在重试创建调用之前检查任务是否存在。重试失败的生成会创建一个新任务，并可能产生新的费用。
• 结果 URL 可能会作为媒体副本保留 30 天。请检查每个项目的 media_retention.items 状态和 expires_at。

关于成本，Billing 指南称控制台会在您确认付费生成前显示最高估算值，而 Usage 会显示最终扣费。异步任务在被接受时可能会预留其估算成本。已完成的任务扣费一次，失败或超时的任务会释放或退还预留金额。交付选项也很重要。TokenLab Verified 使用 TokenLab 公开价格，Official 使用官方价格层级，Auto 优先尝试 Verified，然后是 Official。Models 页面价格列中的横杠表示没有 Verified 报价，并不代表模型免费。API 密钥上的消费限额一旦达到，将返回 402 Payment Required。

请将 request_id、task_id、poll_url、billing_transaction_id（存在时）、模型、端点和您自己的作业 ID 存储在一起。实际上，该记录可以解决大多数计费不匹配的问题。证据仅记录了 Seedance 视频任务的排队任务取消。图像编辑的取消未被记录，因此请在设计流程时不要依赖它。

常见问题解答

我可以向每个图像编辑模型发送蒙版吗？

证据仅记录了 gpt-image-2 在 /v1/images/edits 上支持蒙版。蒙版必须是小于 50 MiB 的 PNG，且尺寸与源图像相同，透明区域即为编辑区域。对于其他模型（包括 flux-pro-1.0-fill），在假设支持蒙版之前，请检查模型详情页面。

Nano Banana 编辑使用哪个端点？

请使用 POST /v1/images/generations 并设置 operation: "image-to-image" 和 image_urls。不支持将 Nano Banana 参考请求发送至 /v1/images/edits。也不要向生成端点发送顶层的 images[] 或 file_id。

为什么我的 gpt-image-2 编辑返回 400 unsupported_parameter？

最常见的原因是 input_fidelity，这不是 gpt-image-2 支持的字段。此外，请移除 resolution 和任何 background: "transparent" 值。常见错误表建议移除模型文档中未提及的任何字段。

异步编辑任务失败时会被扣费吗？

Billing 指南称失败的任务不会扣费，其预留金额会被释放或退还。已完成的任务扣费一次，最终金额会显示在 Usage 中并附带 billing_transaction_id。如果任务结束后 Usage 仍未显示任何内容，请携带请求 ID 和任务 ID 联系 support@tokenlab.sh。

要运行上述请求，请在控制台 → API Keys 下创建一个 API 密钥（密钥限制在 Billing 指南中有解释），将其导出为 TOKENLAB_API_KEY，并将您的示例编辑与 Usage 中的最终成本进行比较。