Edit a company image

Use POST /v1/images/edits only with a reviewed image.edit route. Submit multipart fields model, prompt, optional supported scalar options, and image or repeated image[] parts. Do not mix the two image field forms. A single mask is accepted only when the route permits it; required status, MIME, size, same-dimension and alpha requirements come from that reviewed contract.

Keep a stable Idempotency-Key for this operation. The gateway decodes actual image bytes, ignores the client filename and MIME as evidence, and validates the route's image count and size limits. PNG, JPEG and static WebP are the runtime formats; animated inputs are rejected. The default runtime ceilings are 16 MiB per image, 32 MiB of combined input and 16 million pixels per image, reduced further by route policy and configured request limits.

For background processing, add a multipart model_gate field containing {"async":true}. Company credentials stay in the Authorization header, never in multipart fields. The submitted files and resulting images are private to the operation's owner/principal/key/group scope. Use the operation ID, not another edit POST, to recover an interrupted client connection.

Follow company operation handling for polling, expiry and download-only retries. The company balance is settled through the existing accounting path, not a second image-specific wallet.

The Playground Images tab can serialize real multipart editing without exposing permanent API secrets. Optional model_gate.quote_sha256 binds a previous unpaid quote; input metadata used by a quote never substitutes actual file validation.

In company operation details and history, quoted amounts remain explicitly labelled until measured accounting is recorded. Calculated cost does not by itself confirm company settlement. An empty file list during processing is not an expired download. For the separate aggregate-only usage representation and price labels, see image result fields.

Image request errors

Errors contain a stable error.code, human-readable error.message, error.type and, where applicable, error.param. Keep X-Request-ID from the response for support; never send the API key. Unknown canonical model and alias return 400 model_not_found, not a catalog outage.

Restrictions of several routes are not merged into fictitious accepted combinations. Do not automatically repeat a paid POST after a timeout or ambiguous failure. Check operation status and keep the original idempotency key. Detailed internal configuration/credential errors are not returned to clients.