Как пользоваться Ideogram 3.0 Character API? Запускаем первое изображение персонажа за 5 минут

TL;DR

• Ideogram 3.0 Character — модель генерации персонажа по референсу: загрузите 1 референсное изображение персонажа, напишите промпт сцены — и то же лицо и тот же костюм появятся в новой сцене.Откройте страницу модели и попробуйте онлайн; новым пользователям при регистрации начисляется 200 кредитов.
• Цена за изображение: TURBO $0.09, BALANCED $0.13, QUALITY $0.18; референсное изображение бесплатно, при ошибке плата не списывается (подробнее на странице цен).
• Вызов идёт через эндпоинт HiAPI /v1/tasks: отправьте задачу, получите taskId, затем запросите по нему результат, а после успеха скачайте изображение из output[0].url.

Что он умеет

• Согласованность персонажа: одно референсное изображение фиксирует персонажа — форма лица и одежда остаются неизменными, а сцену можно менять как угодно.
• И иллюстрация, и реализм: для style доступны AUTO / REALISTIC / FICTION — подходит и для фотографических персонажей, и для иллюстрированных.
• Формат следует за референсом: вертикальный референс даёт 3:4 (864×1152), горизонтальный — 16:9 (1328×752); параметр размера указывать не нужно.
• Парный эндпоинт редактирования: ideogram-v3-character/edit с помощью маски вписывает персонажа в заданную область существующего изображения, остальная картинка не меняется.

Ниже — реальный результат (референс — горизонтальное иллюстрированное изображение персонажа):

The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs

(По-русски: этот персонаж-исследователь идёт по ночному рынку, увешанному фонарями, держит бумажный стаканчик с горячей лапшой, по обе стороны — тёплые светящиеся прилавки, стиль иллюстрации из книжки с картинками, без текста, без вывесок.)

ideogram-v3-character, TURBO, 16:9, 1328×752, $0.09.

Сгенерировать с этим промптом →

Как выбрать между двумя эндпоинтами

	ideogram-v3-character	ideogram-v3-character/edit
Что делает	Генерирует нового персонажа в новой сцене с нуля	Вписывает персонажа в область маски на существующем изображении
Обязательные входные данные	prompt + 1 референсное изображение	prompt + исходное изображение + маска + 1 референсное изображение
Цена (TURBO / BALANCED / QUALITY)	$0.09 / $0.13 / $0.18	$0.09 / $0.13 / $0.18
Вывод	WebP, формат следует за референсом	WebP, размер следует за исходным изображением
Подходит для	Постеры, серии, сюжетные изображения сцен	Замена или добавление персонажа на готовом изображении

Соглашение о маске: чёрный = перерисовка, белый = сохранение; соотношение сторон маски и исходного изображения должно совпадать. Эндпоинт редактирования не принимает negative_prompt — при передаче вернётся 400.

Два пути к началу работы

Браузер, 3 шага: откройте страницу модели → загрузите референс персонажа, вставьте промпт → нажмите «Сгенерировать», TURBO — $0.09 за изображение.

API, 3 шага: POST /v1/tasks для отправки → получите taskId → GET /v1/tasks/<taskId> до статуса success, затем скачайте.

curl: первое изображение

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

Для эндпоинта редактирования замените model на ideogram-v3-character/edit, а в input добавьте image_url (исходное изображение) и mask_url (маска):

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/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"
  }
}'

taskId в ответе — это ваш идентификатор для запроса результата.

Python: отправка, опрос, скачивание

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "ideogram-v3-character",
    "input": {
        "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
        "reference_image_urls": ["https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"],
        "rendering_speed": "TURBO",
    },
}

# Отправка: с Idempotency-Key повтор при сетевой ошибке не создаст дублирующую задачу
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Опрос: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # временный адрес, скачайте и сохраните как можно скорее
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

Таблица параметров (ideogram-v3-character)

Поле	Обязательное	Значения	Описание
prompt	Да	1–5000 символов	Описывает сцену, в которой должен появиться персонаж, а не внешность персонажа (внешность берётся из референса)
reference_image_urls	Да	Ровно 1, JPEG / PNG / WebP, ≤10 MB	Референсное изображение персонажа; его формат определяет формат вывода
rendering_speed	Нет	TURBO / BALANCED / QUALITY, по умолчанию BALANCED	Определяет режим и цену
style	Нет	AUTO / REALISTIC / FICTION, по умолчанию AUTO	REALISTIC — ближе к фотографичности, FICTION — сохраняет иллюстративность
seed	Нет	Целое число 0–2147483647	С теми же параметрами и тем же seed изображение воспроизводится
expand_prompt	Нет	По умолчанию true	Автоматически расширяет промпт; чтобы строго следовать исходному тексту, передайте false
negative_prompt	Нет	≤5000 символов	Нежелательное содержимое

У эндпоинта редактирования помимо таблицы есть два обязательных поля image_url, mask_url, и он не поддерживает negative_prompt. Если в теле запроса есть поле вне таблицы, сразу вернётся 400 (additional properties ... not allowed).

Ошибки, которые вы встретите (исходный текст ответов)

Что вы сделали	Ответ
Не передали prompt	400 invalid input: prompt: missing required field "prompt"
Передали 2 референсных изображения	400 invalid input: reference_image_urls: maxItems: got 2, want 1
Опечатка в rendering_speed	400 invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
Передали неизвестное эндпоинту поле	400 invalid input: <root>: additional properties 'foo' not allowed
Передали negative_prompt в эндпоинт редактирования	400 invalid input: <root>: additional properties 'negative_prompt' not allowed
Недостаточно средств	402 insufficient account balance; top up and retry

Повторная отправка с тем же Idempotency-Key вернёт 409 (обрабатывается) или 422 (параметры не совпадают) — попробуйте с новым ключом.

Что учесть перед запуском в продакшен

• Callback: передайте на верхнем уровне тела запроса "callback": {"url": "https://..."} — при достижении задачей конечного состояния ваш сервис получит уведомление, и опрос не понадобится.
• Своевременно сохраняйте: output[0].url — временный адрес; получив его, сразу скачайте и сохраните в своё хранилище, не используйте его как постоянную ссылку.
• Явно указывайте режим и формат: передавайте rendering_speed явно каждый раз (если не передать, тарифицируется как BALANCED); формат вывода определяется референсом, поэтому для вертикальной сцены подготовьте вертикальный референс.
• Для пакетных задач — свой ключ идемпотентности для каждой: каждый запрос должен иметь уникальный Idempotency-Key; при сетевом повторе с тем же ключом попадёте в ту же задачу — не будет дублирующих задач и повторных списаний кредитов.

Частые вопросы

Можно ли использовать референс по URL?

Да. Подойдёт любой доступный http/https адрес, JPEG, PNG, WebP, максимум 10 MB.

Сколько референсных изображений можно передать?

Ровно 1 — это жёсткое правило; при передаче двух сразу будет ошибка 400. Чтобы сменить персонажа, смените референс.

Нужно ли передавать параметр размера?

Нет. Формат вывода следует за референсом: вертикальный референс даёт 864×1152, горизонтальный — 1328×752.

Способ вызова у двух эндпоинтов одинаковый?

Да. Меняются только model и поля внутри input.

Списывается ли плата при ошибке?

Нет, предварительно списанные кредиты полностью возвращаются после конечного состояния с ошибкой.

Далее: возьмите промпт про ночной рынок выше и попробуйте на странице модели, затем выбирайте промпты под сцену в сборнике промптов; цены по трём режимам и таблица бюджета — на странице цен.