Amux

Create image edit

Last updated September 1, 2026

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

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

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 only takes effect alongside a reference image. On its own it is dropped, with an explanation in amux.notes — otherwise the upstream just answers "image is required", which does not point at the mask.

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: per the official OpenAI documentation, gpt-image-2 always processes input images at high fidelity, so input_fidelity is not configurable here.

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.

⚠️ Ordinary fields in a raw multipart request are strings, so send stream=true 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" \
  -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>"
    ]
  }
}