Amux

Create image edit

最近更新：2026年9月1日

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

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

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

鉴权

header
Authorizationstring必填

Bearer <你的 Amux 密钥> 控制台创建的 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 为准。折成精确像素是有损的， 折不出对应档位时会丢掉并在 amux.notes 里说明。取值域逐模型不同，见模型页。

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 不收

（它恒定按高保真处理输入图，API 不允许改）。

只有编辑端点有它；发到生成端点会被丢掉并在 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 与 gpt-image-1.5。除生成端点上那两处差异外，编辑端点还多一处：

gpt-image-2gpt-image-1.5
input_fidelity不收（恒定按高保真处理输入图）high / low，默认 low

专属文档：gpt-image-2 · gpt-image-1.5。

请求体是 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>"
    ]
  }
}