开发者文档

切换外观

编辑图片 ​

POST/images/edits
鉴权
Bearer API Key
执行方式
按所调用的完整地址执行
查看调用示例

接口说明 ​

使用当前实现的 Images Edits multipart/form-data 合同编辑一张或多张图片；Token Factory 只接受 multipart/form-data，OpenAI 官方另有 application/json images 引用请求体但本入口尚未实现；校验已列官方文本 part 后，原样转发图片、可选蒙版及全部 part，成功终态必须提供可信用量事实；平台 805 MiB 请求体门禁仅用于承载官方最多 16 张、逐图与蒙版大小限制。

请求 ​

  • 方法：POST

  • 鉴权：Authorization: Bearer ${TOKENFACTORY_API_KEY}

请求头 ​

名称必填值或类型说明
Authorization是Bearer ${TOKENFACTORY_API_KEY}Token Factory API Key
Content-Type是multipart/form-data客户端必须生成带 boundary 的 multipart 请求头，不要手写固定 boundary

路径参数：无

查询参数：无

请求字段 ​

字段类型必填说明示例或约束
backgroundstring否multipart 文本 part；允许为 null/省略。transparent 仅适用于支持透明背景的 GPT Image 模型，并须搭配 png 或 webp。可选值："transparent"、"opaque"、"auto"；可为 null
imagestring (binary)[]是至少一个图片 part；GPT Image 官方最多 16 张，多图通过重复 image 或 image[] part 发送；dall-e-2 仅允许一张；平台 Images Edit 请求体门禁为 805 MiB。示例：["@source-one.png","@source-two.webp"]；最少：1 项；最多：16 项
input_fidelitystring否multipart 文本 part；允许为 null/省略，仅适用于支持的 GPT Image 模型。可选值："high"、"low"；可为 null
maskstring (binary)否可选蒙版 PNG；OpenAI 官方要求小于 4 MB 且与首张 image 尺寸相同；同时计入平台 805 MiB 请求体门禁。示例："@mask.png"
modelstring否OpenAI 官方可选且允许为 null 的图片模型 ID；multipart/官方 SDK 中 null 的线上语义是省略该 part，省略时 Token Factory 默认使用 gpt-image-1.5；字面字符串 null 会被当作模型 ID 而不代表 null，请勿发送。若提供，必须是非空字符串；dall-e-3 不支持编辑。示例："YOUR_MODEL_ID"；可为 null
ninteger (int32)否multipart 整数文本 part；允许为 null/省略，取值范围 1 到 10。最小值：1；最大值：10；可为 null
output_compressioninteger (int32)否multipart 整数文本 part；允许为 null/省略，取值范围 0 到 100，仅用于 JPEG/WebP 输出。最小值：0；最大值：100；可为 null
output_formatstring否multipart 文本 part；允许为 null/省略。可选值："png"、"jpeg"、"webp"；可为 null
partial_imagesinteger (int32)否multipart 整数文本 part；允许为 null/省略，取值范围 0 到 3，仅在 stream=true 时使用。最小值：0；最大值：3；可为 null
promptstring是图片编辑提示词；OpenAI 官方对 dall-e-2 最长 1000 字符，GPT Image 模型最长 32000 字符。首尾空白与换行按原始字节保留；仅当内容全部为空白时返回 400 invalid_request_error。示例："保留主体并改成夜景"
qualitystring否multipart 文本 part；允许为 null/省略，合法值随模型而异。可选值："standard"、"low"、"medium"、"high"、"auto"；可为 null
response_formatstring否multipart 文本 part；允许为 null/省略，仅适用于 dall-e-2。可选值："url"、"b64_json"；可为 null
sizestring否multipart 文本 part；允许为 null/省略，合法值随模型而异；gpt-image-2 还支持满足约束的 WIDTHxHEIGHT。可为 null
streamboolean否multipart 布尔文本 part；省略或 SDK null 等同 false，线上只发送 true 或 false。示例：false；可为 null
userstring否用于 OpenAI 安全监测的终端用户标识；若提供必须是字符串。—

请求报文 ​

媒体类型：multipart/form-data

text
image: @source-one.png
image: @source-two.webp
mask: @mask.png
model: YOUR_MODEL_ID
prompt: 保留主体并改成夜景
stream: false

响应 ​

成功状态：200

响应头 ​

名称值或类型说明
Content-Typeapplication/json 或 text/event-stream响应媒体类型
retry-afterstring上游限流或暂时不可用时保留的重试等待秒数。
x-ratelimit-limit-input-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-output-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-requestsstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-input-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-output-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-requestsstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-input-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-output-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-requestsstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-request-idstring本次 OpenAI 协议请求的关联 ID；上游未提供时由 Token Factory 生成。

响应字段 ​

OpenAI Images 成功终态；官方新增字段保持开放。 下表完整列出当前公开协议明确声明的字段；开放扩展只允许未声明的附加字段，不会放宽已声明字段的必填、类型或枚举约束。

