开发者文档

切换外观

编辑图片 ​

POST/images/edits

接口说明 ​

支持 Images Edits 的 multipart/form-data 文件上传与 application/json 图片引用请求；JSON 必须显式提供 model、prompt 与 images 引用对象数组，不接受 image 字段。文件、URL 与内联数据通过校验后原样转发，网关不下载引用图片；成功终态必须提供可信用量事实。JSON 总请求体默认上限为 4 MiB，base64 文本与其他字段共同计入；大图片可用 URL 或 multipart。multipart 使用平台 805 MiB 请求体门禁，且保留逐图与蒙版大小限制。

请求 ​

  • 方法：POST

  • 鉴权：Authorization: Bearer ${TOKENFACTORY_API_KEY}

请求头 ​

名称必填值或类型说明
Authorization是Bearer ${TOKENFACTORY_API_KEY}Token Factory API Key
Content-Type是multipart/form-data 或 application/json上传文件时由客户端生成带 boundary 的 multipart 请求头；图片引用 JSON 使用 application/json

路径参数：无

查询参数：无

请求字段 · multipart/form-data ​

字段类型必填说明示例或约束
backgroundstring否multipart 文本 part；可省略，提供时须为非空字符串；背景与格式组合由供应商判断。最短：1 字符；可为 null
imagestring (binary)[]是至少一个图片 part，最多 16 张，多图通过重复 image 或 image[] part 发送；平台 Images Edit 请求体门禁为 805 MiB。示例：["@source-one.png","@source-two.webp"]；最少：1 项；最多：16 项
input_fidelitystring否multipart 文本 part；可省略，提供时须为非空字符串；输入保真度由供应商判断。最短：1 字符；可为 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，请勿发送。若提供，必须是非空字符串；模型支持由供应商判断。示例："YOUR_MODEL_ID"；可为 null
ninteger (int32)否multipart 整数文本 part；允许为 null/省略，取值范围 1 到 10。最小值：1；最大值：10；可为 null
output_compressioninteger (int32)否multipart 整数文本 part；允许为 null/省略，取值范围 0 到 100，支持的格式组合由供应商判断。最小值：0；最大值：100；可为 null
output_formatstring否multipart 文本 part；允许为 null/省略。最短：1 字符；可为 null
partial_imagesinteger (int32)否multipart 整数文本 part；允许为 null/省略，取值范围 0 到 3，流式参数组合由供应商判断。最小值：0；最大值：3；可为 null
promptstring是图片编辑提示词；模型长度限制由供应商判断。首尾空白与换行按原始字节保留；仅当内容全部为空白时返回 400 invalid_request_error。示例："保留主体并改成夜景"
qualitystring否multipart 文本 part；允许为 null/省略，合法值随模型而异。最短：1 字符；可为 null
response_formatstring否multipart 文本 part；可省略，提供时须为非空字符串；载荷格式由供应商判断。最短：1 字符；可为 null
sizestring否multipart 文本 part；可省略，提供时须为非空字符串；输出尺寸由供应商判断。可为 null
streamboolean否multipart 布尔文本 part；省略或 SDK null 等同 false，线上只发送 true 或 false。示例：false；可为 null
userstring否用于 OpenAI 安全监测的终端用户标识；若提供必须是字符串。—

请求报文 · multipart/form-data ​

媒体类型：multipart/form-data

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

请求字段 · application/json ​

字段类型必填说明示例或约束
backgroundstring否可省略或为 null；提供时须为非空字符串，模型支持的取值由供应商判断。最短：1 字符；可为 null
imagesobject[]是必填的 1 到 16 个 image_url 引用对象，支持 HTTP(S) URL 或 image base64 data URL；内联编码解码后须小于 50 MiB，但 base64 文本与其他字段须共同满足默认 4 MiB JSON 总请求体上限及单字符串限制。URL 不在本地下载或核验字节；较大图片使用 URL 或 multipart，不支持 file_id、url 别名或裸字符串。示例：[{"image_url":"https://example.com/source.png"}]；最少：1 项；最多：16 项
images[].image_urlstring是非空 HTTP(S) URL 或 data:image/<格式>;base64,<数据>；不在网关下载内容。示例："https://example.com/source.png"；最短：1 字符
input_fidelitystring否可省略或为 null；提供时须为非空字符串，模型支持的取值由供应商判断。最短：1 字符；可为 null
maskobject否可选或 null 的遮罩引用对象；内联编码解码后须小于 4 MiB，同时与其他字段共同受默认 4 MiB JSON 总请求体上限及单字符串限制。URL 不在本地下载或核验字节，图片格式与尺寸由供应商判断。可为 null
mask.image_urlstring父字段存在时必填非空 HTTP(S) URL 或 data:image/<格式>;base64,<数据>；不在网关下载内容。最短：1 字符
modelstring是必填非空模型 ID；JSON 编辑没有默认模型。示例："YOUR_MODEL_ID"；最短：1 字符
moderationstring否可省略或为 null；提供时须为非空字符串，模型支持的取值由供应商判断。最短：1 字符；可为 null
ninteger (int32)否生成图片数量；可省略或为 null，范围 1 到 10。最小值：1；最大值：10；可为 null
output_compressioninteger (int32)否输出压缩级别；可省略或为 null，范围 0 到 100。最小值：0；最大值：100；可为 null
output_formatstring否可省略或为 null；提供时须为非空字符串，模型支持的取值由供应商判断。最短：1 字符；可为 null
partial_imagesinteger (int32)否流式中间图片数量；可省略或为 null，范围 0 到 3。最小值：0；最大值：3；可为 null
promptstring是必填非空编辑提示词；保留首尾空白与换行，仅拒绝全部为空白。示例："保留主体并改成夜景"；最短：1 字符
qualitystring否可省略或为 null；提供时须为非空字符串，模型支持的取值由供应商判断。最短：1 字符；可为 null
response_formatstring否可省略或为 null；提供时须为非空字符串，模型支持的取值由供应商判断。最短：1 字符；可为 null
sizestring否可省略或为 null；提供时须为非空字符串，模型支持的取值由供应商判断。最短：1 字符；可为 null
streamboolean否是否返回 Images Edit SSE；省略或 null 等同 false。示例：false；可为 null
userstring否终端用户标识；若提供须为字符串，可为空但不可为 null。—

