Как использовать Ideogram 4.5 API? Генерация, редактирование и запрос задач

TL;DR

• Ideogram 4.5 — это серия text-to-image с приоритетом типографики: ideogram-v4.5/text-to-image генерирует постеры, логотипы-надписи, двуязычную упаковку и другие изображения с текстом, а ideogram-v4.5/image-to-image с помощью Precise Edit точно меняет текст, меняет стиль по референсному изображению и локально правит области по маске. Задачу можно выбрать на странице модели или вызвать интерфейс, как описано ниже.
• Цена за изображение и зависит от уровня качества: LOW $0.043, MEDIUM (по умолчанию) $0.086, HIGH $0.3145; уровень редактирования от VERY_LOW $0.0115; сейчас каждый запрос выдаёт 1 изображение, num_images может быть только 1. Подробности на странице цен.
• Вызов идёт через интерфейс HiAPI /v1/tasks: после отправки прочитайте data.taskId, затем запрашивайте data.status; после успеха скачайте изображение по адресу из data.output с type=image.

Что он умеет

• Упорядочивать текстовую иерархию изображения: заключайте нужный текст в кавычки и отдельно указывайте расположение заголовка, подзаголовка, даты и состава; после генерации проверяйте каждый символ.
• Исследовать композицию одиночными задачами: каждый запрос выдаёт 1 изображение; меняйте промпт или seed и отправляйте несколько задач отдельно, чтобы сравнить направления.
• Парный интерфейс редактирования: Precise Edit (edit_precision=high) подходит для небольших правок названия бренда, дат и т. п.; сверяйте сохраняемые области с исходным изображением.
• Референсные изображения + маска: до 4 референсных изображений (при наличии маски — 3); чёрный цвет маски = перерисовать, белый = сохранить.

Ниже реальный результат генерации (уровень LOW):

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

(По-китайски это значит: минималистичный современный брендовый постер дизайнерской конференции, по центру огромный жирный заголовок "DESIGN FORWARD", ниже мелкий подзаголовок "Typography Summit 2026", швейцарская сеточная вёрстка, тёплая оранжевая и глубоко-синяя палитра, геометрические фигуры, чёткие резкие буквы. Размер выбран landscape_16_9.)

ideogram-v4.5/text-to-image, LOW, landscape_16_9, 1280×720, $0.043.

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

Как выбрать один из двух интерфейсов

	ideogram-v4.5/text-to-image	ideogram-v4.5/image-to-image
Что делает	Генерирует изображение с вёрсткой по тексту	Редактирует существующее изображение
Обязательный ввод	prompt	image_url + prompt
Уровень качества	low / medium / high	very_low / low / medium / high
Особые параметры	num_images: 1, enable_prompt_expansion	edit_precision (Precise), reference_image_urls, mask_url
Размер	6 предустановок, по умолчанию square_hd	auto (по умолчанию) или 6 предустановок; при маске / Precise только auto
Подходит для	Новых макетов постеров, логотипов, упаковки, вывесок	Правки текста, смены палитры, сезонных версий, локальной перерисовки

Типичный конвейер: сгенерировать брендовый постер, затем с помощью Edit поменять название бренда или дату на клиентскую версию. Генерация LOW одного изображения $0.043 плюс одна правка текста Precise LOW $0.043 — комплект $0.086.

Два пути освоения

В браузере за 3 шага: откройте страницу модели → вставьте промпт, выберите уровень качества → нажмите «Сгенерировать».

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

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

Сначала задайте в терминале HIAPI_IDEMPOTENCY_KEY как уникальный идентификатор этой бизнес-операции; при повторной попытке того же запроса используйте то же значение. Пример явно задаёт LOW, горизонтальный размер и включает расширение промпта.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

Интерфейс редактирования: замените model на ideogram-v4.5/image-to-image, передайте исходное изображение и инструкцию. Ниже с помощью Precise Edit запрашивается изменение текста и сохранение вёрстки; результат всё равно нужно сверять с исходным изображением:

Для этой задачи редактирования задайте отдельный HIAPI_EDIT_IDEMPOTENCY_KEY, не используйте повторно ключ задачи генерации.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

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

Сначала установите requests, задайте HIAPI_API_KEY; для первой отправки также задайте HIAPI_IDEMPOTENCY_KEY, для каждой новой бизнес-операции используйте отдельное значение, а при повторных попытках одной и той же отправки не меняйте его. Программа сначала печатает ID задачи; после прерывания задайте HIAPI_TASK_ID, чтобы продолжить опрос и скачивание без повторной отправки генерации.

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

При сетевой ошибке во время опроса или скачивания сохраните напечатанный ID задачи и продолжите; скрипт не повторяет запрос создания автоматически. В примере верхняя граница опроса — 600 секунд, ожидание по 3 секунды; при скачивании сначала записывается файл .part, и только после завершения он переименовывается в正式ное имя.

Таблица параметров

Генерация ideogram-v4.5/text-to-image

