Skip to content
HiAPI Docs
HiAPI
Playground Get API Key
English
English 中文

Ideogram 3.0 Character Edit

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

Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name ideogram-v3-character/edit
Type Masked edit (consistent character)
Endpoint POST /v1/tasks
Pricing See HiAPI Pricing

Inpaint the referenced character into the masked area of a source image; three tiers priced per image.

Production guidance

Production guidance
  • For production, pass callback.url at the top level so HiAPI can notify your service when the task finishes.
  • Image URLs must be publicly reachable http/https addresses.

Request parameters

model string required

Fixed value ideogram-v3-character/edit.

example ideogram-v3-character/edit
input object required

Business parameters. Each request returns exactly one image.

prompt string required

Scene or change description, 1–5000 characters.

image_url string required

Public URL of the image to edit; must match the mask aspect ratio. Output size follows this image.

mask_url string required

Public URL of the mask: black areas are repainted, white areas kept; same aspect ratio as the source image.

reference_image_urls string[] required

Exactly one character reference image (JPEG/PNG/WebP, up to 10 MB).

rendering_speed enum optional

Rendering tier; each tier is priced per image.

default BALANCED enum: TURBOBALANCEDQUALITY
style enum optional

Style type.

default AUTO enum: AUTOREALISTICFICTION
expand_prompt boolean optional

Whether to expand the prompt with MagicPrompt.

default true
seed integer optional

Random seed, 0–2147483647.

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback
when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Ideogram 3.0 Character Edit API

Inpaint the referenced character into the masked area of a source image; three tiers priced per image.

Request body
{
  "model": "ideogram-v3-character/edit",
  "input": {
    "prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}

Getting the result

  1. The response returns a taskId immediately without waiting for generation to finish.
  2. In production, prefer the callback notification. For local debugging, poll GET /v1/tasks/:id.
  3. When status=success, download the image from output[].url.
  4. When status=fail, fix the request based on the returned error.

FAQ

Which rendering_speed tier should I use?

TURBO is fastest and cheapest for iteration, BALANCED is the default, QUALITY gives the finest detail for final output. Each tier is priced per image. View pricing

Can I send more than one character reference?

No. reference_image_urls must contain exactly one image; more returns a 400 error.

Can I choose the output aspect ratio?

Not separately. The output follows the character reference (generate) or the source image (edit). Upload a landscape character reference for landscape output.

Is Remix supported?

Remix is not available yet; only character generation and masked editing are supported.

How many images per request?

Exactly one image per request, billed per image. Submit several tasks in parallel for more.

How do I get the generated image?

The request returns a taskId immediately. When the task finishes, download the WebP image from output[].url. In production, pass callback.url at the top level of the request body.

Next steps