Create Image

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

Creates one or more images from a prompt, in OpenAI's shape (images.generate() in OpenAI's SDKs). The default model is z-image-turbo. GET /v1/images/models lists the image models currently served with what each accepts.

The answer is a link (url) unless response_format is b64_json; POST /v1/images answers base64 by default. Every error is OpenRouter's envelope.

quality (auto, low, medium, high, standard, hd) is accepted and ignored on a model without quality tiers, where steps trades time for detail. On minimax-h3 it selects a tier: low or auto Turbo (4 steps), medium or standard 20 steps at 1.5 times the megapixels billed, high or hd 40 steps at 3 times, ultra 50 steps at 5 times, and a raw steps bills the tier whose step range holds it; GET /v1/images/models/{author}/{slug}/endpoints lists them as quality_tiers. moderation and style are not supported and are a 400 naming the field. stream: true answers one image_generation.completed event and [DONE] (partial_images above 0 is a 400). output_format (png, jpeg, webp) and output_compression are passed to the engine. Model-specific settings are steps (or num_inference_steps), guidance_scale and negative_prompt, also under provider.options (see POST /v1/images).

images or input_references make the request an edit with a model that has reference editing, answered as POST /v1/images/edits answers it (minimax-h3's reference stills included).

For reproducible output, send an integer seed together with steps and guidance_scale, and keep every other field the same between requests.

Body

application/json

One request shape for POST /v1/images, /v1/images/generations and (as JSON) /v1/images/edits: OpenRouter's image request, OpenAI's image request and the parameter names each model declares in GET /v1/images/models are all accepted on all three routes.

Every field is read, accepted and ignored by design (user, session_id, trace, and provider's routing fields such as order and sort), quality (auto, low, medium, high, standard, hd; any other value is a 400; on minimax-h3 it selects a quality tier, and ultra is one more: low Turbo, medium 20 steps billed 1.5x, high or hd 40 steps billed 3x, ultra 50 steps billed 5x), or refused with a 400 naming it: moderation, style, input_fidelity, lora, loras, partial_images above 0, and any field the model does not declare. Limits below are z-image-turbo's; each model's own are in GET /v1/images/models.

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.

Responses

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/generations \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "Studio photograph of a red ceramic teapot beside a blue cup on a wooden table.",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

import os
import requests

response = requests.post(
    "https://api.vultrinference.com/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['VULTR_INFERENCE_API_KEY']}"},
    json={
        "model": "z-image-turbo",
        "prompt": "Studio photograph of a red ceramic teapot beside a blue cup on a wooden table.",
        "n": 1,
        "size": "1024x1024",
        "response_format": "b64_json",
    },
)
print(response.json())

const response = await fetch("https://api.vultrinference.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VULTR_INFERENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "z-image-turbo",
    "prompt": "Studio photograph of a red ceramic teapot beside a blue cup on a wooden table.",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }),
});
console.log(await response.json());

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