Как использовать ideogram-v4 через hiapi API: curl, Python и рабочий запрос

Репутация моделей Ideogram построена на том, что большинство моделей изображений до сих пор не умеют делать: типографика. Заголовки на постерах написаны правильно, буквы на логотипах чёткие, текст на вывесках не превращается в нечитаемую кашу. ideogram-v4, как и все остальные модели изображений и видео, доступна на hiapi через единый API задач, и это руководство полностью проведёт вас через такой запрос: версия на curl, которую можно скопировать и вставить, полный скрипт на Python, параметры, которые действительно проверяются схемой (они не совпадают с теми, что предоставляет нативный API Ideogram), и ошибки, с которыми вы столкнётесь на практике.

Что вы создаёте и что нужно подготовить

Цель: отправить текстовый промпт в POST /v1/tasks, дождаться завершения задачи и скачать изображение, текст на котором отрисован так, как вы указали.

Вам нужно только одно: API-ключ hiapi — создайте его в консоли. Он используется в каждом запросе как Bearer token. Бесплатного неавторизованного уровня нет; все вызовы ниже предполагают использование Authorization: Bearer sk-....

Как и все модели на hiapi, ideogram-v4 работает асинхронно: вы создаёте задачу, сразу получаете taskId, а затем либо опрашиваете результат, либо получаете callback. Синхронного режима «ждать 40 секунд в одном HTTP-соединении» не существует — и для генерации изображений он вам и не нужен.

Минимальный запрос: curl

Создание задачи:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4",
    "input": {
      "prompt": "Постер джазового фестиваля в стиле винтажного ар-деко. Заголовок \"MIDNIGHT & BRASS\" жирным золотым шрифтом на фоне тёмно-синего цвета, подзаголовок \"Live at the Riverside, Fridays\" тонким шрифтом без засечек под ним.",
      "rendering_speed": "BALANCED",
      "aspect_ratio": "3:4"
    }
  }'

Ответ возвращается сразу, идентификатор задачи находится в data.taskId (в формате tk-hiapi-...). Опрашивайте его:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-XXXXXXXX \
  -H "Authorization: Bearer $HIAPI_KEY"

Во время генерации изображения data.status последовательно проходит через queued и handling. При достижении конечного состояния он становится success или fail. В случае успеха URL изображения находится в data.output[0].url:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-XXXXXXXX",
    "status": "success",
    "output": [
      { "url": "https://.../result.png?...expireAt=..." }
    ]
  }
}

Об этом URL нужно помнить одно: он подписанный и истекает (expireAt). Скачайте байты сразу после успешного завершения задачи и сохраните их в своём хранилище. Никогда не сохраняйте горячие ссылки в базе данных.

Параметры, которые ideogram-v4 действительно принимает

Это та часть, к которой стоит отнестись точно. Если вы читали документацию самого Ideogram, то знаете, что его нативный API предоставляет стилевые пресеты, переключатели магических промптов, негативные промпты и количество изображений в пакете. Схема задачи ideogram-v4 в hiapi намеренно сделана меньше, и валидатор отклоняет всё, что выходит за её пределы. Вот полный набор, подтверждённый живым API:

Поле	Обязательное	Тип / значения
prompt	Да	string
rendering_speed	Да	"TURBO", "BALANCED", "QUALITY"
aspect_ratio	Нет	"1:1", "16:9", "4:3", "9:16", "3:4"
seed	Нет	целое число

Оба обязательных поля проходят строгую проверку. Отправка пустого input выдаст:

invalid input: prompt: missing required field "prompt";
rendering_speed: missing required field "rendering_speed"

При опечатке в значении перечисления ошибка сообщит допустимые значения:

invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'

А всё, чего нет в таблице выше из нативного интерфейса Ideogram, будет отклонено как неизвестное свойство — style_type, magic_prompt, negative_prompt, num_images, size и входные изображения вернут 400, например:

invalid input: <root>: additional properties 'style_type' not allowed

Практические последствия:

• Управление типографикой полностью зависит от промпта. Поместите точный текст, который хотите отрисовать, в промпт в двойных кавычках и опишите шрифт («жирный шрифт в стиле ар-деко», «тонкий геометрический шрифт без засечек», «рукописный вывесочный шрифт»). Именно так получают эффекты постеров, логотипов и вывесок, которыми славится Ideogram — отдельного стилевого параметра, на который можно положиться, нет.
• Одно изображение на задачу. Нет n или num_images. Если вам нужно четыре варианта, отправьте четыре задачи и опрашивайте каждый taskId отдельно.
• seed — ваша ручка воспроизводимости. Одинаковый промпт + одинаковый seed дают стабильную отправную точку для итераций над формулировкой.
• Только текст-в-изображение. Схема модели не принимает референсные изображения. Если вашему рабочему процессу нужно изображение-в-изображение, выберите модель, которая это поддерживает — см. как вызывать несколько моделей изображений с одним API-ключом, чтобы переключать модели без изменения кода интеграции.

О rendering_speed: TURBO — быстрый уровень, подходит для черновиков при итерации формулировок промпта; QUALITY — медленный, тщательный уровень для финального рендера; BALANCED — разумное значение по умолчанию. Оплата взимается за использование по каждому изображению — актуальные цены смотрите на странице тарифов.

Полный скрипт на Python

