Amux

Create image edit

Last updated September 12, 2026

Edit with gpt-image-2.5-sunburst and reference images; multipart request, official SDKs work as-is.

Image-to-image with openai/gpt-image-2.5-sunburst. The body is multipart/form-data: reference images as files, everything else as ordinary fields.

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

Authorization

header
AuthorizationstringRequired

Bearer <your Amux key> Your Amux API key.

Request

multipart/form-data
modelstringRequired

A catalog model ID.

promptstringRequired

What to change.

imagearray<string>Required

Reference images. At most 16, 25MB each.

Both image and image[] are accepted. OpenAI SDKs typically send

the first for a single image and the second for several.

maskstring

A mask; transparent areas mark what to change. Three hard rules:

1. It must be a PNG with an alpha channel (add one if starting

from grayscale);

2. Same dimensions as the image, and under 4MB — the mask has its

own, much tighter limit than a reference image (we cap those at 25MB);

3. With several reference images it applies only to the first.

This field is only meaningful alongside a reference image. On its

own, it is ignored and noted in amux.notes.

nintegerDefault 1

How many images. Maximum 10; must be 1 when streaming.

sizestringDefault "1024x1024"

1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 2048x1152 / 3840x2160 / 2160x3840 / auto (default), or any legal pixel string — same constraints as the generation endpoint.

aspect_ratiostring

1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 16:9 / 9:16. An alternative spelling of size (the Google-ecosystem form); send one or the other. If both are given, size wins and we say so in amux.notes.

⚠️ Prefer size where you can. This upstream takes exact pixel sizes only, so a ratio is folded into one of them, together with image_size when given. The fold is lossy: a ratio with no exact match is approximated to the nearest available size, and if nothing is close enough the field is dropped — either way with a note in amux.notes. size states the result you want and is passed through unchanged.

image_sizestring

1K / 2K / 4K. Used together with aspect_ratio; same rules.

quality"low" | "medium" | "high" | "xhigh" | "max" | "auto"Default "auto"

Quality tier. xhigh and max are new in 2.5 and sit above high.

background"transparent" | "opaque" | "auto"Default "auto"

transparent / opaque / auto. Transparency needs png or webp.

output_format"png" | "jpeg" | "webp"Default "png"

png, jpeg or webp.

output_compressionstring

Compression level; jpeg / webp only, defaults to 100.

userstring

End-user identifier for abuse monitoring.

stream"true" | "false"

Return SSE. Form fields are strings, so send true as text.

partial_imagesstring

How many low-resolution previews while streaming (0-3, default 0).

Response

200response

Edited. Same shape as the generation endpoint.

400response

Malformed, or using something this path does not support (URL-form references). Also covers "streaming asked for but no provider streams" and "streaming with n above 1".

402response

The available balance cannot cover the reserve.

503response

Too many tasks in flight. Retry later.

Reference images and masks

The field name may be image or image[] — official SDKs send the former for one image and the latter for several. Up to 16 images, 25MB each.

A mask has three hard requirements:

  1. It must be a PNG with an alpha channel — the transparent areas get edited;
  2. Same dimensions as the image, and under 4MB;
  3. With several reference images, the mask applies only to the first one.

A mask takes effect only alongside a reference image. Sent on its own it is dropped, with an explanation in amux.notes; otherwise the upstream returns only "image is required", which does not identify the mask as the cause.

Cost

Reference images count as input tokens. The request reserves an estimated amount up front and settles against the actual usage in the response.

input_fidelity

This page deliberately omits that parameter. GPT-Image-2.5 does not accept it: sending input_fidelity causes the request to be rejected upstream, while an otherwise identical request without it succeeds. The gateway drops the field before the request is sent and records this in amux.notes, so an existing gpt-image-1.5 call that carries the field continues to work when retargeted at 2.5.

Asynchronous editing

Send the same fields to /v1/tasks (also multipart) for an asynchronous edit.

Streaming

Same as generation, with the events named image_edit.partial_image / image_edit.completed.

⚠️ Ordinary fields in a raw multipart request are strings, so stream=true must be sent as a text field.

Errors

The error shape matches OpenAI. See Errors and retries for the type values and their retry semantics.

cURL
curl https://gateway.amux.ai/v1/images/edits \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -F "model=openai/gpt-image-2.5-sunburst" \
  -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>"
    ]
  }
}