Amux

Create image edit

最近更新：2026年9月1日

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

openai/gpt-image-2 的图生图。请求体是 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 / 3:2 / 2:3 / 16:9 / 9:16。size 的另一种写法（Google 生态的说法）， 两者给一个就够；同时给时以 size 为准，并在 amux.notes 里说明。 折成精确像素是有损的，折不出对应档位时会丢掉并记 note——不会替你猜一个尺寸。

image_sizestring

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

quality"low" | "medium" | "high" | "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

这一页故意没有这个参数：按 OpenAI 官方文档，gpt-image-2 会始终以高保真处理 输入图像，因此不支持修改 input_fidelity。

异步也能编辑

同一批参数发到 /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" \
  -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>"
    ]
  }
}