Amux AI

Create image edit

最近更新：2026年9月1日

带参考图改图。兼容 OpenAI Images edits 的形状，官方 SDK 直接可用。

带参考图改图。请求体是 multipart/form-data：参考图作为文件上传，其余参数作为普通表单字段。

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

鉴权

header
Authorizationstring必填

Bearer <你的 Amux AI 密钥> 控制台创建的 Amux 密钥。忘了可以回控制台的密钥页再看一次。

请求

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

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

sizestring

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

aspect_ratiostring

size 的另一种写法（Google 生态的说法），和 image_size 搭配用。 两套给一个就够；同时给时以 size 为准。取值域逐模型不同，见模型页。

⚠️ OpenAI 那几个模型上建议优先使用 size。 它们的上游只接受精确 像素串，比例会被折算为其中一档；折算有损，没有精确匹配的比例会被近似或 丢弃，并在 amux.notes 中说明。xAI 的出图正好相反：它原生接受 aspect_ratio，且完全不接受 size。

image_sizestring

分辨率档，和 aspect_ratio 搭配用。取值域逐模型不同，见模型页。

qualitystring

low / medium / high / auto。

backgroundstring

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

output_formatstring

png / jpeg / webp。

output_compressionstring

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

input_fidelity"high" | "low"

对原图的保真度，默认 low。控制「改一处时其余部分要多像原图」

——人脸、logo、文字这类细节走样，多半是它。

⚠️ 逐模型不同：gpt-image-1.5 支持；

**gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst

都不收**——gpt-image-2 恒定按高保真处理输入图，而 GPT-Image-2.5

则会被上游直接拒绝。这三个模型上，网关会在请求发出前将其丢弃并

记入 amux.notes，因此从 gpt-image-1.5 迁移过来的调用仍能成功。

只有编辑端点有它；发到生成端点会被丢掉并在 amux.notes 里说明。

userstring

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

streamstring

以 SSE 流式返回，事件是 image_edit.partial_image / image_edit.completed。 要求 n 为 1，且这个模型至少有一条支持流式的供应商。 ⚠️ multipart 的字段都是字符串，所以这里写 stream=true。

partial_imagesstring

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

响应

200response

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

400response

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

402response

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

503response

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

支持的模型

六个：gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2、 gpt-image-1.5、x-ai/grok-imagine-image-2.0、x-ai/grok-imagine-image-quality。

除生成端点上那几处差异外，编辑端点还多三处——下面「参考图」与「蒙版」 两节写的是 gpt-image 的规格，xAI 那两个不适用：

gpt-image-2.5（flare / sunburst）gpt-image-2gpt-image-1.5grok-imagine-image-2.0grok-imagine-image-quality
input_fidelity不收不收（恒定高保真）high / low，默认 low不收不收
mask支持支持支持不支持不支持
参考图张数最多 16最多 16最多 16最多 5最多 3

⚠️ GPT-Image-2.5 上的 input_fidelity 是被上游拒绝，不是被忽略。 我们在请求离开网关前就将其丢弃并记入 amux.notes，因此从 gpt-image-1.5 迁移过来的调用仍可正常工作；直接发往厂商则会返回 400。

专属文档：gpt-image-2.5-flare · gpt-image-2.5-sunburst · gpt-image-2 · gpt-image-1.5 · grok-imagine-image-2.0 · grok-imagine-image-quality。

请求体是 multipart

参考图当文件传，其余参数当普通字段。⚠️ 表单字段一律是字符串， 所以流式要写 stream=true（文本），不是布尔。

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

蒙版三条硬要求

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

蒙版只在同时给了参考图时才生效。单独给会被丢掉并在 amux.notes 里说明 ——否则上游只回一句「image is required」，看不出问题出在蒙版上。

比生成多一块成本

参考图按输入 token 计入。预扣按每张一个上界估，完成后按响应里的真实用量结算。

异步也能编辑

同一批参数发到 /v1/tasks（同样用 multipart）即可。

错误

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

cURL
curl https://gateway.amux.ai/v1/images/edits \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -F "model=<string>" \
  -F "prompt=<string>" \
  -F "image=@/path/to/image.png" \
  -F "mask=@/path/to/mask.png" \
  -F "n=0" \
  -F "size=<string>" \
  -F "aspect_ratio=<string>" \
  -F "image_size=<string>" \
  -F "quality=<string>" \
  -F "background=<string>" \
  -F "output_format=<string>" \
  -F "output_compression=<string>" \
  -F "input_fidelity=high" \
  -F "user=<string>" \
  -F "stream=<string>" \
  -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>"
    ]
  }
}