Ideogram Character API

Ideogram's character-consistency model (Jul 2025) that keeps the same person or character recognizable across scenes, poses, and styles, all from a single reference image.

Integrate Ideogram Character with a single API call — one key, one unified endpoint, and shared billing across every model on Apiframe.

Get API Key Use in Apiframe Studio View Ideogram Character API Docs

model: "ideogram-character"

What's special about Ideogram Character

Consistency from a single image

It generates unlimited variations of a character from just one reference photo, skipping the traditional LoRA training that needs many images and setup time.

Automatic identity mapping

It detects facial features and hair to build a core identity map, then preserves that identity across new environments, poses, and contexts.

Works with real and fictional subjects

The same approach handles real people and invented characters, and can move them between scenes and art styles.

Three style modes

Auto picks intelligently, Realistic targets photographic output for portraits and fashion, and Fiction leans into stylized and artistic looks.

Tools for placement and editing

A character mask controls hair, clothing, and accessories, while Magic Fill drops the character into an existing scene, and Remix and Face Swap extend the workflow.

Flexible and easy to access

It supports many aspect ratios and resolutions and runs on the web, on iOS, and via the Character API, with a free tier to start.

Prompts to try with Ideogram Character

Example prompts you can run through the Ideogram Character API on Apiframe.

Place this character in a cozy coffee shop reading a book, natural window light, keep their face and hair.

Show this character as an astronaut floating in space, keep their identity, cinematic lighting.

Generate this character in three outfits, a business suit, casual weekend wear, and athletic gear, same face.

Turn this character into an anime-style illustration, keeping their recognizable features.

A children's book scene of this character planting a garden, soft watercolor style.

A professional headshot of this person against a neutral grey background, realistic style.

Overview

Endpoint: POST /v2/images/generate
Model ID: ideogram-character
Params key: ideogramParams
Modality: Image
Provider: Ideogram
Avg. completion: ~25s

Capabilities

Aspect ratios1:1, 3:4, 4:3, 9:16, 16:9

Image inputSupported

Avg. time~25s

Quick start

Send a single POST /v2/images/generate request with your API key to generate with Ideogram Character. The call returns a jobId you can poll or receive via webhook.

curl -X POST https://api.apiframe.ai/v2/images/generate \
  -H "X-API-Key: afk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "a sleek silver sports car on a coastal highway at sunset, hyper-realistic",
        "model": "ideogram-character",
        "ideogramParams": {
            "character_reference_image": "https://example.com/input.jpg",
            "style_type": "AUTO",
            "magic_prompt_option": "Auto",
            "negative_prompt": "What you do NOT want to see…"
        }
    }'

import requests

response = requests.post(
    "https://api.apiframe.ai/v2/images/generate",
    headers={
        "X-API-Key": "afk_your_api_key_here",
        "Content-Type": "application/json",
    },
    json={
        "prompt": "a sleek silver sports car on a coastal highway at sunset, hyper-realistic",
        "model": "ideogram-character",
        "ideogramParams": {
            "character_reference_image": "https://example.com/input.jpg",
            "style_type": "AUTO",
            "magic_prompt_option": "Auto",
            "negative_prompt": "What you do NOT want to see…"
        }
    },
)
print(response.json())  # { "jobId": "...", "status": "QUEUED" }

const response = await fetch("https://api.apiframe.ai/v2/images/generate", {
  method: "POST",
  headers: {
    "X-API-Key": "afk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prompt": "a sleek silver sports car on a coastal highway at sunset, hyper-realistic",
    "model": "ideogram-character",
    "ideogramParams": {
      "character_reference_image": "https://example.com/input.jpg",
      "style_type": "AUTO",
      "magic_prompt_option": "Auto",
      "negative_prompt": "What you do NOT want to see…"
    }
  }),
});
const { jobId } = await response.json();
console.log(jobId);

Response & job lifecycle

Generation is asynchronous. A successful submission returns 202 Accepted with a jobId. Poll GET /v2/jobs/{id} (or supply a webhook_url) until the status is COMPLETED; the result field then holds the output URL(s).

1. Submission response (202)

{
  "jobId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "status": "QUEUED"
}

2. Poll for the result

curl https://api.apiframe.ai/v2/jobs/JOB_ID \
  -H "X-API-Key: afk_your_api_key_here"

import requests, time

while True:
    job = requests.get(
        "https://api.apiframe.ai/v2/jobs/JOB_ID",
        headers={"X-API-Key": "afk_your_api_key_here"},
    ).json()
    if job["status"] in ("COMPLETED", "FAILED"):
        break
    time.sleep(2)
print(job["result"])

let job;
do {
  await new Promise((r) => setTimeout(r, 2000));
  job = await fetch("https://api.apiframe.ai/v2/jobs/JOB_ID", {
    headers: { "X-API-Key": "afk_your_api_key_here" },
  }).then((r) => r.json());
} while (job.status !== "COMPLETED" && job.status !== "FAILED");
console.log(job.result);

Input schema

Request parameters accepted by the Ideogram Character endpoint. Model-specific options are nested under the params object shown below.

Parameter	Type	Required	Default	Allowed / range	Description
prompt	string	required	—	—	Text description of what to generate.
model	string	required	"ideogram-character"	"ideogram-character"	The model identifier for this endpoint.
ideogramParams.character_reference_image	string (URL)	optional	—	—	Required — the character to keep consistent across generations.
ideogramParams.style_type	string	optional	"AUTO"	"AUTO", "GENERAL", "REALISTIC", "DESIGN"	Style
ideogramParams.magic_prompt_option	string	optional	"Auto"	"Auto", "On", "Off"	Let Ideogram rewrite your prompt for better results.
ideogramParams.negative_prompt	string	optional	—	—	Negative prompt
ideogramParams.rendering_speed	string	optional	"default"	"default", "turbo", "quality"	Rendering speed
ideogramParams.seed	number	optional	—	step 1	Reuse a number to reproduce the same result.

Frequently Asked Questions

Common questions about the Ideogram Character API.

What is Ideogram Character?

A specialized model that keeps a character visually consistent across many generated images, using a single reference photo.

How many reference images do you need?

Just one. It avoids the multi-image LoRA training that older consistency methods required.

Does it work with fictional characters?

Yes. It handles both real people and invented characters across scenes and styles.

What gives the best results?

A clear, high-quality reference with visible facial features, plus a prompt that states both what to change and what to keep.

Is it free?

It is free to use on ideogram.ai and the iOS app, with Plus and Pro tiers adding unlimited generations, private creation, and more credits.

Where can you access it?

Through Apiframe, as well as ideogram.ai, the iOS app, and the Character API.

Still have questions?

Contact Support Join Discord

Start building with the Ideogram Character API

Get your API key and integrate Ideogram Character in minutes — Pay-as-you-go.

Free credits to start

One API for every model

Webhooks, SDKs & idempotency

No provider account required

Get Started Free Read Documentation

Questions? Join our Discord or contact sales.