Ideogram

Ideogram V3 Character

ideogram-v3-character/edit

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/edit

Input

Showcases

View all showcases

Output

image

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

Pricing

ideogram-v3-character/edit per image

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

Overview

ideogram-v3-character/edit is an image model built for character-consistent editing: upload a source image and a mask, specify the region to repaint, and use exactly one character reference image as the visual anchor to rewrite part of the scene while preserving the face, hairstyle, clothing, and body shape. It is suited to developers who need to reuse the same person, mascot, or virtual avatar across a series of assets, especially in batch production scenarios where the character's appearance must stay consistent while the scene and copy can vary.

Core Highlights

Inpainting anchored to a character — the source image and mask define the edit region, and the reference image locks in the character's identity, so you can change the scene without changing the face.
Variable scenes, unchanged appearance — prompts can replace pose, lighting, and background, while the character's core features remain constrained by the reference image.
Reproducible batch production — a fixed random seed is supported, and together with style and rendering-speed tiers it helps reproduce a series of assets reliably.

Capabilities

Mask-directed editing: pass in a source image and a mask with the same aspect ratio, and only the area covered by the mask is repainted while the rest of the image stays unchanged — ideal for replacing backgrounds or local elements.

Single-reference character locking: exactly one reference image is allowed (JPEG, PNG, or WebP, max 10MB), and it constrains the character's appearance in the repainted result.

Prompt-controlled scenes: a prompt of up to 5000 characters describes the target scene, and prompt expansion can be enabled to automatically fill in descriptive details.

Style and speed tiers: styles include AUTO, REALISTIC, and FICTION; rendering speed is split into TURBO, BALANCED, and QUALITY, with the tier determining the level of detail.

Use Cases

Batch iteration of series character assets — operations and design teams use the same reference image with different masks to batch-produce multi-scene images of the same character for social media and campaign pages.
Local scene swaps for posters and promotional images — replace the background and lighting while keeping the main character, producing promotional images ready for delivery and materials with typeset text.
Character consistency in comics and storyboards — creators repaint poses and scenes in storyboard panels using a fixed reference image, producing continuous frames with a coherent appearance for storyboards.

Limitations and Model Selection Advice

Character consistency is not absolute; visible deviations can still occur in complex scenes or with extreme poses and expressions. The reference image needs a clear face, good lighting, and little occlusion, or results will degrade. The mask and source image must share the same aspect ratio, and only one reference image is accepted. If the task is a single standalone creative generation and does not require locking the same character, a text-to-image pipeline is more appropriate; the QUALITY detail tier and above lengthen generation time, so you need to trade off speed against quality.

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/edit

routestringOptional

Current fixed value: default

inputobjectRequired

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

seedintegerOptionalmin 0max 2147483647

An integer random seed used to make the generation results for the same prompt reproducible; the value takes the form of an integer.

stylestringOptionalDefault: "AUTO"

Specifies the style type used for generation; defaults to AUTO.

Options:AUTOREALISTICFICTION

promptstringRequiredminLength 1maxLength 5000

Describes the scene the reference character is in, i.e., the image content to be generated by this edit; maximum 5000 characters.

mask_urlstringRequiredminLength 1pattern ^https?://

Specifies the URL of the mask image for the area to be repainted; the mask must have the same aspect ratio as the source image.

image_urlstringRequiredminLength 1pattern ^https?://

URL of the source image to be edited; this image must have the same aspect ratio as the mask.

expand_promptbooleanOptionalDefault: true

Boolean switch that controls whether MagicPrompt is used to automatically expand the prompt; defaults to true.

rendering_speedstringOptionalDefault: "BALANCED"

Specifies the rendering speed tier: TURBO is the fastest and cheapest, QUALITY has the most detail, and different tiers have different prices; defaults to BALANCED.

Options:TURBOBALANCEDQUALITY

reference_image_urlsarrayRequiredminItems 1maxItems 1

Array of character reference images; exactly one character reference image is required, supporting JPEG, PNG, or WebP format, with a maximum of 10 MB per image.

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/edit",
  "input": {
    "style": "AUTO",
    "prompt": "…",
    "mask_url": "…",
    "image_url": "…",
    "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/edit",
    input: {
      "style": "AUTO",
      "prompt": "…",
      "mask_url": "…",
      "image_url": "…",
      "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/edit",
        "input": {
          "style": "AUTO",
          "prompt": "…",
          "mask_url": "…",
          "image_url": "…",
          "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"
    }
  }
}