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

# Create image

`POST /v2/router/images/generations`

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.
  - `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` union[] — 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.
    - union
      - PIIRedactionPluginAuto
        - `id` 'pii_redaction', required — Plugin discriminator. Must be `pii_redaction`.
        - `on_failure` 'block' | 'passthrough' — Behavior when redaction is unavailable. `block` (default) fails the request; `passthrough` sends the original text.
        - `threshold` number — Detector confidence cutoff in [0,1].
        - `entities` string[] — Entity types to redact when no detector language is configured. Omit to redact every detected type.
      - PIIRedactionPluginEn
        - `id` 'pii_redaction', required — Plugin discriminator. Must be `pii_redaction`.
        - `on_failure` 'block' | 'passthrough' — Behavior when redaction is unavailable. `block` (default) fails the request; `passthrough` sends the original text.
        - `threshold` number — Detector confidence cutoff in [0,1].
        - `language` 'en', required — Detector language.
        - `entities` string[] — English entity types to redact. Omit to redact every type detected for the language.
      - PIIRedactionPluginNl
        - `id` 'pii_redaction', required — Plugin discriminator. Must be `pii_redaction`.
        - `on_failure` 'block' | 'passthrough' — Behavior when redaction is unavailable. `block` (default) fails the request; `passthrough` sends the original text.
        - `threshold` number — Detector confidence cutoff in [0,1].
        - `language` 'nl', required — Detector language.
        - `entities` string[] — Dutch entity types to redact. Omit to redact every type detected for the language.
  - `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
    - `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 — Array of models with weights for load balancing requests
      - `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

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/deb8d376faee/schema)