Как использовать ideogram-v3-character через HiAPI API: руководство по curl + Python

Что такое ideogram-v3-character и когда его использовать

ideogram-v3-character — это модель генерации изображений на HiAPI, ориентированная на согласованность персонажа. Она не рассматривает каждую генерацию как независимый промпт, а позволяет передать референсное изображение персонажа, чтобы последующие рендеры сохраняли те же черты лица, одежду и общую идентичность.

Использовать её стоит, когда кто и что делает одинаково важны:

• Раскадровки и комиксы: один и тот же персонаж появляется в нескольких кадрах.
• Вариации игровых ассетов: генерация разных поз, выражений лиц или одежды для одного главного персонажа.
• Брендовые маскоты: образ должен оставаться неизменным во множестве разных сцен и фонов.
• Итеративное художественное руководство: доработка персонажа за несколько раундов правок без потери сходства.

Если вам нужна разовая иллюстрация и не важно совпадение с предыдущими изображениями, универсальная модель текст-в-изображение проще. Дополнительная структура, которую даёт референсное изображение, — именно то, ради чего стоит добавлять поля в запрос к ideogram-v3-character.

Модель, как и другие, доступна через единый эндпоинт генерации изображений HiAPI, поэтому структура запроса покажется знакомой: вы отправляете JSON-нагрузку, получаете ссылку на задачу асинхронного задания и опрашиваете её до готовности результата. В этом руководстве основное внимание уделено тому, как правильно пройти этот процесс.

Перед отправкой запроса: настройка и аутентификация

Перед первым вызовом нужно подготовить лишь несколько вещей.

1. API-ключ

Создайте API-ключ в панели управления аккаунта HiAPI. Относитесь к нему как к секрету — он авторизует каждый ваш запрос и учитывается в биллинге аккаунта.

2. Работа с учётными данными через переменные окружения

Никогда не встраивайте ключ в исходные файлы и не коммитьте его в git. Вместо этого используйте переменные окружения:

export HIAPI_API_KEY="your_api_key_here"

В Python его можно прочитать так:

import os
api_key = os.environ["HIAPI_API_KEY"]

Если вы используете файл .env при локальной разработке, добавьте его в .gitignore прежде чем делать что-либо ещё.

3. URL референсного изображения

Поскольку согласованность персонажа зависит от референса, подготовьте изображение, которое можно передать по URL. Убедитесь, что URL общедоступен или иначе доступен для API — приватные ссылки за аутентификацией не подойдут. Лучше всего работают квадратные или вертикальные изображения с чётко видимым лицом персонажа.

4. Способ выполнения HTTP-запросов

Достаточно любого из двух: curl в командной строке или среда Python с установленным requests. Примеры ниже предполагают, что у вас есть один из них.

Подготовив эти четыре вещи, вы можете отправить первый запрос.

Разбор рабочего curl-запроса строка за строкой

Ниже приведён полный запрос на отправку задания ideogram-v3-character в HiAPI. Замените заполнители своими значениями.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-character",
    "prompt": "дружелюбный робот-механик стоит в залитой солнцем мастерской, держит гаечный ключ, ракурс три четверти",
    "reference_images": [
      "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1
  }'

Что делает каждая часть

• POST /v1/images/generations — единый эндпоинт генерации изображений HiAPI. Все модели используют этот же путь.
• Authorization: Bearer $HIAPI_API_KEY — аутентифицирует вызов. Оболочка подставит переменную окружения, которую вы установили ранее.
• Content-Type: application/json — вы отправляете JSON-тело, поэтому его нужно объявить.
• model — выбирает ideogram-v3-character. Без него запрос не знает, к какой модели маршрутизировать.
• prompt — описание сцены. Описывайте позу, окружение, освещение и атмосферу; идентичность персонажа оставьте референсному изображению.
• reference_images — массив URL изображений. Для одного персонажа обычно достаточно одного элемента.
• aspect_ratio — форма выходного изображения. Соответствуйте предполагаемому использованию (квадрат, вертикаль и т. д.).
• num_images — сколько вариантов генерировать на одно задание.

Успешная отправка возвращает JSON-тело с идентификатором задания. Запишите это значение — оно понадобится на этапе опроса. Ответ также может содержать поле статуса, указывающее, что задание в очереди или обрабатывается. Если статус уже терминальный, результат может быть встроен прямо в ответ; в противном случае продолжайте опрос.

Тот же запрос на Python

