Docs
Get an API key
API reference›Images

Edit Image

POST /v1/images/edits Models: Images View .md

Edits or recombines images with a prompt, in OpenAI's shape (images.edit() in OpenAI's SDKs): multipart image[] files and an optional mask, or JSON images: [{image_url}] and mask: {image_url}; OpenRouter's input_references works too. The same implementation as /v1/images/generations, and the same fields and answer.

Only a model with reference editing takes this route. z-image-turbo has none: the request is a 400 naming image (or images, input_references, mask, whichever was sent). Each image is an upload, a base64 data URI or an https URL the gateway fetches itself (public addresses only); the engine only receives bytes. An image's type is read from its bytes and checked against the model's accepted formats.

On minimax-h3 the references (1 to 9 PNG, JPEG or WebP images) render one still on its reference task. Its Turbo is no steps, steps 8 or quality turbo (auto, low); the prompt mode's tiers apply above it (steps 10 to 50, or quality standard, max or ultra, on the base weights), and any other count is a 400 (steps must be an integer between 10 and 50, or 8 with image references). Each reference larger than 1 megapixel is scaled down to it by the gateway, keeping its aspect ratio and format, before the engine gets it.

Billing is the output megapixels, so an edit with any number of references bills the same as a generation of the same size, except on minimax-h3, whose reference stills bill the megapixels times 1.5 + 0.75 per reference (2.25 with one, 8.25 with nine; price_options in GET /v1/models?format=openrouter). size auto is the model's default size, not the first image's.

Body

multipart/form-data

OpenAI's multipart edit request, as images.edit() sends it. Every other field of the create request is a form field too (steps, guidance_scale, ... as plain fields; provider and input_references as JSON strings).

  • prompt string required
  • model string
  • image array of string (binary)s required

    One or more image files, at most the model's reference count (minimax-h3, 9; qwen-image-2.1, 10). Send them as image[] (what the OpenAI SDKs do); PHP keeps only the last of several parts named plainly image. A model that scales references down (minimax-h3, to 1 megapixel each) does so before its engine gets them; above 50 megapixels an image is a 413.

  • mask string (binary)

    A PNG mask; it needs at least one image.

  • n integer
  • size string
  • response_format string
    urlb64_json
  • output_format string
  • output_compression integer
  • background string
  • seed integer
  • stream boolean
  • upscale string

    The upscale object of the JSON request as JSON text, such as {"fallback": "original"}.

Body

