Amux

Create image edit

Last updated September 1, 2026

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

Image-to-image with openai/gpt-image-1.5. 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.

size"1024x1024" | "1536x1024" | "1024x1536" | "auto"Default "1024x1024"

Only these, or auto (the default):

1024x1024 (1:1) - 1536x1024 (3:2 landscape) - 1024x1536 (3:2 portrait)

⚠️ Only the tiers above. Anything else is rejected upstream.

The Google-style "aspect ratio + resolution tier" spelling

(aspect_ratio / image_size) also works; we convert to one of the

three above, downgrading a 2K/4K request to the nearest legal tier

with a note in amux.notes.

aspect_ratiostring

1:1 / 3:2 / 2:3. 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. Folding a ratio into exact pixels is lossy, and when no tier matches we drop it and note it rather than guessing a size for you.

image_sizestring

1K. Used together with aspect_ratio; same rules.

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

Quality tier.

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.

input_fidelity"high" | "low"Default "low"

Edits only, defaults to low.

It controls how closely unchanged areas follow the original. low

allows more repainting outside the edited region; localized retouching

usually works better with high.

Drifting faces, logos and text usually trace back to it.

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.

input_fidelity: how closely the rest must match the original

low (the default) repaints more freely, and faces, logos and text drift; localized retouching almost always wants high.

This is one of the main differences from gpt-image-2, which always works at high fidelity and does not let you change it.

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 (OpenAI allows 50MB; we are stricter).

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 only takes effect alongside a reference image. On its own it is dropped, with an explanation in amux.notes.

Size and cost

Sizes match the generation endpoint: 1024x1024 / 1536x1024 / 1024x1536 / auto.

Reference images count as input tokens, and this model also produces text output tokens (internal reasoning). A reserve is held when the request is accepted and settled against the actual usage in the response.

Editing works asynchronously too

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.

⚠️ Multipart fields are always strings, so send stream=true as text, not a boolean.

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-1.5" \
  -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 "input_fidelity=low" \
  -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>"
    ]
  }
}