字段类型必填说明示例或约束
backgroundstring否实际输出背景模式。示例："opaque"；可选值："transparent"、"opaque"；可为 null
createdinteger (int64)是创建时间 Unix 秒。示例：1787832000
dataobject[]是真实输出图片数组；成功响应至少包含一张图片。示例：[{"b64_json":"...","revised_prompt":"一只在月光下读书的猫"}]；最少：1 项
data[].b64_jsonstring否Base64 编码的图片数据；允许为 null。示例："..."；可为 null
data[].revised_promptstring否模型修订后的提示词；允许为 null。示例："一只在月光下读书的猫"；可为 null
data[].urlstring否临时图片 URL；允许为 null。可为 null
output_formatstring否实际输出图片格式。示例："png"；可选值："png"、"webp"、"jpeg"；可为 null
qualitystring否实际输出质量。示例："high"；可选值："low"、"medium"、"high"；可为 null
sizestring否实际输出尺寸。示例："1024x1024"；可选值："1024x1024"、"1024x1536"、"1536x1024"、"auto"；可为 null
usageobject否TOKEN_USAGE 绑定时必需的可信生成用量；OUTPUT_IMAGE 绑定按 data 中真实图片数计费；两类事实均缺失时失败关闭。官方字段可省略或为 null。示例：{"input_tokens":14,"input_tokens_details":{"image_tokens":0,"text_tokens":14}...；可为 null
usage.input_tokensinteger (int32)父字段存在时必填输入 Token 数。示例：14；最小值：0
usage.input_tokens_detailsobject父字段存在时必填输入 Token 分类明细。示例：
usage.input_tokens_details.image_tokensinteger (int32)父字段存在时必填图片 Token 数。示例：0；最小值：0
usage.input_tokens_details.text_tokensinteger (int32)父字段存在时必填文本 Token 数。示例：14；最小值：0
usage.output_tokensinteger (int32)父字段存在时必填输出 Token 数。示例：32；最小值：0
usage.output_tokens_detailsobject否输出 Token 分类明细；官方可省略。示例：
usage.output_tokens_details.image_tokensinteger (int32)父字段存在时必填图片 Token 数。示例：32；最小值：0
usage.output_tokens_details.text_tokensinteger (int32)父字段存在时必填文本 Token 数。示例：0；最小值：0
usage.total_tokensinteger (int32)父字段存在时必填输入与输出 Token 总数。示例：46；最小值：0

返回报文 ​

媒体类型：application/json

json
{
  "background": "opaque",
  "created": 1787832000,
  "data": [
    {
      "b64_json": "...",
      "revised_prompt": "一只在月光下读书的猫"
    }
  ],
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 14,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 14
    },
    "output_tokens": 32,
    "output_tokens_details": {
      "image_tokens": 32,
      "text_tokens": 0
    },
    "total_tokens": 46
  }
}

SSE 返回报文 ​

媒体类型：text/event-stream

允许事件：image_edit.partial_image、image_edit.completed、error

协议终态：image_edit.completed、error

text
event: image_edit.partial_image
data: {"type":"image_edit.partial_image","b64_json":"...","created_at":1787832000,"size":"1024x1024","quality":"high","background":"opaque","output_format":"png","partial_image_index":0}

event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","created_at":1787832000,"size":"1024x1024","quality":"high","background":"opaque","output_format":"png","usage":{"input_tokens":26,"input_tokens_details":{"text_tokens":8,"image_tokens":18},"output_tokens":34,"total_tokens":60}}

只有上方列出的协议终态才表示流正常结束；连接中断不代表请求未执行。若已经收到部分内容，不要无条件重放同一请求。

错误 ​