请求报文 · application/json ​

媒体类型：application/json

json
{
  "images": [
    {
      "image_url": "https://example.com/source.png"
    }
  ],
  "model": "YOUR_MODEL_ID",
  "prompt": "保留主体并改成夜景",
  "stream": false
}

响应 ​

成功状态：200

响应头 ​

名称值或类型说明
Content-Typeapplication/json 或 text/event-stream响应媒体类型
request-idstringToken Factory 独立生成的平台请求编号；Anthropic 错误体的 request_id 与其相同。
retry-afterstring可选重试等待提示：非负秒数或标准 HTTP 日期。重试前仍需确认请求可安全重复。
x-request-idstringToken Factory 独立生成的平台请求编号，与 request-id 相同。

响应字段 ​

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

字段类型必填说明示例或约束
backgroundstring否实际输出背景模式。示例："opaque"；最短：1 字符；可为 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"；最短：1 字符；可为 null
qualitystring否实际输出质量。示例："high"；最短：1 字符；可为 null
sizestring否实际输出尺寸；auto 或正整数 WIDTHxHEIGHT。示例："1024x1024"；最短：1 字符；可为 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当前模型不可用否核对模型名称与当前入口的模型列表；持续出现时联系支持无
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_AVAILABLE_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 无权执行该请求否检查 API Key 权限与当前入口的模型可见性无
https://api.tokenfactory.cn/v1/images/edits409conflict_error请求与当前资源状态冲突视情况读取最新状态后修正请求或稍后重试中到高
https://api.tokenfactory.cn/v1/images/edits422unprocessable_entity请求结构正确但当前请求无法处理否按错误信息修正参数或输入内容无
https://api.tokenfactory.cn/v1/images/edits503service_unavailable服务暂不可用，请稍后重试视情况保留平台请求编号，稍后重试或联系支持中到高
https://api.tokenfactory.cn/v1/images/edits503service_busy模型服务繁忙，请稍后重试视情况参考 Retry-After 并限制重试次数；已收到输出时先确认是否可安全重复中到高
https://api.tokenfactory.cn/v1/images/edits400context_length_exceeded输入超过模型上下文限制否缩短输入或减少历史上下文后再发送无
https://api.tokenfactory.cn/v1/images/edits400missing_required_parameter缺少必填请求参数否按文档补齐错误指出的公开参数后再发送无
https://api.tokenfactory.cn/v1/images/edits400invalid_parameter请求参数的类型或格式不正确否修正错误指出的公开参数类型或格式后再发送无
https://api.tokenfactory.cn/v1/images/edits502upstream_usage_missing服务响应缺少可验证的用量信息视情况保留平台请求编号联系支持；确认可安全重复后再发送中到高

错误返回报文 ​

适用完整地址 ​

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

HTTP 400；Content-Type: application/json；响应头：request-id: string、retry-after: 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请求成功后按通用余额计费；余额不足时调用失败。
受全局请求体上限约束。
模型上下文与输出限制依当前模型和上游事实而定。
支持 multipart/form-data 文件上传及 application/json 图片引用；JSON model/prompt 必填，images 必填，1 到 16 个 image_url 对象仅支持 HTTP(S) URL 或 image base64 data URL。
JSON mask 可省略或为 null，否则须为 image_url 引用对象；不支持 file_id/Files 生命周期、单字符串、url 别名或裸 base64，图片内容不下载、不转换。
JSON 总请求体默认上限为 4 MiB，base64 文本与其他字段共同计入，且受 JSON 单字符串限制；逐图字节上界不代表可上传同等大小的 JSON，大图片可用 URL 或 multipart。
支持 multipart 的多 image part、可选 mask、filename、Content-Type、stream 及协议允许的未知文本 part。
multipart 允许最多 16 张、每张 png/webp/jpg 小于 50 MB；mask 必须是小于 4 MB 且与首图同尺寸的 PNG。
Token Factory 对 Images Edit multipart 使用 805 MiB 请求体门禁以承载官方最多 16 张图片；该总门禁不放宽逐图与蒙版限制。
除可重复 image 外，已列文本 part 最多出现一次；prompt 只拒绝全空白并保留首尾空白与换行，其他标量文本 part 必须是无首尾空白的非空 UTF-8；模型支持的参数值及其组合由供应商判断。
不支持 Images Variations、私有异步任务生命周期或视频编辑。

相关说明 ​

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

TokenFactory 词元工厂 · 开发者文档 · 返回官网

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