---
title: "Create image"
method: POST
path: "/v2/router/images/generations"
tags: ["Images"]
---

# Create image

`POST /v2/router/images/generations`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v2/router/images/generations`
- Auth: HTTP bearer

Create an Image

## Request body

- object
  - `prompt` string, required: A text description of the desired image(s).
  - `background` 'transparent' | 'opaque' | 'auto' | 'null', nullable: Allows to set transparency for the background of the generated image(s). This parameter is only supported for `openai/gpt-image-1`.
  - `model` string, required: The model to use for image generation. One of `openai/dall-e-2`, `openai/dall-e-3`, or `openai/gpt-image-1`.
  - `moderation` 'low' | 'auto' | 'null', nullable: Control the content-moderation level for images generated by `gpt-image-1`. Must be either `low` or `auto`.
  - `n` integer, nullable: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported.
  - `output_compression` integer, nullable: The compression level (0-100%) for the generated images. This parameter is only supported for `gpt-image-1` with the `webp` or `jpeg` output formats.
  - `output_format` 'png' | 'jpeg' | 'webp' | 'null', nullable: The format in which the generated images are returned. This parameter is only supported for `openai/gpt-image-1`.
  - `quality` 'auto' | 'high' | 'medium' | 'low' | 'hd' | 'standard' | 'null', nullable: The quality of the image that will be generated. `auto` will automatically select the best quality for the given model.
  - `response_format` 'url' | 'b64_json' | 'null', nullable: The format in which generated images are returned. Must be one of `url` or `b64_json`. This parameter isn't supported for `gpt-image-1` which will always return base64-encoded images.
  - `size` string, nullable: The size of the generated images. Must be one of the specified sizes for each model.
  - `style` 'vivid' | 'natural' | 'null', nullable: The style of the generated images. This parameter is only supported for `openai/dall-e-3`. Must be one of `vivid` or `natural`.
  - `metadata` object: Optional metadata for the request. This metadata will be stored in the trace and can be used for filtering.
  - `name` string: The name to display on the trace. If not specified, the default system name will be used.
  - `fallback_on_codes` integer[]: HTTP status codes that trigger fallback. Enter up to 20 unique integers from 400 to 599. When omitted or empty, defaults to [408, 429, 500, 502, 503, 504, 529].
  - `fallbacks` object[]: Array of fallback models to use if primary model fails
    - `model` string, required: Fallback model identifier
  - `retry` object: Retry configuration for the request
    - `count` number: Number of retry attempts (1-5)
    - `on_codes` number[]: HTTP status codes that trigger retry logic
  - `cache` object: Cache configuration for the request.
    - `ttl` number: Time to live for cached responses in seconds. Maximum 259200 seconds (3 days).
    - `type` 'exact_match', required
  - `load_balancer` object: Load balancer configuration for the request.
    - `type` 'weight_based', required
    - `models` object[], required
      - `model` string, required: Model identifier for load balancing
      - `weight` number: Weight assigned to this model for load balancing
  - `timeout` object: Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured.
    - `call_timeout` number, required: Timeout value in milliseconds
  - `plugins` PIIRedactionPlugin[]: Request-scoped transforms applied to the text exchanged with the model. Currently supports `pii_redaction`, which replaces PII with placeholders before the provider sees it and restores the original values in the response.
    - `id` 'pii_redaction', required: PII redaction plugin.
    - `language` string: Detector language. Accepts "auto" to detect the language per request; GET /v2/pii/capabilities lists the concrete languages and does not include "auto". Omitting the field defaults to "auto".
    - `regions` string[]: Region codes selecting whole regions of coverage (e.g. "nl", "gb"). Every entity type those regions cover is redacted, alongside the base catalog. ["all"] is exclusive, and leaving both this and entities empty also runs every region, so selecting nothing is the widest request rather than the narrowest. Combines with entities: the two selections are unioned, so entities adds types on top of the region coverage.
    - `entities` string[]: The entity types to redact. A named type is redacted even when it belongs to a region, so a region's types can be selected individually without naming the region. On its own this is a strict allowlist; alongside regions it adds to the region coverage. See GET /v2/pii/capabilities for valid types.
    - `entity_thresholds` object: Per-entity confidence cutoff overrides in [0,1]. Tunes confidence only and never changes which types are redacted, so every key must also appear in entities.
    - `threshold` number: Baseline confidence cutoff applied to every entity type without a per-entity override.
    - `on_failure` 'block' | 'passthrough': Behaviour when detection fails.
  - `orq` object
    - `name` string: The name to display on the trace. If not specified, the default system name will be used.
    - `retry` object: Retry configuration for the request
      - `count` number: Number of retry attempts (1-5)
      - `on_codes` number[]: HTTP status codes that trigger retry logic
    - `fallback_on_codes` integer[]: HTTP status codes that trigger fallback. Enter up to 20 unique integers from 400 to 599. When omitted or empty, defaults to [408, 429, 500, 502, 503, 504, 529].
    - `fallbacks` object[]: Array of fallback models to use if primary model fails
      - `model` string, required: Fallback model identifier
    - `identity` PublicIdentity: Information about the identity making the request. If the identity does not exist, it will be created automatically.
      - `id` string, required: Unique identifier for the contact
      - `display_name` string: Display name of the contact
      - `email` string, email: Email address of the contact
      - `metadata` object[]: A hash of key/value pairs containing any other data about the contact
      - `logo_url` string: URL to the contact's avatar or logo
      - `tags` string[]: A list of tags associated with the contact
    - `contact` PublicContact: @deprecated Use identity instead. Information about the contact making the request.
      - `id` string, required: Unique identifier for the contact
      - `display_name` string: Display name of the contact
      - `email` string, email: Email address of the contact
      - `metadata` object[]: A hash of key/value pairs containing any other data about the contact
      - `logo_url` string: URL to the contact's avatar or logo
      - `tags` string[]: A list of tags associated with the contact
    - `cache` object: Cache configuration for the request.
      - `ttl` number: Time to live for cached responses in seconds. Maximum 259200 seconds (3 days).
      - `type` 'exact_match', required
    - `load_balancer` object: Load balancer configuration for the request.
      - `type` 'weight_based', required
      - `models` object[], required
        - `model` string, required: Model identifier for load balancing
        - `weight` number: Weight assigned to this model for load balancing
    - `timeout` object: Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured.
      - `call_timeout` number, required: Timeout value in milliseconds

## Response `200`

Represents an image generation response from the API.

- object
  - `created` number, required: The Unix timestamp (in seconds) of when the image was created.
  - `data` object[], required: Represents the url or the content of an image generated.
    - `revised_prompt` string, nullable: The prompt that was used to generate the image, if there was any revision to the prompt.
    - `b64_json` string: The base64-encoded JSON of the generated image, if `response_format` is `b64_json`
    - `url` string: The url of the generated image, if `response_format` is `url` (default)
  - `usage` object
    - `input_tokens` number
    - `input_tokens_details` object, required
      - `image_tokens` number
      - `text_tokens` number
    - `output_tokens` number
    - `total_tokens` number

## Other responses

- `401`: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-23** `0b4e519a544f`: 5 info
  - added the new optional request property `fallback_on_codes`
  - added the new optional request property `orq/fallback_on_codes`
  - the `ttl` request property default value changed from `1800` to `3600`
  - the `ttl` request property default value changed from `1800` to `3600`
  - …1 more
- **2026-10-23** `732aed62833a`: 2 warning, 3 info
  - removed the request property `fallback_on_codes`
  - removed the request property `orq/fallback_on_codes`
  - the `ttl` request property default value changed from `3600` to `1800`
  - the `ttl` request property default value changed from `3600` to `1800`
  - …1 more
- **2026-10-22** `4f826b2c3a0e`: 5 info
  - added the new optional request property `fallback_on_codes`
  - added the new optional request property `orq/fallback_on_codes`
  - the `ttl` request property default value changed from `1800` to `3600`
  - the `ttl` request property default value changed from `1800` to `3600`
  - …1 more
- **2026-10-22** `8f0dc569f247`: 2 warning, 3 info
  - removed the request property `fallback_on_codes`
  - removed the request property `orq/fallback_on_codes`
  - the `ttl` request property default value changed from `3600` to `1800`
  - the `ttl` request property default value changed from `3600` to `1800`
  - …1 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/router/images/generations/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)