图像编辑

图像编辑允许应用通过 AISIX 发送源图片、可选蒙版和文本指令，并将调用方认证、模型别名、上游凭证和请求侧策略保留在同一条网关路径中。

AISIX 为使用 OpenAI 服务提供方配置的模型别名公开 OpenAI 的 multipart 图像编辑路由。gpt-image-2 等编辑模型会在同一个 multipart/form-data 请求体中接收图片、提示词和调节参数。

准备工作

请先准备以下内容：

• 一个可以处理代理请求的 AISIX 网关。
• 一个可以访问该模型别名的调用方 API Key。
• 一个配置服务提供方为 OpenAI、上游 model_name 为图像编辑模型（如 gpt-image-2）的模型别名。示例使用别名 image-edit-prod。
• 一张待编辑的源图片文件。示例使用 original.png。

导出网关连接和请求值：

# AISIX_PROXY 不含尾部斜杠或 /v1 等端点路径
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="image-edit-prod"

发送图像编辑请求

以 multipart 表单形式通过网关代理发送编辑请求，并在 model 字段中使用 AISIX 模型别名：

curl -sS -X POST "${AISIX_PROXY}/v1/images/edits" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -F "model=${AISIX_MODEL}" \
  -F "image=@original.png" \
  -F "prompt=Add a red hat to the subject" \
  -F "size=1024x1024" \
  -o aisix-image-edit-response.json

AISIX 会解析模型别名、检查调用方 API Key，并对提示词执行受支持的输入策略检查。它把 model 表单字段替换为上游模型 ID，然后重建并转发 multipart 请求体。源图片和蒙版会保留其字节、文件名及各部分的顺序，其他所有字段都会原样转发。只有已配置的脱敏动作安全护栏规则可以修改提示词。

响应保持 OpenAI 图片格式。编辑模型返回 Base64 图片数据和一个 Token 用量块：

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "..."
    }
  ],
  "usage": {
    "input_tokens": 50,
    "output_tokens": 1056,
    "total_tokens": 1106
  }
}

检查响应中包含一条图片记录：

jq '.data | length' aisix-image-edit-response.json

命令应输出：

1

请求字段

该路由只接受 multipart/form-data。JSON 请求体会返回网关错误信封中的 400。

字段	必填方	含义
model	网关	AISIX 模型别名。AISIX 唯一必定改写的字段；配置了脱敏动作的安全护栏规则还可能改写 prompt。
image	服务提供方	源图片文件。对于接受多张输入图片的模型，该字段可以重复出现；AISIX 会按原顺序转发每个部分，字节和文件名保持不变。
prompt	服务提供方	编辑指令。输入安全护栏会在请求发往上游之前检查并可脱敏该文本。
mask	—	可选的蒙版图片，其透明区域标记要编辑的范围。原样转发。

其余所有表单字段——n、size、quality、background、input_fidelity，以及服务提供方后续新增的任何参数——都会原样转发，因此上游新增参数不需要升级网关。未设置的字段不会出现在上游请求中。

备注

该路由不支持 stream=true。编辑模型可以用服务器发送事件流式返回部分图片，但 AISIX 尚未中继该数据流，因此会直接返回 400，而不是静默缓冲。

OpenAI 服务提供方要求

图像编辑路由是服务提供方专属路由。只有当解析到的模型配置的服务提供方为 OpenAI 时，AISIX 才会接受请求。

这比使用兼容 OpenAI 的适配器更严格。一个兼容 OpenAI 的供应商可以在聊天补全路由上正常工作，但由于其配置的服务提供方不是 OpenAI，仍会在图像编辑路由上被拒绝。

当解析到的模型配置的服务提供方不是 OpenAI 时，AISIX 会在向上游发送任何内容之前返回 400。

上游 URL 的推导方式与其他 OpenAI 路由一致：未设置 api_base 时解析到标准 OpenAI API；api_base 为不带路径的主机时会在端点路径前追加 /v1。

图像编辑行为

输入安全护栏会在 AISIX 调用服务提供方之前检查每一个 prompt 表单字段，脱敏动作规则会就地改写提示词文本。被阻断的提示词会在任何上游调用之前返回 422，且不占用模型限流容量。图片和蒙版字节不是可扫描文本，输出安全护栏也不会扫描生成后的图片字节。

提交会同时计入调用方 API Key 各层限流和模型限流。当上游响应包含 Token 用量块时——gpt-image 系列模型会返回——AISIX 会记录这些 Token 并计入基于 Token 的限流；不含用量块的响应按零 Token 记录。图片数量、尺寸和质量等按图片计费的细节不会在此代理路径中推断。

错误

失败会返回网关的 JSON 错误信封。服务提供方返回的 4xx——例如模型拒绝的 size 取值——会携带服务提供方自己的状态码和消息原样中继，不在下表范围内；下表只覆盖 AISIX 自身生成的状态码。

状态码	触发场景
400	请求体不是有效的 multipart/form-data、缺少 model 字段、设置了 stream=true，或解析到的模型服务提供方不是 OpenAI。
401	调用方 API Key 缺失或无效。
403	调用方 API Key 无权使用该模型别名，或请求来自模型允许列表之外的客户端 IP。
404	模型别名无法解析。
413	请求体超过配置的请求体大小限制。
422	输入安全护栏阻断了提示词。不会向服务提供方发送请求。
429	限流或 AISIX Cloud 预算拒绝了该请求。
502	服务提供方返回服务端错误、响应不是有效 JSON，或无法连接。
504	服务提供方未在模型的请求超时时间内应答。

下一步

你现在已经了解 AISIX 如何代理 OpenAI 图像编辑请求，以及 multipart 表单如何经过网关。接下来可以查看图像生成了解提示词生成图片路由，或查看语音与音频了解其他 multipart 端点。