Edit an Image

Editing is synchronous, like generation: the request stays open until the images are ready. Send multipart/form-data — the source images are file parts, and every other parameter rides alongside them as a text field.

Source images are read only to identify and measure them, and are never persisted — no stored object, no database row, nothing retained once the response is sent. Only the model's output is persisted, and only when you ask for response_format: "url".

The whole request body is capped at 40 MiB, source images and form framing together; over that is a 413. A model that only generates — the Endpoints column says which — is a 400 here naming model, not a silent fallback.

Source images

Repeat the image field, or name it image[], to pass several source images in one request; the model composes from all of them. The two forms are equivalent.

Both the number of source images and the size of each are capped per model, and both are enforced before any rendering begins:

Accepted types are PNG, WEBP, JPEG — identified from the bytes, not from the content type your form declares. HEIC is not accepted, because this surface never transcodes. An oversize file is a 400 naming which one it was (image[1]) and the limit it broke, so a rejection is actionable without guessing.

Which cap you meet first depends on the model. On 4 of them — seedream-4.0, seedream-4.5, seedream-5.0, seedream-5.0-pro — a full set of source images at the per-file maximum would far exceed the 40 MiB body cap, so the body is what binds and those files share the 40 MiB between them. On the rest, a full set fits inside the body cap with room to spare, so the per-file limit is the only one you can hit.

Note what the last column costs you: on those models the per-source fee is charged for each delivered image, not once per request — so where the model also accepts an n above 1, source images and n multiply. See Billing below.

Masks are not supported

mask is refused by name rather than ignored: no model on this surface offers masked editing, so a mask would silently have no effect. Describe the region you want changed in the prompt instead.

Models

size takes any WIDTHxHEIGHT inside the model's envelope — the envelope column is the whole surface, not a list of presets, and within it the image arrives at exactly the size you name. Two carve-outs:

• A size below the model's minimum scales up. You get the smallest size the model renders at your exact aspect ratio — never fewer pixels than you asked for, and never a changed shape. This is how the OpenAI canonical sizes work on seedream-4.5 and seedream-5.0, whose pixel floor sits above all three: ask for 1024x1024 and the delivered image is 2048x2048; 720x1280 delivers 1440x2560.
• qwen-image-edit-plus and z-image-turbo render on a 16-pixel grid. Each side rounds to the nearest multiple of 16, ties to the even multiple — 1000x700 arrives as 992x704. Sides already divisible by 16 arrive exactly.

A size outside the envelope — over its pixel ceiling, or at an aspect ratio beyond its limit — is a 400 naming the envelope. A below-minimum size is never an error.

Every model additionally accepts size: "auto", and a model whose default size reads model decides has no fixed output shape: on an edit it follows your source image, and on a generation the model picks for itself.

The Transparent column marks the models that can render an alpha channel — seedream-5.0-pro — and it is an edits-only capability. Transparency needs something to be transparent around, so on this endpoint background: "transparent" fails for every model without exception: we refuse it outright on the models with no alpha support, and on the one that has it the request is refused for having no source image. Either way you get a 400. On edits, where it does work, it carries further conditions worth reading before you rely on it.

The response carries the image, not a size field — measure the bytes if the exact shape matters to you.

Prompt handling

Your prompt is used exactly as you wrote it — no rewriting, no prefix, not even a trim, because leading and trailing whitespace is yours and models do respond to it. Prompts run to 32,000 characters, counted as JavaScript string length, so anything outside the basic multilingual plane — most emoji — counts as two.

seedream-4.0, seedream-4.5, seedream-5.0 and seedream-5.0-pro expand the prompt before rendering it, and there is no switch to turn that off, so a terse prompt can produce a more elaborate image than you specified. The remaining models render what you wrote. Nothing in the response reports the expanded text, so if reproducibility matters, prefer a model that does not expand and write the detail yourself.

Delivery

response_format decides where the pixels go, and the two options have different privacy properties:

• "b64_json" (default) inlines the bytes in the JSON response. The image is not stored — no object, no row, no URL, and nothing to expire. Your request is still recorded in your usage history like any other, to the depth your organization's logging level sets.
• "url" stores each image for 24 hours and returns an authenticated URL. The URL is not public: fetching it needs your API key, the same as any other endpoint. After 24 hours it returns 404. There is no delete endpoint — expiry is the only removal path.

Batching

n is bounded per model rather than at OpenAI's flat 10 — see the Max n column. The ceilings are not one rule: some models have no documented n at all and are pinned to 1, and on the slowest models a full fan-out would not finish inside the request wall.

However it is served, n means n separate answers to your whole prompt. A prompt asking for "six variations" still returns exactly the n you requested, never a set the model decided on for itself, and never one picture divided across several files.

Underneath, qwen-image-2.0 and qwen-image-edit-plus render the whole batch in one pass, while the remaining models render n single images concurrently. Nothing in the response distinguishes them, and the only place it surfaces is the bill: see Billing for what n does to a per-source charge.

Unknown parameters are refused

We do not silently drop parameters we do not recognise. Any key outside the documented set is a 400 naming it — unknown parameter 'foo' — so a typo fails loudly instead of appearing to work while changing nothing.

Several parameters from OpenAI's images API are recognised and then refused by name, because no model here implements them. The refusal says which one and why, so you can tell whether to drop the parameter or change model. quality is the one partial case — it is accepted, but only as "auto":

If you are porting OpenAI code, strip these before your first call.

Errors

Every failure is the same { "error": { "message", "type", … } } envelope. Read the status and type together — the 5xx family all report api_error, so the status is what separates a transient failure worth retrying from one that is not.

Every response carries X-RateLimit-Limit-RPM, -TPM and -TPD with their -Remaining counterparts, which is where to look when a 429 is not obviously yours.

Two of these are worth planning for specifically. Capacity pressure reaches you as a 503, never a 429 — a retry policy keyed only on 429 will not fire for it, and it is the most common transient failure on this surface. And a 429 is not always about rate: an unpriced model on your tier, or one with no price in your billing currency, is refused the same way.

Billing

Images are billed per delivered image. Most models carry a single rate for every size they render; on seedream-5.0-pro and qwen-image-3.0-pro the rate steps up once the delivered image's pixel count crosses the model's large-size threshold — it is the delivered pixels that pick the rate, so naming a size pins it. A model whose default reads model decides can come back at a shape you did not pick, and you are billed for the shape that arrived. Your usage history itemizes each request into per-meter line items, one per rate applied, so what you were charged for is always visible there. Your tier's price list is the authority on the rates themselves and on where each model's threshold sits.

seedream-5.0-pro, qwen-image-3.0 and qwen-image-3.0-pro additionally bill per source image on an edit, at a flat rate that does not vary with size. That line counts source images per delivered image, not once per request — so on a model that accepts an n above 1, three source images with n: 2 bills six rather than three. Where the ceiling is 1 the two numbers are the same and the distinction never appears.

A request that returns no images is not billed at all, and a partly successful batch is billed only for the images it delivered — source images included.

Images carry no token meter. They report zero tokens and add nothing to your tokens-per-minute or tokens-per-day counters. They are still checked against those limits, though: an image request refused with a token-limit 429 is being turned away on allowance your other traffic has already spent, not on anything the image itself consumed.