POST /v1/images/edits
Multipart image edits with private operation results.
No current prepared translation is available. The English source is shown without machine translation.
Edit existing images through a configured image.edit route. This endpoint accepts multipart form data, not JSON image URLs.
Send model, prompt, the route's supported scalar settings, and either one image field or repeated image[] file parts. An optional mask is one file whose MIME, dimensions and required alpha properties must satisfy the selected reviewed contract. A route can disallow masks, require matching input dimensions or narrow the accepted formats and input counts. Add model_gate as a JSON string, such as {"async":true}, for asynchronous execution.
Use the normal Authorization header and a required Idempotency-Key. File names and submitted content types do not override inspection of the bytes. The runtime accepts static PNG/JPEG/WebP only, with ceilings of 16 MiB per file, 32 MiB of input bytes and 16 million pixels per image. Animation, corrupt files, duplicate scalar fields and unsupported settings fail before a paid dispatch. Server request limits can be smaller.
The response and polling flow match generation. Keep the operation ID and reuse the same idempotency key after a client timeout; do not upload a new paid edit just to retrieve the existing result. Source files are never served through the output download API. See image operations.
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.
Price quote and Usage Limit quote are preliminary values. Calculated cost is still distinct from a completed balance update. Saved-file availability requires an existing file and an unexpired download window. Aggregate-only token observations may appear in reported_tokens with token_usage_status=aggregate_only_not_priced; they do not supply a missing modality breakdown for token pricing. See generation response 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.
| HTTP | Code | Action |
|---|---|---|
| 400 | model_not_found | Check model ID or alias. |
| 400 | unsupported_parameter / unsupported_value / incompatible_parameters | Correct the indicated parameter using that route's contract; allowed values may be provided. |
| 422 | image_route_not_available | Check or remove the explicit route_id. |
| 503 | image_route_unavailable | No reviewed route is currently available; contact support. |
| 503 | image_configuration_unavailable | Route configuration/pricing is unavailable; contact support. |
| 503 | image_catalog_unavailable | The catalog backend failed. |
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.