Generate consistent characters from a single reference image. Render the same character in many styles — realistic or fiction — insert them into existing photos with mask inpainting, and rely on Ideogram's signature text rendering for legible signs and typography.
Test this model instantly in the Console Playground — no code required
Copy usage instructions for Claude, ChatGPT, or other AI
curl -X POST "https://api.core.today/v1/predictions" \
-H "Content-Type: application/json" \
-H "X-API-Key: cdt_your_api_key" \
-d '{
"model": "ideogram-ai/ideogram-character",
"input": {
"prompt": "a close up photo of a woman in a fashion magazine photoshoot",
"resolution": "None",
"style_type": "Auto",
"aspect_ratio": "1:1",
"magic_prompt_option": "Auto",
"character_reference_image": "https://example.com/character.webp"
}
}'| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
prompt | string | Yes | - | Text prompt for image generation |
mask | string | No | - | A black and white image. Black pixels are inpainted, white pixels are preserved. Resized to match the image size |
seed | integer | No | - | Random seed. Set for reproducible generation |
image | string | No | - | An image file to use for inpainting. You must also use a mask |
resolution | string | No | None | Exact output resolution (e.g. 1024x1024) from ~69 supported presets between 512x1536 and 1536x512. Overrides aspect_ratio; ignored for inpainting None512x1536576x1408576x1472576x1536640x1344640x1408640x1472640x1536704x1152704x1216704x1280704x1344704x1408704x1472736x1312768x1088768x1216768x1280768x1344800x1280832x960832x1024832x1088832x1152832x1216832x1248864x1152896x960896x1024896x1088896x1120896x1152960x832960x896960x1024960x10881024x8321024x8961024x9601024x10241088x7681088x8321088x8961088x9601120x8961152x7041152x8321152x8641152x8961216x7041216x7681216x8321248x8321280x7041280x7681280x8001312x7361344x6401344x7041344x7681408x5761408x6401408x7041472x5761472x6401472x7041536x5121536x5761536x640 |
style_type | string | No | Auto | The character style type AutoFictionRealistic |
aspect_ratio | string | No | 1:1 | Aspect ratio. Ignored if a resolution or inpainting image is given 1:33:11:22:19:1616:910:1616:102:33:23:44:34:55:41:1 |
rendering_speed | string | No | Default | Rendering speed. Turbo is faster and cheaper (300 credits), Quality is higher quality and more expensive (600 credits), Default is balanced (450 credits) DefaultTurboQuality |
magic_prompt_option | string | No | Auto | Magic Prompt interprets and optimizes your prompt to maximize variety and quality. Also enables prompts in other languages AutoOnOff |
character_reference_image | string | Yes | - | An image to use as a character reference |
There are 3 ways to provide files for the maskimagecharacter_reference_image parameters:
Attach files directly to POST /v1/predictions/upload. No separate upload step needed.
curl -X POST "https://api.core.today/v1/predictions/upload" \
-H "X-API-Key: cdt_your_api_key" \
-F "model=ideogram-ai/ideogram-character" \
-F 'input={"prompt":"your prompt here"}' \
-F "file:mask=@your_file.png"Pass a publicly accessible URL directly. You can also use file_url from the Storage API.
{
"model": "ideogram-ai/ideogram-character",
"input": {
"prompt": "your prompt here",
"mask": "https://example.com/image.jpg"
}
}Common parameters used when calling POST /v1/predictions.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | - | Model identifier |
input | object | Yes | - | Object containing the model-specific parameters from the table above |
output_folder | string | No | - | Folder path for output files (max 256 chars, '..' not allowed) |
webhook_url | string | No | - | Webhook URL to call on completion |
is_public | boolean | No | false | If true, output files are also available via permanent public URLs |
The reference character rendered in a magazine photoshoot setting
curl -X POST "https://api.core.today/v1/predictions" \
-H "Content-Type: application/json" \
-H "X-API-Key: cdt_your_api_key" \
-d '{
"model": "ideogram-ai/ideogram-character",
"input": {
"prompt": "a close up photo of a woman in a fashion magazine photoshoot",
"resolution": "None",
"style_type": "Auto",
"aspect_ratio": "1:1",
"magic_prompt_option": "Auto",
"character_reference_image": "https://example.com/character.webp"
}
}'Turbo rendering cuts the price to 300 credits per image
curl -X POST "https://api.core.today/v1/predictions" \
-H "Content-Type: application/json" \
-H "X-API-Key: cdt_your_api_key" \
-d '{
"model": "ideogram-ai/ideogram-character",
"input": {
"prompt": "the character as a barista pouring latte art in a cozy cafe, warm lighting",
"rendering_speed": "Turbo",
"style_type": "Realistic",
"aspect_ratio": "3:4",
"character_reference_image": "https://example.com/character.webp"
}
}'POST /v1/predictions