适用完整地址状态错误码常见触发重试建议动作结果风险
https://api.tokenfactory.cn/v1/images/edits401invalid_api_keyAuthorization 缺失、Bearer 格式错误、Key 不可用或账户未实名否检查 Bearer API Key、Key 状态与实名状态无
https://api.tokenfactory.cn/v1/images/edits400model_not_found模型存在，但不具备当前端点要求的能力否改用支持当前端点能力的模型，或改为调用该模型支持的端点无
https://api.tokenfactory.cn/v1/images/edits404model_not_found模型不存在、未上架或当前入口不可用否调用模型列表并改用当前入口可用模型无
https://api.tokenfactory.cn/v1/images/edits404MODEL_ROUTING_PROTOCOL_UNSUPPORTED模型未开放当前 API 接口对应协议否改用该模型已开放的协议或其他模型无
https://api.tokenfactory.cn/v1/images/edits503MODEL_ROUTING_NOT_CONFIGURED模型的协议路由尚未配置视情况稍后重试；持续出现时联系平台确认路由配置无
https://api.tokenfactory.cn/v1/images/edits503MODEL_ROUTING_POLICY_INVALID模型协议路由策略状态异常视情况稍后重试；持续出现时联系平台检查路由策略无
https://api.tokenfactory.cn/v1/images/edits503MODEL_ROUTING_NO_HEALTHY_ROUTE模型当前没有健康供应路线是，退避后指数退避后重试或临时改用其他模型无
https://api.tokenfactory.cn/v1/images/edits429insufficient_balance账户可用余额不足否充值后重新发起请求无
https://api.tokenfactory.cn/v1/images/edits429balance_daily_limit_exceeded账户当天余额消费已达到自助上限否调整每日上限或等待次日恢复无
https://api.tokenfactory.cn/v1/images/edits413request_too_large请求体超过平台接收上限否缩小请求体后重试无
https://api.tokenfactory.cn/v1/images/edits400invalid_request_error请求参数或请求体缺字段、格式错误或不受支持否修正请求后重试无
https://api.tokenfactory.cn/v1/images/edits502upstream_error供应商连接失败或返回异常响应视情况确认未收到有效结果后再决定是否重试中到高
https://api.tokenfactory.cn/v1/images/edits504upstream_timeout供应商在平台超时时间内未完成响应视情况先确认是否已有部分输出，再决定是否重试中到高
https://api.tokenfactory.cn/v1/images/edits500internal_error平台内部出现未预期错误视情况确认未收到有效结果并记录请求时间后再决定是否重试中到高
https://api.tokenfactory.cn/v1/images/edits405method_not_allowed请求方法不是该公开地址允许的方法否改用文档列出的 HTTP 方法无
https://api.tokenfactory.cn/v1/images/edits415unsupported_media_typeContent-Type 与该公开地址要求的媒体类型不一致否按文档发送正确 Content-Type无
https://api.tokenfactory.cn/v1/images/edits403permission_denied当前 API Key 或上游账户无权执行该请求否检查权限、模型可见性与供应商授权无
https://api.tokenfactory.cn/v1/images/edits409conflict_error请求与上游资源当前状态冲突视情况读取最新状态后修正请求或稍后重试中到高
https://api.tokenfactory.cn/v1/images/edits422unprocessable_entity请求结构正确但上游无法处理其中的语义否按错误信息修正参数或输入内容无

错误返回报文 ​

适用完整地址 ​

https://api.tokenfactory.cn/v1/images/edits

HTTP 400；Content-Type: application/json；响应头：retry-after: string、x-ratelimit-limit-input-tokens: string、x-ratelimit-limit-output-tokens: string、x-ratelimit-limit-requests: string、x-ratelimit-limit-tokens: string、x-ratelimit-remaining-input-tokens: string、x-ratelimit-remaining-output-tokens: string、x-ratelimit-remaining-requests: string、x-ratelimit-remaining-tokens: string、x-ratelimit-reset-input-tokens: string、x-ratelimit-reset-output-tokens: string、x-ratelimit-reset-requests: string、x-ratelimit-reset-tokens: string、x-request-id: string

json
{
  "error": {
    "code": "model_not_found",
    "message": "模型存在，但不具备当前端点要求的能力",
    "param": null,
    "type": "invalid_request_error"
  }
}

适用完整地址：https://api.tokenfactory.cn/v1/images/edits

供应商非 2xx 响应会归一化为当前公开协议的错误信封，并只保留安全响应头；502、504 或连接中断时，调用结果可能未知。

限制与计费 ​

适用完整地址限制或计费说明
https://api.tokenfactory.cn/v1/images/edits请求成功后按通用余额计费；余额不足时调用失败。
受全局请求体上限约束。
模型上下文与输出限制依当前模型和上游事实而定。
Token Factory 当前只接受 multipart/form-data；OpenAI 官方另有 application/json images 引用请求体，本接口尚未实现。
支持 multipart 的多 image part、可选 mask、filename、Content-Type、stream 及协议允许的未知文本 part。
OpenAI 官方对 GPT Image 模型允许最多 16 张、每张 png/webp/jpg 小于 50 MB；dall-e-2 仅允许一张小于 4 MB 的正方形 PNG，mask 也必须是小于 4 MB 且与首图同尺寸的 PNG。
Token Factory 对 Images Edit 使用 805 MiB 请求体门禁以承载官方最多 16 张图片；该总门禁不放宽逐图与蒙版限制。
除可重复 image 外，已列文本 part 最多出现一次；prompt 只拒绝全空白并保留首尾空白与换行，其他标量文本 part 必须是无首尾空白的非空 UTF-8；partial_images 只可与 stream=true 一起使用，dall-e-3 不支持编辑。
不支持 Images Variations、私有异步任务生命周期或视频编辑。
余额计费调用不会自动改用 Coding Plan 权益。

调用示例 ​

cURL · https://api.tokenfactory.cn/v1/images/edits ​

sh
curl --request POST "https://api.tokenfactory.cn/v1/images/edits" --silent --show-error --fail-with-body --max-time 60 --header "Authorization: Bearer ${TOKENFACTORY_API_KEY}" --form "model=${TOKENFACTORY_MODEL_ID}" --form "image=@source-one.png;type=image/png" --form "image[]=@source-two.webp;type=image/webp" --form "mask=@mask.png;type=image/png" --form "prompt=保留主体并改成夜景" --form "stream=false"

相关说明 ​

请求与响应按当前 OpenAI 兼容能力开放；供应商扩展字段可能随所选模型变化。

Token Factory · 国产合规 AI Gateway

无锡伟瑞达科技有限公司 · 苏ICP备2025202631号-3 · 苏公网安备32021302003207号