Docs
Get an API key
API reference›Images

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: no model has a quality setting, and steps trades time for detail. 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).

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

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/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"
  }'
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
    }
}