Поле	Обязательно	Значения	Описание
prompt	Да	1–10000 символов	Четыре части: что за изображение → текст и палитра → вёрстка → текстура и ограничения
quality	Нет	low / medium / high, по умолчанию medium	Для массового поиска low, для повседневных задач medium, для финала с мелким текстом high
image_size	Нет	6 предустановок, по умолчанию square_hd	Пользовательские ширина и высота не поддерживаются
num_images	Нет	Фиксировано 1	Каждая задача выдаёт 1 изображение
enable_prompt_expansion	Нет	По умолчанию true	Расширение промпта; false отключает расширение, но проверять текст результата всё равно нужно
seed	Нет	Целое число	Воспроизведение с теми же параметрами

Редактирование ideogram-v4.5/image-to-image

Поле	Обязательно	Значения	Описание
image_url	Да	Адрес изображения	Исходное изображение
prompt	Да	1–10000 символов	Инструкция редактирования; ясно напишите, что менять, а что сохранить
edit_precision	Нет	regular / high, по умолчанию regular	high = Precise Edit, подходит для небольших правок текста
quality	Нет	very_low / low / medium / high, по умолчанию medium	very_low совместим только с regular
image_size	Нет	auto или 6 предустановок, по умолчанию auto	При маске или Precise только auto
reference_image_urls	Нет	До 4 изображений	При наличии маски — до 3
mask_url	Нет	Адрес изображения	Чёрный = перерисовать, белый = сохранить
num_images	Нет	Фиксировано 1	Каждая задача выдаёт 1 изображение
seed	Нет	Целое число

Если внутри input появляются поля, отсутствующие в таблице параметров этой модели, возвращается 400; верхнеуровневые model, callback и т. п. заполняются по формату интерфейса задач.

Ошибки, которые вы встретите

Код состояния	Значение	Что делать
400 INVALID_REQUEST	Некорректное тело запроса (нет prompt или image_url, неверное значение перечисления, поле вне таблицы)	Исправьте тело запроса по таблице параметров
402 INSUFFICIENT_QUOTA	Недостаточно средств (списание не происходит)	Пополните баланс и повторите
429 RATE_LIMITED	Сработало ограничение частоты	Снизьте частоту отправки
409 IDEMPOTENCY_KEY_PROCESSING	Задача с тем же ключом создаётся	Подождите и повторите с тем же ключом и тем же телом запроса
422 IDEMPOTENCY_KEY_MISMATCH	С тем же ключом передано другое тело запроса	Восстановите исходное тело запроса; новый ключ берите только для новой бизнес-задачи

Терминальный сбой задачи может содержать коды ошибок CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT и т. п. Сохраните taskId и сообщение об ошибке, сверяйте расчёты по финальному состоянию задачи и записям аккаунта; не принимайте неудачу опроса или скачивания за неудачу генерации.

Перед запуском в продакшен

• Callback: передайте на верхнем уровне тела запроса "callback": {"url": "https://..."}, и о терминальном состоянии придёт уведомление.
• Своевременно сохраняйте: ссылки на результаты в data.output имеют срок действия, после успеха сразу скачивайте.
• Одиночные задачи и идемпотентность: каждый раз выдаётся 1 изображение; при повторной попытке того же бизнес-запроса из-за тайм-аута используйте прежний ключ идемпотентности, новый ключ — только для новой бизнес-задачи.
• Мелкий китайский текст: сравнивайте уровни качества на реальном тексте; перед сдачей проверяйте посимвольно, medium или high не заменяют проверку.

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

Сколько изображений максимум генерируется за один запрос?

Сейчас генерация и редактирование каждый раз выдают 1 изображение, num_images может быть только 1. Для нескольких направлений отправляйте отдельные задачи.

Уровень качества по умолчанию — LOW?

Нет. По умолчанию MEDIUM, $0.086 за изображение; если нужно LOW по $0.043 за изображение, явно передайте quality: "low".

Какой режим использовать, чтобы поменять только название бренда и дату?

Можно выбрать Precise Edit, явно передав edit_precision: "high", quality: "low", image_size: "auto"; $0.043 за изображение.

Что означают чёрные и белые области маски?

Чёрные области перерисовываются, белые сохраняются. Маска должна быть того же размера, что и исходное изображение; при использовании маски выбирайте image_size = auto.

Нужно ли менять ключ идемпотентности после тайм-аута отправки?

При повторной попытке того же бизнес-запроса не меняйте ключ, используйте тот же Idempotency-Key и то же тело запроса; новый ключ — только когда действительно нужна новая задача.

Следующий шаг: возьмите промпт постера DESIGN FORWARD и сгенерируйте изображение на странице модели, затем одной инструкцией Precise замените заголовок на название вашего мероприятия. Сопутствующее чтение: три уровня цен и бюджет · 4 примера промптов для редактирования.

Если хотите сразу начать делать логотипы-надписи или постеры мероприятий, скопируйте эту подборку примеров промптов.