application/json
Fields as application/json
  • prompt string required

    A text description of the desired image(s). The maximum length is the model's (4000 characters for z-image-turbo), counted as Unicode characters rather than bytes.

    at most 4000 characters
  • model string

    The model to use for image generation. Defaults to z-image-turbo. GET /v1/images/models lists the image models currently served. An unknown model returns 404.

    default z-image-turbo
  • n integer

    The number of images to generate. The images in one request are generated together, so changing n can change every image, including the first, for the same seed.

    default 1range 1–10
  • response_format string

    How the image comes back. url is a presigned link that expires after one hour; b64_json is the image inline as base64. The default is b64_json on POST /v1/images (OpenRouter's SDKs require it) and url on /v1/images/generations and /v1/images/edits.

    urlb64_json
  • size string

    WIDTHxHEIGHT in pixels, or a resolution label (1K, 2K, ...). For z-image-turbo any sides that are multiples of 16, an area from 65,536 to 4,194,304 pixels and a longer side at most 4 times the shorter (so 768x768 works and 1000x1000 is a 400). auto is the same as leaving it out. An aspect_ratio or resolution beside an explicit size must agree with it.

    default 1024x1024
  • width integer deprecated

    Legacy spelling of size, kept because this API once documented it as ignored. Needs height and means size "{width}x{height}" under the same rules; a 400 if it disagrees with a size sent beside it. Use size.

  • height integer deprecated

    See width.

  • aspect_ratio string

    One of the model's aspect ratios (GET /v1/images/models). With resolution, or alone at the model's default resolution, it picks the size.

  • resolution string

    One of the model's resolutions (512, 768, 1K, 1.5K, 2K for z-image-turbo; 4K is a 400).

  • seed integer (int64)

    Random seed. Must be an integer; fractional values are rejected rather than rounded. When omitted, each request uses a random seed.

    Repeating a request with the same seed and the same value for every other field, including n and size, returns the same images from the same model version on the same hardware. A model or engine update can change the images a seed produces, and replicas on different GPUs can differ in the last bits.

  • output_format string
    default pngpngjpegwebp
  • output_compression integer

    The encoder quality for jpeg and webp, the compression level for png. The engine's own default applies when omitted.

    range 0–100
  • background string

    auto and opaque give an opaque image. transparent only works on a model whose spec supports it (it also needs output_format png or webp); on z-image-turbo it is a 400.

    default autoautoopaquetransparent
  • input_references array of objects

    OpenRouter's reference images, for a model with reference editing (z-image-turbo has none, so it is a 400 naming this field). Each is {"type": "image_url", "image_url": {"url": "<https URL or base64 data URI>"}}. The gateway fetches an https URL itself.

    2 fields
    • type string required
      image_url
    • image_url object required
      1 field
      • url string required
  • steps integer

    The number of denoising steps (z-image-turbo: 1 to 50, default 8). Generation time grows roughly linearly with steps. Also accepted as num_inference_steps, and under provider.options (see provider).

    For z-image-turbo the last step of the schedule lands at zero noise and does not change the image, so N steps apply N - 1 denoising updates. The default of 8 applies 7; 9 matches the 8 updates in the upstream Z-Image-Turbo reference.

    range 1–50
  • num_inference_steps integer

    Alias of steps.

    range 1–50
  • guidance_scale number (float)

    Classifier-free guidance strength, on the model's own scale, so a value from its model card works as written. Each model's range and default are in its entry in GET /v1/images/models; when omitted, that default is used.

    On z-image-turbo 0 is off and the default (also the upstream recommendation for Turbo models); higher values are not a quality setting there. On moss-image and qwen-image-2.1 1 is off (qwen-image-2.1 defaults to 1 and also accepts this setting as true_cfg_scale). Guidance above off enables negative_prompt and roughly doubles the model work per step.

    range 0–20
  • negative_prompt string

    Text describing what to steer the image away from. It only takes effect when guidance_scale is above 0; at the z-image-turbo default of 0 it is ignored. On qwen-image-2.1 it takes effect when guidance_scale is above 1, and when omitted it is " " (the model's empty negative prompt), so guidance_scale alone turns guidance on. It changes the output, but does not guarantee that the described content is absent.

  • provider object

    OpenRouter's provider preferences. The routing fields (order, only, ignore, sort, allow_fallbacks, ...) are accepted and ignored. options carries the model's own settings (steps, guidance_scale, negative_prompt) for clients that cannot add top-level fields. From OpenRouter's SDKs use options.stealth: they keep only the slugs on their closed list and drop any other, vultr included, without an error. The first form present wins, the top level before any option; a key the model does not declare is a 400 naming its path.

  • upscale object

    What to answer when the upscale of a size the gateway enlarges after the model (minimax-h3's 4K, with SeedVR2) cannot run. fallback none (the default) fails the request with 429, 503 or 502 and bills nothing; original answers the model's own render instead and says so (upscale.applied false in the answer, and the X-Vultr-Upscale header). On any other size it changes nothing. In a multipart form send it as JSON text.

    1 field
    • fallback string
      default nonenoneoriginal
  • stream boolean

    true answers text/event-stream: one image_generation.completed event (see the response), then [DONE]. Always base64. Not with n above 1.

  • partial_images integer

    OpenAI's partial image count. Only 0 is accepted; a stream carries the finished image only.

    range 0–0
  • user string

    Accepted and ignored.

  • session_id string

    Accepted and ignored.

  • trace object

    Accepted and ignored.

  • images array of objects

    The images to edit, at most the model's maximum (10 for qwen-image-2.1), 20 MB each. A file_id is not supported.

    1 field
    • image_url string required

      An https URL (public addresses only; the gateway fetches it) or a base64 data URI.

  • mask object

    A PNG mask for the edit; it needs at least one image.

    1 field
    • image_url string

Responses

OK

application/json · create-image-response-payload

7 fields
  • created integer required

    The Unix timestamp (in seconds) of when the image was created.

  • data array of objects required

    The list of generated images.

    4 fields
    • b64_json string

      The base64-encoded image, in output_format. Present when response_format is b64_json, which is the default of POST /v1/images.

    • url string

      A presigned link to the image. Present when response_format is url, which is the default of /v1/images/generations and /v1/images/edits. Expires after one hour. OpenRouter's SDKs require b64_json, so do not use links with them.

    • media_type string required

      The MIME type of the image (image/png, image/jpeg or image/webp).

    • revised_prompt string

      Only present when the engine really rewrote the prompt.

  • size string

    The size generated. On a size the gateway upscales, the images' real size: the model's render's when the upscale fell back to it (upscale.applied false).

  • output_format string
  • background string

    transparent only when the model produced a transparent image, otherwise opaque.

  • usage object required

    Always present. Images are not billed in tokens, so the token counts are 0; they are there because OpenRouter's SDKs require all three whenever usage is present.

    8 fields
    • prompt_tokens integer required
    • completion_tokens integer required
    • total_tokens integer required
    • input_tokens integer

      OpenAI's name for prompt_tokens.

    • output_tokens integer

      OpenAI's name for completion_tokens.

    • input_tokens_details object
      2 fields
      • text_tokens integer
      • image_tokens integer
    • cost number required

      Dollars billed for this request. megapixels times the model's price per megapixel; 0 for a model with no price.

    • megapixels number required

      The billed quantity. Output megapixels (width x height / 1,000,000 per image returned), times the model's step scaling where it has one. Reference images and masks are not billed.

  • upscale object

    What became of the upscale of a size the gateway enlarges after the model with SeedVR2 (minimax-h3's 4K), present only on such a size. applied true: every image was upscaled by model. applied false: the request sent upscale.fallback original, the upscale could not run, and the images are the model's own render instead, at the size in the answer's size; reason says why. The X-Vultr-Upscale header says the same.

    4 fields
    • applied boolean required
    • model string required

      The SeedVR2 model that enlarged the images, or would have.

    • reason string

      Why the upscale did not run: capacity (every upscaler slot was busy for the queue time), account_limit (your requests already hold your share of upscaler slots), unavailable (no upscaler serves the size), upscaler_error (the upscaler failed twice).

      capacityaccount_limitunavailableupscaler_error
    • fallback string

      The fallback the request asked for and got.

      original
curl https://api.vultrinference.com/v1/images/edits \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "string"
  }'
Response · 200
{
    "created": 0,
    "data": [
        {
            "media_type": "image/png"
        }
    ],
    "size": "1024x1024",
    "output_format": "png",
    "background": "opaque",
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0,
        "input_tokens": 0,
        "output_tokens": 0,
        "cost": 0.02097152,
        "megapixels": 1.048576
    }
}