Ideogram 3.0 Character

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
Type	Image generation (consistent character)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Upload one character reference and generate the same character in new scenes; TURBO / BALANCED / QUALITY tiers priced per image.

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

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

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character reading a paper map on a rainy night train platform, glowing lamps, reflections on wet tiles, cinematic, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character reading a paper map on a rainy night train platform, glowing lamps, reflections on wet tiles, cinematic, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character reading a paper map on a rainy night train platform, glowing lamps, reflections on wet tiles, cinematic, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value ideogram-v3-character.

example ideogram-v3-character

input object required

Business parameters. Each request returns exactly one image.

prompt string required

Scene or change description, 1–5000 characters.

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

negative_prompt string optional

What to exclude, up to 5000 characters.

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 API

Upload one character reference and generate the same character in new scenes; TURBO / BALANCED / QUALITY tiers priced per image.

Request body

{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character reading a paper map on a rainy night train platform, glowing lamps, reflections on wet tiles, cinematic, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer the callback notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the image from output[].url.
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.