Image Edits API

Experimental. /v1/images/edits accepts a prompt and reference images for a model that supports image conditioning. Check the build requirements and request examples before using this API. For vLLM-Omni model limits, see Image Edit Capabilities.

Request Contract

Send either multipart/form-data uploads or application/json references. prompt and at least one input image are required. n controls the number of output images, independently of the input count.

Multipart Uploads

• Use image for one file, or repeat image or image[] for multiple files. Choose one field name per request; input order is multipart part order.
• Upload PNG, JPEG, or WebP. File contents determine the format, regardless of the filename or declared MIME type.
• Do not mix files with input_reference, url, or url[] fields. Mask fields (mask and mask_image), duplicate scalar fields, and unknown fields return HTTP 400.

Supported scalar fields are prompt, model, n, quality, background, output_format, response_format, size, style, user, and moderation. Backend validation determines which controls the loaded model supports. Encode nvext as one form field containing a JSON object.

JSON References

Set input_reference to an HTTP(S) image URL, a base64 data URL such as data:image/png;base64,..., or an ordered array of those strings. Empty arrays, blank references, and filesystem paths are invalid. Do not combine input_reference with image, URL, or mask fields.

/v1/images/generations also accepts this JSON extension for reference-capable models. Both routes apply the same input-count and serialized-request limits. Workers validate URL destinations and redirects before fetching references.

Image Edit Limits

Set these environment variables before starting the listed processes. Values must be positive decimal integers without unit suffixes; invalid values fail startup. Pixel counts are width multiplied by height before RGB expansion. Both means the frontend and each aggregated Omni worker. When frontend, worker, and model limits differ, the lower applicable limit wins.

Additional limits apply:

• DYN_HTTP_BODY_LIMIT_MB caps the complete HTTP body, including multipart framing and chunked uploads.
• DYN_MM_MAX_DATA_URL_MB and DYN_MM_MAX_FILE_SIZE_MB bound inline references and remote downloads on the worker. Uploads become data URLs, so account for base64 expansion when configuring both sides.
• DYN_TCP_MAX_MESSAGE_SIZE caps each TCP frame. The default 28 MiB request budget leaves room below the default 32 MiB frame cap. If increasing the request budget, allow space for the transport envelope and configure the frame limit on both sides.

These are per-request limits. They do not bound total process memory under arbitrary concurrency or guarantee that an accepted request fits GPU memory.

Errors and Cancellation

These statuses cover request validation, reference loading, and admission:

Remote image servers can return other HTTP errors, which retain their status. A failing reference stops the edit before generation; Dynamo does not return a successful edit using only the earlier references. Client disconnects cancel pending upload and reference-fetch work.

Capabilities and Rolling Upgrades

The frontend admits an edit only when every worker it might route that request to supports the input count. A legacy worker or one with unknown capability limits those requests to one input. An explicitly advertised zero rejects edits. The Omni worker also checks its loaded model and configured limit before loading references; changing the model name in a request cannot raise the limit.

Upgrade all workers eligible to serve the model before sending multiple inputs. A single reference retains the legacy string wire format; multiple references use an array under the same input_reference field. Older workers reject the array instead of silently using only its first image.

Custom Backend Capability Schema

Backend authors, including authors of custom in-process engines, register this capability in the image engine’s ModelDeploymentCard.user_data. It is deployment metadata, not a field in an HTTP image request. The following example is the value of user_data:

{
  "image_edits": {
    "schema_version": 1,
    "max_input_images": 4
  }
}

Missing or invalid records, and unknown schema versions, fall back to one reference. This compatibility fallback does not establish that a backend supports editing. Publish the smaller of the loaded model’s supported count and the deployment’s configured count. The engine must still validate and load all references in order; advertising a capability does not implement it.