Тот же процесс — создание, опрос, скачивание — с таймаутом и обработкой конечных состояний. Единственная зависимость — requests (pip install requests).

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task(prompt: str, rendering_speed: str = "BALANCED",
                aspect_ratio: str = "1:1", seed: int | None = None) -> str:
    input_obj = {
        "prompt": prompt,
        "rendering_speed": rendering_speed,
        "aspect_ratio": aspect_ratio,
    }
    if seed is not None:
        input_obj["seed"] = seed
    resp = requests.post(API_BASE, headers=HEADERS,
                         json={"model": "ideogram-v4", "input": input_obj},
                         timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: HTTP {resp.status_code} {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt=('Создай минималистичный логотип для кофейного бренда под названием "Driftwood", '
                'слово Driftwood в виде словесного знака тёплым шрифтом с засечками, монохромный, '
                'на кремовом фоне'),
        rendering_speed="QUALITY",
        aspect_ratio="1:1",
        seed=42,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    png = requests.get(url, timeout=120).content   # подписанный URL истекает - скачивайте сразу
    with open("driftwood-logo.png", "wb") as f:
        f.write(png)
    print("saved driftwood-logo.png,", len(png), "bytes")

Замечания для продакшена: callback, идемпотентность и ошибки

Опрос против callback. Для интерактивных инструментов, генерирующих одно изображение, опрос каждые несколько секунд проще и вполне достаточен. Для пакетных или серверных нагрузок добавьте callback в запрос создания, чтобы hiapi отправлял вам конечный результат через POST:

{
  "model": "ideogram-v4",
  "input": { "prompt": "...", "rendering_speed": "BALANCED" },
  "callback": { "url": "https://your.domain.example/hiapi/hook", "when": "final" }
}

Два ограничения, проверяемые при создании: URL должен быть https:// и доступен из публичной сети, а when принимает только "final" — если вы попробуете другое значение, API просто вернёт invalid callback.when: only 'final' is supported. Сделайте обработчик идемпотентным по taskId, быстро возвращайте 2xx и сохраняйте опрос как запасной вариант для задач, чьи callback так и не пришли. Если callback не пришёл, сначала проверьте по почему ваш callback задачи hiapi не срабатывает, а потом вините очередь.

Идемпотентность. Создание задачи не идемпотентно — каждый успешный POST /v1/tasks создаёт новую задачу и новое списание. Сразу после получения taskId сохраните его в связке с вашим собственным id задачи, и при любых повторных попытках опрашивайте сохранённый taskId, а не отправляйте запрос заново.

Ошибки, которые вы реально увидите.

• 401 с "code": "permission_denied" — ключ недействителен или не может использовать эту модель. Сообщение прямо говорит: «This API key cannot use the selected model. Please check permissions or use another key.» Исправьте в консоли, не повторяйте попытку.
• 400 с "error_code": "INVALID_REQUEST" — ошибка валидации. В message указано конкретное поле и допустимые значения; прочитайте его и исправьте тело запроса. Повтор с тем же телом запроса будет терпеть неудачу всегда.
• 404 "task not found" на GET /v1/tasks/{id} — неверный id задачи или задача создана с другим ключом.
• Статус fail у уже принятой задачи — проверьте data.error.code / data.error.message в ответе на опрос. Их можно безопасно повторить как новую задачу.

Связанные материалы

• Страница модели ideogram-v4 — возможности и текущие тарифные уровни
• Почему ваш callback задачи hiapi не срабатывает — чек-лист отладки callback
• Как вызывать несколько моделей изображений с одним API-ключом — тот же API задач, разные строки model
• Самый дешёвый API генерации изображений — как сравнивать реальную стоимость одного изображения у разных моделей
• Документация API — полный справочник по POST /v1/tasks / GET /v1/tasks/{id}

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

Поддерживает ли ideogram-v4 на hiapi изображение-в-изображение или референсные изображения? Нет. Схема задачи этой модели принимает только prompt, rendering_speed, aspect_ratio и seed — любое поле входного изображения будет отклонено с 400. Если вам нужно редактировать или перерисовывать существующее изображение, используйте модель, поддерживающую изображение-в-изображение (например, серию gpt-image-2).

Какой rendering_speed мне использовать? Пока вы оптимизируете промпт и точную формулировку текста, итерируйте с TURBO, а затем перерендерите победивший вариант с QUALITY и тем же seed. Если вы рендерите только один раз, BALANCED — неплохое значение по умолчанию.

Как заставить ideogram-v4 отрисовать точный текст? Поместите буквальный текст в промпт в двойных кавычках и опишите вокруг него типографику: Заголовок "SUMMER SALE" жирным сжатым шрифтом без засечек. Короткие строки отрисовываются надёжнее, чем целые предложения; если длинная строка выходит искажённой, разбейте её на заголовок и подзаголовок.

Можно ли генерировать несколько изображений в одном запросе? Нет — одна задача создаёт одно изображение. Вместо этого отправьте несколько задач параллельно; у каждой будет свой taskId, и они встанут в очередь независимо.

Почему мой ключ работает с другими моделями, но я получаю 401 permission_denied? Доступ к моделям настраивается для каждого ключа. Проверьте права ключа на модели в консоли или создайте новый ключ с доступом к ideogram-v4.

Сколько действует URL результата? Это подписанный URL с отметкой expireAt. Относитесь к нему как к сроку в минутах, а не в днях: скачивайте изображение сразу, как только задача достигает success, и сохраняйте файл сами.

Какие соотношения сторон доступны? Ровно пять: 1:1, 16:9, 4:3, 9:16 и 3:4. Свободного параметра size нет — запрос с size будет отклонён как неизвестное свойство.