Ниже тот же самый вызов на Python. Он читает ключ из переменной окружения, отправляет запрос и выводит ссылку на задание.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "ideogram-v3-character",
    "prompt": "дружелюбный робот-механик стоит в залитой солнцем мастерской, держит гаечный ключ, ракурс три четверти",
    "reference_images": [
        "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=60)
response.raise_for_status()

job = response.json()
print(json.dumps(job, indent=2))

job_id = job.get("id") or job.get("job_id")
print("Job id:", job_id)

Замечания к версии на Python

• timeout=60 не позволяет скрипту зависать бесконечно при плохой сети.
• raise_for_status() преобразует ответы не из диапазона 2xx в исключения, чтобы вы сразу заметили проблемы с аутентификацией и валидацией.
• Извлечение ID задания — HiAPI возвращает идентификатор задания в теле ответа. В зависимости от структуры ответа он может находиться под id или job_id; пример проверяет оба, но вам следует сначала проверить реальный ответ, а затем для ясности жёстко задать правильное имя поля.

Нагрузка намеренно полностью совпадает с примером curl. Копирование JSON-тела туда и обратно между ними — хорошая проверка при отладке: если один работает, а другой нет, проблема в транспортном уровне, а не в модели.

Работа с референсными изображениями для согласованности персонажа

Референсные изображения — именно то, что отличает ideogram-v3-character от обычных моделей текст-в-изображение. Хорошо с ними разберитесь — и вы выполните большую часть работы.

Как передаются референсные изображения

Поле reference_images — это массив URL. Каждый URL должен указывать на изображение, которое API может напрямую загрузить. Если вы храните пользовательский контент, раздавайте его из бакета или CDN, разрешающих неаутентифицированные GET-запросы, или создайте подписанный URL, действительный на время выполнения задания.

Советы по референсным изображениям, которые действительно обеспечивают согласованность

• Один персонаж на каждое референсное изображение. На групповых снимках трудно понять, какое лицо сохранять.
• Чёткое лицо и хорошее освещение. Избегайте глубоких теней, экстремальных ракурсов и перекрытий.
• Нейтральная или характерная поза. Анфас или ракурс три четверти лучше всего сохраняют идентичность.
• Если хотите сохранить одежду, она должна быть одинаковой на референсе — модель воспроизведёт то, что видит.
• Разрешение важно, но без фанатизма. Изображение разумного размера с чётким лицом лучше огромного и размытого.

Сохранение узнаваемости персонажа при нескольких генерациях

Когда вы генерируете вторую сцену для того же персонажа, используйте то же самое референсное изображение, а не предыдущий сгенерированный результат. Цепочка сгенерированных изображений может накапливать незаметный дрейф. Если вам нужен новый референс — например, в другой одежде — сгенерируйте его один раз, проверьте, а затем используйте этот файл как новый референс для последующих заданий.

Проверка согласованности

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

Асинхронные задания: отправка, опрос и получение результатов

Генерация изображений требует времени, поэтому HiAPI обрабатывает её асинхронно. Схема всегда одна: отправить, захватить ID задания, опрашивать до достижения заданием терминального состояния, затем прочитать URL результата.

Жизненный цикл задания

1. Отправка — вы отправляете запрос из предыдущего примера.
2. В очереди — задание принято и ожидает ресурсов.
3. Обрабатывается — модель выполняет рендеринг.
4. Завершено или Ошибка — терминальное состояние; результат (или ошибка) доступен.

Опрос на Python

После захвата job_id опрашивайте эндпоинт задания:

import time
import requests

def wait_for_job(job_id, api_key, interval=2, max_attempts=60):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data
        if status in ("failed", "error", "canceled"):
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

Получение результата

После завершения задания тело ответа содержит результат — обычно массив URL изображений или один URL плюс метаданные. Скачайте изображение с этого URL как можно скорее; некоторые URL имеют ограничение по времени. Если вам нужно долговременное хранение, скопируйте файл в свой бакет сразу после успешного завершения задания.

Правила опроса

• Увеличивайте интервал. Двухсекундный интервал подходит для коротких заданий; если вы опрашиваете много заданий, увеличивайте интервал или используйте джиттер.
• Ограничивайте число попыток. Защита max_attempts предотвращает бесконечные циклы и даёт коду явный путь обработки ошибки.
• Не опрашивайте чаще, чем нужно. Каждый опрос — это запрос; шквал запросов к эндпоинту не заставит рендеринг завершиться раньше.

Частые ошибки и способы их диагностики

Когда что-то идёт не так, самый быстрый путь — сначала определить, в чём проблема: в вашем запросе, референсном изображении или самом задании.

Ошибки аутентификации

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

Ошибки валидации

400 почти всегда указывает на нагрузку. Проверьте:

• Поле model в точности равно ideogram-v3-character.
• reference_images — это массив, а не строка.
• Каждый URL в массиве общедоступен.
• aspect_ratio использует поддерживаемое значение.

Если не уверены, отправьте минимальную нагрузку — только model, prompt и reference_images — затем добавляйте поля по одному.

Задания, которые никогда не завершаются

Если опрос превысил предел попыток, не повторяйте вслепую. Проверьте, есть ли сообщение в ответе о статусе задания. Частые причины — недоступный референсный URL или перегруженная очередь. Отправьте заново один раз; если снова застряло, упростите промпт и референсные изображения.

Референсное изображение молча игнорируется

Задание завершается успешно, но персонаж не совпадает. Обычно это проблема референса, а не кода: URL может возвращать страницу ошибки, PDF или изображение-заглушку. Откройте этот URL самостоятельно в браузере и убедитесь, что он возвращает ожидаемое изображение с правильным типом содержимого.

Ограничение частоты запросов

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

Быстрый контрольный список

• Установлен ли ключ в правильном окружении?
• Доступен ли референсный URL без аутентификации?
• Правильно ли написаны поля нагрузки?
• Ограничен ли опрос и используется ли задержка?
• Скачан ли результат до истечения срока действия его URL?

Проверьте этот список по порядку — большинство сбоев решается быстро. После первого успешного сквозного запуска сохраните его как заведомо рабочий пример и сравнивайте с ним любые новые запросы. При масштабировании на множество персонажей и сцен одна эта привычка сэкономит вам время.