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.

Billing is the output megapixels only, so an edit with any number of references bills the same as a generation of the same size. 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. Send them as image[] (what the OpenAI SDKs do); PHP keeps only the last of several parts named plainly image.

  • 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

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. When omitted, the model's default is used: 0 for z-image-turbo, which is also the upstream recommendation for Turbo models.

    0 turns guidance off. Values above 0 turn it on, which enables negative_prompt and roughly doubles the model work per step. Higher values are not a quality setting for z-image-turbo.

    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. 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.

  • 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

6 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.

  • 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.

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
    }
}