Create task

Last updated September 2, 2026

Submit an async task for openai/gpt-image-2. One endpoint for both generation and editing — send a reference image and it edits.

Submit openai/gpt-image-2 work to /v1/tasks: you get an id immediately and the work happens in the background.

This endpoint does not split generation from editing — omit image and it generates, send one and it edits. The parameters are the same either way, which is why there is only this one page.

The parameter table below is the multipart/form-data shape, which is the superset. Without reference images the same fields can be sent as JSON.

POSThttps://gateway.amux.ai/v1/tasks

Authorization

header

AuthorizationstringRequired

Bearer <your Amux key> Your Amux API key.

Request

multipart/form-data

modelstringRequired

A catalog model ID.

promptstringRequired

What you want. With a reference image it describes the edit.

imagearray<string>

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.

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.

webhook_urlstring

Where to POST the result once the task is terminal. https only, and never a private network.

moderation"auto" | "low"

Moderation level. Only applies without reference images — the upstream

edits endpoint has no such field, so with a reference image it is dropped

and reported in notes.

Response

200response

Already terminal (Prefer: wait caught it), or this is a replay

of the same idempotency key.

Kept apart from 202 deliberately: 202 means "I took this on", and

neither of these took on anything new.

202response

Accepted, and the reserve is held. Use the id to fetch the result.

400response

Invalid request. Also covers stream: true and partial_images above 0 —

this endpoint is asynchronous; for synchronous streaming use

/v1/images/generations.

402response

Available balance does not cover the upper-bound reserve.

503response

Too many tasks in flight; retry later (the response carries Retry-After).

Three ways to get the result

	How	When it fits
Poll	`GET /v1/tasks/{id}`	Simplest; every 2-5 seconds
Callback	send `webhook_url`	You would rather not hold a connection
Wait in place	send `Prefer: wait=60`	You want it synchronously without polling

Task lifecycle, callback signing and verification, idempotency — these are the same for every model; see Create task.

How this differs from the vendor-compatible endpoints

	`/v1/images/*`	`/v1/tasks`
Generation / editing	two endpoints	one, split by reference image
Delivery	synchronous (streamable)	async + callback + optional wait
Compatibility	official OpenAI SDKs work as-is	our own shape

Use this one for slow work: on the synchronous path any timeout along the way (reverse proxy, gateway, client default) leaves you without the image after the money has been spent.

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/tasks \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -F "model=openai/gpt-image-2" \
  -F "prompt=Make the fox wear a red scarf" \
  -F "image=@/path/to/image.png" \
  -F "size=1024x1024" \
  -F "webhook_url=https://hooks.example.com/amux"

{
  "id": "task_01M1CG35C16CJ790D00BV1RBVM",
  "status": "queued",
  "model": "openai/gpt-image-2",
  "created_at": "<string>",
  "output": {
    "images": [
      {
        "index": 0,
        "url": "<string>"
      }
    ]
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  },
  "cost": "0.2108",
  "error": {
    "message": "<string>",
    "code": "<string>"
  }
}