# Ideogram Character - Core.Today AI API

> 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.

- **Provider**: Ideogram
- **Model ID**: ideogram-ai/ideogram-character
- **Category**: Image Generation
- **Credits**: 350 per image at Default rendering — Turbo 230, Default 350, Quality 470 credits
- **Speed**: Medium
- **Quality**: Ultra

## Features
- Consistent characters from just one reference image
- Auto, Fiction, or Realistic character style types
- Mask inpainting to add your character to an existing image
- Three rendering speeds (Turbo/Default/Quality) with tiered pricing
- Ideogram's signature accurate text rendering inside images

## Use Cases
- Character sheets showing the same character in varied poses and outfits
- Webtoon, comic, and storybook panels with a recurring protagonist
- Compositing a character into existing photos via inpainting
- Branded mascot imagery with legible embedded text
- Marketing visuals featuring a consistent spokesperson or persona

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **prompt**: string - Text prompt for image generation
- **character_reference_image**: string - An image to use as a character reference

### Optional
- **mask**: string - A black and white image. Black pixels are inpainted, white pixels are preserved. Resized to match the image size
- **seed**: integer - Random seed. Set for reproducible generation
- **image**: string - An image file to use for inpainting. You must also use a mask
- **resolution**: string (default: None) - Exact output resolution (e.g. 1024x1024) from ~69 supported presets between 512x1536 and 1536x512. Overrides aspect_ratio; ignored for inpainting
  Options: None, 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
- **style_type**: string (default: Auto) - The character style type
  Options: Auto, Fiction, Realistic
- **aspect_ratio**: string (default: 1:1) - Aspect ratio. Ignored if a resolution or inpainting image is given
  Options: 1:3, 3:1, 1:2, 2:1, 9:16, 16:9, 10:16, 16:10, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 1:1
- **rendering_speed**: string (default: Default) - Rendering speed. Turbo is faster and cheaper (300 credits), Quality is higher quality and more expensive (600 credits), Default is balanced (450 credits)
  Options: Default, Turbo, Quality
- **magic_prompt_option**: string (default: Auto) - Magic Prompt interprets and optimizes your prompt to maximize variety and quality. Also enables prompts in other languages
  Options: Auto, On, Off

## Examples

### Fashion Photoshoot from a Reference
The reference character rendered in a magazine photoshoot setting
```json
{
  "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"
  }
}
```

### Fast Character Iteration with Turbo
Turbo rendering cuts the price to 300 credits per image
```json
{
  "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"
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- Iterate with rendering_speed Turbo (300 credits) and switch to Quality (600 credits) only for final renders
- Use a clear, well-lit reference image of the character's face for the strongest consistency
- For inpainting, provide both image and mask — black mask pixels are replaced, white pixels are preserved
- Take advantage of Ideogram's text rendering: put signs, labels, or titles directly in the prompt in quotes
- resolution overrides aspect_ratio; leave it at None unless you need an exact pixel size
- Only use photos of real people as character references with the person's explicit consent

## Documentation
https://replicate.com/ideogram-ai/ideogram-character