Amux

Create image edit

最近更新：2026年9月12日

用 gpt-image-2.5-flare 带参考图改图，multipart 请求，官方 SDK 直接可用。

openai/gpt-image-2.5-flare 的图生图。请求体是 multipart/form-data：参考图当 文件传，其余参数当普通字段。

POSThttps://gateway.amux.ai/v1/images/edits

鉴权

header
Authorizationstring必填

Bearer <你的 Amux 密钥> 站内 API Key。

请求

multipart/form-data
modelstring必填

站内模型 ID。

promptstring必填

想怎么改。

imagearray<string>必填

参考图，最多 16 张、单张 25MB。

image 与 image[] 两种字段名均支持。OpenAI SDK 通常在单图场景使用前者，多图场景使用后者。

maskstring

蒙版，透明处表示要改的区域。三条硬要求：

1. 必须是 PNG 且带 alpha 通道（灰度图要先自己加上）；

2. 尺寸与原图一致，且小于 4MB——这是蒙版自己的上限，

比参考图那个（我们限 25MB）严得多；

3. 多张参考图时它只作用于第一张。

该字段仅在同时提供参考图时生效。单独传入会被忽略，并在 amux.notes 中说明。

ninteger默认 1

出几张。上限 10，流式时必须是 1。

sizestring默认 "1024x1024"

1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 2048x1152 / 3840x2160 / 2160x3840 / auto（默认）， 或任意合法像素串——约束与生成端点相同。

aspect_ratiostring

1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 16:9 / 9:16。 size 的另一种写法（Google 生态的说法），两者给一个就够； 同时给时以 size 为准，并在 amux.notes 里说明。

⚠️ 建议优先使用 size。 这条上游只接受精确像素串，因此比例会连同 image_size（若提供）一起折算为其中一档。折算是有损的：没有精确匹配的 比例会被近似为最接近的一档，实在没有接近的则整个丢弃——两种情况都会在 amux.notes 中说明。size 表达的是确切的结果，且原样透传。

image_sizestring

1K / 2K / 4K。和 aspect_ratio 搭配用，规则同上。

quality"low" | "medium" | "high" | "xhigh" | "max" | "auto"默认 "auto"

low / medium / high / auto。

background"transparent" | "opaque" | "auto"默认 "auto"

transparent / opaque / auto。透明要配 png 或 webp。

output_format"png" | "jpeg" | "webp"默认 "png"

png / jpeg / webp。

output_compressionstring

压缩级别，只对 jpeg / webp 有意义，默认 100。

userstring

端用户标识，用于滥用追踪。

stream"true" | "false"

以 SSE 流式返回。表单字段是字符串，要写 true 而不是布尔。

partial_imagesstring

流式时给几张低清预览（0–3，默认 0）。

响应

200response

编辑成功。形状与生成端点一致。

400response

请求不合法，或用了这条链路不支持的能力（如 URL 形式的参考图）。 也包括「要流式但没有支持流式的供应商」与「流式时 n 大于 1」。

402response

可用余额不足以覆盖预扣上界。

503response

在途任务已满，稍后重试。

参考图与蒙版

参考图字段名 image 或 image[] 都收（官方 SDK 单图发前者、多图发后者）， 最多 16 张、单张 25MB。

蒙版三条硬要求：

  1. 必须是 PNG 且带 alpha 通道——透明的地方才是要改的区域；
  2. 尺寸和原图一致，且小于 4MB；
  3. 多张参考图时，蒙版只作用于第一张。

蒙版仅在同时提供参考图时生效。单独发送时会被丢弃并在 amux.notes 中说明； 否则上游只会返回「image is required」，无法看出问题出在蒙版上。

成本

参考图会按输入 token 计入成本。请求接受时会先预留一笔预计费用，完成后按响应里的 真实用量结算。

input_fidelity

本页不列出该参数。GPT-Image-2.5 不接受它：实测携带 input_fidelity 会被上游 拒绝，其余字段完全相同、仅移除该字段即可成功。网关会在请求发出前将其丢弃并记入 amux.notes，因此原本调用 gpt-image-1.5 且携带该字段的代码，改指向 2.5 后仍可 正常工作。

异步编辑

同一批参数发到 /v1/tasks（同样用 multipart）即可走异步编辑。

流式

和生成端点一样，事件名换成 image_edit.partial_image / image_edit.completed。

⚠️ 原始 multipart 请求中的普通字段均为字符串，因此 stream=true 需以文本字段 形式发送。

错误

错误体形状与 OpenAI 一致，type 取值与重试语义见错误与重试。

cURL
curl https://gateway.amux.ai/v1/images/edits \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "prompt=<string>" \
  -F "image=@/path/to/image.png" \
  -F "mask=@/path/to/mask.png" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "aspect_ratio=<string>" \
  -F "image_size=<string>" \
  -F "quality=auto" \
  -F "background=auto" \
  -F "output_format=png" \
  -F "output_compression=<string>" \
  -F "user=<string>" \
  -F "stream=true" \
  -F "partial_images=<string>"
{
  "created": 1786000000,
  "data": [
    {
      "b64_json": "<string>",
      "revised_prompt": "<string>"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  },
  "amux": {
    "task_id": "<string>",
    "generation_id": "<string>",
    "provider": "<string>",
    "cost_nano": "<string>",
    "images": [
      {
        "index": 0,
        "url": "<string>"
      }
    ],
    "notes": [
      "<string>"
    ]
  }
}