--- title: "Generate images of a consistent character with Ideogram 3.0" method: POST path: "/v2/images/generate/ideogram-v3-character" tags: ["images-generate"] --- # Generate images of a consistent character with Ideogram 3.0 `POST /v2/images/generate/ideogram-v3-character` Generate one or more images featuring a consistent character with Ideogram 3.0. Supply the character as a saved character (`character_reference_collection_id`), as `character_reference_asset_identifiers` references (an image already stored with Ideogram), or as raw `character_reference_images` bytes (multipart requests only, with an optional `character_reference_mask` marking where the character is in the reference). If more than one form is supplied, the collection wins over the identifiers, and the identifiers win over the bytes. Style references may be combined with the character on accounts with access; otherwise the combination returns a 400. Supply them as a saved style (`style_reference_collection_id`), as `style_reference_asset_identifiers` references, or as raw `style_reference_images` bytes, with the same precedence as the character forms. By default the request blocks until the images are ready and returns them in `data`. Set `async` to true to return immediately after the request is accepted, then poll for completion and results with `GET /v1/generations/{generation_id}` using the returned `generation_id`. ## Request body - GenerateImageIdeogramV3CharacterRequest — Supply the character as a saved character collection, as asset identifiers, or (multipart requests only) as raw image bytes. Exactly one character is supported per request; if more than one form is given, the collection is used over the identifiers, and the identifiers over the bytes. - `prompt` string, required — The prompt to generate images from. - `negative_prompt` string — Description of what to exclude from the images. Descriptions in the prompt take precedence over descriptions in the negative prompt. - `character_reference_collection_id` string — A saved character to feature, by its URL-safe base64 collection id. Takes priority over `character_reference_asset_identifiers` and `character_reference_images` if more than one is supplied. - `character_reference_collection_version_id` string — Optional URL-safe base64 version id pinning a specific version of the `character_reference_collection_id` collection. Ignored without it. - `character_reference_asset_identifiers` AssetIdentifier[] — An existing upload or generated image asset to use as the character reference, by reference. Takes priority over `character_reference_images` if both are supplied. - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required - `asset_id` string, required - `character_reference_images` string[] — An image to use as the character reference (max size 25MB), as raw bytes; only JPEG, PNG, and WEBP formats are supported. Multipart requests only; ignored if a character collection or asset identifier is also supplied. - `character_reference_mask` string, binary — Optional grayscale mask for the uploaded character reference image, the same size as that image, marking where the character is. Only JPEG, PNG, and WEBP formats are supported. Multipart requests only; applies only with `character_reference_images`. - `seed` integer — Random seed. Set for reproducible generation. - `resolution` '512x1536' | '576x1408' | '576x1472' | '576x1536' | '640x1344' | '640x1408' | '640x1472' | '640x1536' | '704x1152' | '704x1216' | '704x1280' | '704x1344' | '704x1408' | '704x1472' | '736x1312' | '768x1088' | '768x1216' | '768x1280' | '768x1344' | '800x1280' | '832x960' | '832x1024' | '832x1088' | '832x1152' | '832x1216' | '832x1248' | '864x1152' | '896x960' | '896x1024' | '896x1088' | '896x1120' | '896x1152' | '960x832' | '960x896' | '960x1024' | '960x1088' | '1024x832' | '1024x896' | '1024x960' | '1024x1024' | '1088x768' | '1088x832' | '1088x896' | '1088x960' | '1120x896' | '1152x704' | '1152x832' | '1152x864' | '1152x896' | '1216x704' | '1216x768' | '1216x832' | '1248x832' | '1280x704' | '1280x768' | '1280x800' | '1312x736' | '1344x640' | '1344x704' | '1344x768' | '1408x576' | '1408x640' | '1408x704' | '1472x576' | '1472x640' | '1472x704' | '1536x512' | '1536x576' | '1536x640' — The resolutions supported for Ideogram 3.0. - `aspect_ratio` '1x3' | '3x1' | '1x2' | '2x1' | '9x16' | '16x9' | '10x16' | '16x10' | '2x3' | '3x2' | '3x4' | '4x3' | '4x5' | '5x4' | '1x1' — The aspect ratio to use for image generation, which determines the image's resolution. Cannot be used in conjunction with resolution. Defaults to 1x1. - `rendering_speed` 'TURBO' | 'DEFAULT' | 'QUALITY' — The rendering speed to use. - `magic_prompt` 'AUTO' | 'ON' | 'OFF' — Determine if MagicPrompt should be used in generating the request or not. - `num_images` integer — The number of images to generate. - `style_type` 'AUTO' | 'REALISTIC' | 'FICTION' — The style type to generate the character with. Defaults to `AUTO`. - `style_reference_collection_id` string — A saved style to apply, by its URL-safe base64 collection id. Takes priority over `style_reference_asset_identifiers` and `style_reference_images` if more than one is supplied. - `style_reference_collection_version_id` string — Optional URL-safe base64 version id pinning a specific version of the `style_reference_collection_id` collection. Ignored without it. - `style_reference_asset_identifiers` AssetIdentifier[] — Existing upload or generated image assets to use as style references, by reference. Takes priority over `style_reference_images` if both are supplied. - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required - `asset_id` string, required - `style_reference_images` string[] — Images to use as style references (max 10, max size 25MB per image), as raw bytes; only JPEG, PNG, and WEBP formats are supported. Multipart requests only; ignored if a style reference collection or asset identifiers are also supplied. - `enable_copyright_detection` boolean, nullable — Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with `is_image_safe: false`. - `async` boolean — When false (the default), the request blocks until the images are ready and returns them in `data`. When true, the request returns as soon as it is accepted; poll for completion and results with `GET /v1/generations/{generation_id}` using the returned `generation_id`. ## Response `200` The generated images (synchronous requests), or an acknowledgement to poll with `GET /v1/generations/{generation_id}` (`async` requests). - GenerateImageIdeogramV3CharacterResponse — Response returned by `POST /v2/images/generate/ideogram-v3-character`. Synchronous requests (the default) include the generated images in `data`. Requests with `async` set to true omit `data`; poll for completion and results with `GET /v1/generations/{generation_id}` using the returned `generation_id`. The seed reports the value the request resolved to when the caller left it unset. - `generation_id` string, required — URL-safe base64 ID of the accepted generation. Accepted by the `GET /v1/generations/{generation_id}` polling endpoint. - `data` GeneratedImageObject[] — The generated images, in generation order. Present only for synchronous requests (`async` omitted or false). - `url` string, uri, nullable — The direct link to the generated image. Empty when the image did not pass safety checks. - `prompt` string, required — The final prompt the image was generated from. - `resolution` string, required — The resolution of the generated image, formatted as "WIDTHxHEIGHT". - `is_image_safe` boolean, required — Whether the image passed safety checks. If false, `url` is empty. - `seed` integer, required — Random seed. Set for reproducible generation. - `seed` integer, required — Random seed. Set for reproducible generation. ## Other responses - `400` — Invalid input provided. - `401` — Unauthorized. - `402` — Insufficient credits or quota. - `404` — A referenced asset or collection was not found. - `422` — The prompt did not pass safety checks. - `429` — Too many requests. - `500` — Internal server error. - `503` — The endpoint is temporarily unavailable. --- [API](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/revisions/898026c78d68/schema)