Ideogram

Ideogram V3 Character

ideogram-v3-character

Lock the same character using a reference image, keep the face and clothing consistent across changes in scene, pose, and lighting, and carry forward Ideogram's strength in in-image text layout

ideogram-v3-character ideogram-v3-character/edit

Try ideogram-v3-character

Input

Expand Prompt

Showcases

View all showcases

Output

image

Fill in the parameters and run — results show up here.

Pricing

ideogram-v3-character per image

Specifications	Unit Price
TURBO	$0.090
BALANCED	$0.130
QUALITY	$0.180

Positioning Overview

ideogram-v3-character is an image generation model that uses a reference image as a visual anchor for a character: given a clear character photo as input, it preserves the person's facial features, hairstyle, clothing, and body proportions across multiple generations, while allowing prompts to change the scene, pose, lighting, and background. It is suited for developers and creative teams that need to reuse the same character across comic panels, social media series illustrations, and brand mascot extensions, and it carries on Ideogram's strength in in-image text layout.

Key Highlights

Lock a character with a single reference image — with just one JPEG, PNG, or WebP character image as input, the model uses it as a visual anchor to keep the character's appearance consistent.
Change the scene, not the person — while locking the character's appearance, prompts can substantially adjust the scene, pose, lighting, and background.
Reproducible parameter control — supports seed, negative prompt, and rendering speed presets, making it easy to produce stable outputs in batch generation and to tune detail and pacing as needed.

Capabilities

Reference-image character consistency: with a character reference image as input, the generated results preserve the face, hairstyle, clothing, and body proportions, making it suitable for series content that needs the same character reused across images.

Prompt-driven scene changes: while the character is locked, prompts up to 5,000 characters describe new scenes and poses, and negative prompts can exclude unwanted elements.

Reproducible generation: supports setting a random seed, making it easy to reproduce the same result during debugging or batch production and reducing selection costs.

Rendering preset options: offers three rendering speed presets — TURBO, BALANCED, and QUALITY — so developers can balance speed and quality according to output cadence and detail requirements.

Use Cases

Comic and storyboard artists: continuous frames of the same character — input a character model sheet plus a single-panel scene description to produce storyboard images with a coherent appearance, ready for layout and post-production workflows.
Social media operations: consistent character across series content — use a fixed character reference image to batch-generate illustrations on different themes, keeping the visual protagonist consistent across multiple installments.
Brand teams: mascot extensions across scenes — use mascot images to generate extension assets for different campaigns, seasons, or poster scenes for marketing material distribution.

Limitations and Model Selection Advice

Character consistency is not absolute: under complex scenes, exaggerated poses, and expression changes, the face and details may still show visible deviations. Reference image quality directly affects the results, so character images with a clear face, even lighting, and little occlusion are recommended. If you only need a single standalone creative image and do not need a fixed character, a general text-to-image model is more suitable. For commercial projects with extremely high requirements for character fidelity, it is advisable to validate consistency with a small number of samples before batch generation.

What's new

View changelog →

New model Added ideogram-v3-character and ideogram-v3-character/edit d… Oct 17, 2026

Frequently asked questions

View all FAQs →

What are the mask requirements?

The mask must match the source aspect ratio. Black areas are repainted and white areas are kept; a mask slightly larger than the silhouette looks more natural.
What size is the output?

The output keeps the source size; a 1024×768 source returns 1024×768.
Can I replace a person already in the image?

Yes. Paint that person into the mask and describe the new character's action; people and background outside the mask are kept.
What format should the mask be?

An image with the same aspect ratio as the source, with the area to repaint in black on white; the examples on this page use PNG masks.

Create a generation task

POST https://api.hiapi.ai/v1/tasks

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: ideogram-v3-character

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for ideogram-v3-character and route default — see the parameter table below.

seedintegerOptionalmin 0max 2147483647

Random seed for reproducible generation results; the value is an integer, and the same seed reproduces the same output.

stylestringOptionalDefault: "AUTO"

Style type, controls the overall style of the generated image; defaults to AUTO.

Options:AUTOREALISTICFICTION

promptstringRequiredminLength 1maxLength 5000

Scene prompt describing the referenced character, with a maximum length of 5000 characters.

expand_promptbooleanOptionalDefault: true

Whether to enable MagicPrompt to expand the prompt; defaults to true.

negative_promptstringOptionalmaxLength 5000

Negative prompt specifying content to exclude from the image, with a maximum length of 5000 characters.

rendering_speedstringOptionalDefault: "BALANCED"

Rendering speed tier: TURBO is the fastest and cheapest, QUALITY has the richest detail, and billing differs by tier; defaults to BALANCED.

Options:TURBOBALANCEDQUALITY

reference_image_urlsarrayRequiredminItems 1maxItems 1

Array of character reference images, must contain exactly one character reference image, supports JPEG, PNG, or WebP format, maximum 10 MB each.

Array [ string ]

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "style": "AUTO",
    "prompt": "…",
    "expand_prompt": true,
    "rendering_speed": "BALANCED",
    "reference_image_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "ideogram-v3-character",
    input: {
      "style": "AUTO",
      "prompt": "…",
      "expand_prompt": true,
      "rendering_speed": "BALANCED",
      "reference_image_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "ideogram-v3-character",
        "input": {
          "style": "AUTO",
          "prompt": "…",
          "expand_prompt": True,
          "rendering_speed": "BALANCED",
          "reference_image_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Get task detail

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Processing (non-terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Failed

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}