--- title: "Create image variation" method: POST path: "/v2/router/images/variations" tags: ["Images"] --- # Create image variation `POST /v2/router/images/variations` ## Request - Base URL: `https://my.orq.ai` - URL: `https://my.orq.ai/v2/router/images/variations` - Auth: HTTP bearer Create an Image Variation ## Request body `multipart/form-data` - object - `image` string, binary: The image to edit. Must be a supported image file. It should be a png, webp, or jpg file less than 50MB. - `model` string, required: The model to use for image generation. - `n` number, nullable: The number of images to generate. Must be between 1 and 10. - `response_format` 'url' | 'b64_json': The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. - `size` '256x256' | '512x512' | '1024x1024': The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`. - `user` string: A unique identifier representing your end-user, which can help to monitor and detect abuse. - `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 - `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 - `prompt` object: Prompt configuration for the request - `id` string, required: Unique identifier of the prompt to use - `version` 'latest', required: Version of the prompt to use (currently only "latest" supported) - `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 variation response from the API. - object - `created` number, required: The Unix timestamp (in seconds) of when the image was created. - `output_format` string: The output format of the image generation - `size` string: The size of the image generated - `quality` string: The quality of the image generated - `data` object[], required: The list of generated images. - `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: The token usage information for the image generation. - `total_tokens` number, required: The total number of tokens (images and text) used for the image generation. - `input_tokens` number, required: The number of tokens (images and text) in the input prompt. - `output_tokens` number, required: The number of output tokens generated by the model. - `input_tokens_details` object, required: The input tokens detailed information for the image generation. - `text_tokens` number, required: The number of text tokens in the input prompt. - `image_tokens` number, required: The number of image tokens in the input prompt. ## 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/variations/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)