HiAPI
Блог

Руководство

Как использовать krea-3/text-to-image через API HiAPI: curl, Python и рабочий запрос

Nov 10, 2026
Обложка: на тёплом угольно-сером фоне через изображение по диагонали проходит янтарная полоса света, по краям которой расположены тонкие линии дополнительного цвета.
На этой странице

Почему стоит вызывать krea-3/text-to-image через агрегирующий API

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

Вызов krea-3/text-to-image через HiAPI устраняет эти издержки. Вы интегрируетесь один раз — с единым соглашением об эндпоинте, едиными учётными данными и единой структурой ответа. Идентификатор модели становится полем в теле запроса, а не отдельной веткой в кодовой базе. Когда вы захотите сравнить результаты с другими моделями изображений или перенести рабочую нагрузку, вы измените одну строку, а не целую интеграцию.

Для этой конкретной модели практическая выгода конкретна:

  • Единая структура для всех запросов. Вызовы генерации изображений по тексту на всей платформе подчиняются одним и тем же соглашениям об аутентификации и теле запроса, поэтому знания, полученные при первом вызове, напрямую переносятся на следующую модель.
  • Код приложения, не зависящий от модели. Держите имя модели в конфигурации. Прототипирование на krea-3/text-to-image не должно требовать изменения HTTP-слоя при переходе на другую модель для обслуживания.
  • Единая точка наблюдения за использованием. Биллинг, журналы запросов и ответы с ошибками приходят из одного интерфейса, а не из N панелей разных поставщиков.
  • Меньше ключей. Независимо от того, сколько моделей вы вызываете, вам нужно хранить, ротировать и ограничивать один ключ.

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

Этот учебник намеренно узко сфокусирован. Мы соберём рабочий запрос, выполним его дважды (сначала через curl, затем через Python), посмотрим, как формулировка промпта направляет вывод в сторону фотографии или иллюстрации, а затем отладим те несколько случаев отказа, которые составляют большинство проблем при первом вызове. Без архитектурных схем и без мнений о фреймворках — только запрос, который вы сможете отправить в течение следующих пяти минут, и контрольный список на случай проблем.

Предположения: у вас есть аккаунт HiAPI, вы можете прочитать ключ API в панели управления и знакомы с терминалом и интерпретатором Python. Больше ничего не требуется.

Перед отправкой запроса

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

1. Аккаунт и ключ API

Войдите в HiAPI и получите ключ API в панели управления. Относитесь к нему как к секрету: он должен храниться в переменной окружения или менеджере секретов и никогда не появляться в закоммиченных файлах, в промптах или в сообщениях в поддержку. В примерах ниже он читается из переменной окружения:

export HIAPI_API_KEY="your-key-here"

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

2. Соглашение об эндпоинте и заголовок аутентификации

Запросы HiAPI используют аутентификацию по bearer-токену — тот же шаблон, который вы видели в сотнях других API:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Используйте базовый URL, указанный в справочнике API HiAPI для региона вашего аккаунта, и добавьте к нему задокументированный путь генерации изображений. Не угадывайте путь по памяти или из статей в блогах (включая эту) — справочник API является единственным источником истины, а путь — единственная часть запроса, которая может измениться без предупреждения. Совет из учебника: загляните в справочник один раз, скопируйте URL и сохраните его как значение конфигурации.

3. Идентификатор модели с точным написанием

Идентификатор модели — krea-3/text-to-image. Сохраняйте префикс пространства имён и дефисы в точности как написано — krea3/text2image или отдельное krea-3 завершатся ошибкой «модель не найдена». Регистр тоже важен. Сохраните его как константу:

MODEL = "krea-3/text-to-image"

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

Что не нужно выяснять заранее

Вам не нужно заранее знать имена полей размера изображения, seed или шагов. Начните с минимальной конфигурации: аутентификация, идентификатор модели, промпт. Как только вы получите ответ 200, добавляйте параметры по одному, потому что неудачный запрос с пятью заданными полями даёт вам пять подозреваемых. Минимальный неудачный запрос даёт вам одного.

Сборка рабочего запроса с помощью curl

curl — самый быстрый способ изолировать две проблемы первого вызова: учётные данные и структуру тела запроса. Без версии SDK, без виртуального окружения, без асинхронного рантайма — только запрос по сети.

Минимальный вызов несёт только то, что действительно нужно модели: заголовок аутентификации, идентификатор модели и промпт.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-3/text-to-image",
    "prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
  }'

Два замечания перед запуском. Во-первых, $HIAPI_BASE_URL — это заполнитель: задайте его равным базовому URL из справочника API HiAPI и сверьте сегмент пути с тем же справочником. Во-вторых, флаг -sS подавляет лишний вывод, но показывает ошибки — именно это нужно при отладке.

Как выглядит нормальный ответ: JSON-объект, содержащий ссылку на сгенерированное изображение или данные вместе с метаданными запроса. Точная структура описана в справочнике API; не пишите код разбора для структуры, которую вы ещё не наблюдали. Сохраните реальный ответ в файл, чтобы получить базовый факт:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
  -o response.json

Затем проверьте его с помощью jq или вашего редактора. Этот файл — ваш тестовый фикстур: когда вы будете переносить код в Python, сравните вывод. Если ответ Python структурно отличается от response.json, проблема в вашем коде, а не в модели.

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

После успеха минимального запроса добавляйте параметры по одному. Перезапускайте curl после каждого добавления. Сохраняйте успешные тела запросов; они станут принятыми входными фикстурами для ваших тестов.

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

Версия на Python намеренно скучная: тот же URL, те же заголовки, то же JSON-тело. Главное — переносимость: структура запроса, проверенная в curl, должна перейти в скрипт, а затем в сервис без перепроектирования.

import os
import json
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"

def generate(prompt: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"model": MODEL, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate(
        "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
    )
    print(json.dumps(result, indent=2))

Несколько намеренных решений:

  • Используйте переменные окружения, а не литералы. Ключ никогда не появляется в исходном коде. Если переменная отсутствует, os.environ["HIAPI_API_KEY"] громко упадёт при запуске, что лучше, чем запутанная ошибка 401 на три уровня ниже.
  • Вызывайте raise_for_status() до разбора. Вы хотите, чтобы HTTP-ошибки всплывали как исключения, а не получали KeyError, когда пытаетесь прочитать поле из тела ошибки, которое случайно оказалось JSON.
  • Щедрый таймаут. Генерация изображений — не мгновенный эндпоинт. Установите таймаут, отражающий это, и обрабатывайте его явно в продакшене (см. раздел о продакшене).
  • Используйте json=, а не ручную сборку строк. Пусть библиотека сериализует. Ручная склейка JSON — именно источник ошибок с запятыми в конце и кавычками.

Запустите один раз и сравните вывод с ранее сохранённым response.json. Структура должна совпадать. Выведите ссылку на изображение или декодированные данные изображения в зависимости от того, что возвращает ответ — опять же, пишите код для наблюдаемой структуры, а не для предполагаемой.

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

Управление фотографическим стилем и стилем иллюстрации

Стиль — не переключатель; это направление, в которое вы толкаете модель, и krea-3/text-to-image откликается на те же рычаги, которые вы использовали бы при работе с фотографом или иллюстратором: субъект, медиум, освещение и словарь ремесла.

Движение к фотографическому стилю

Фотографический вывод в основном заключается в назывании оборудования и его последствий. Слова, описывающие камеру, объектив, плёнку и реальный свет, работают лучше, чем слово «реалистичный».

  • Называйте медиум и способ съёмки: "35mm photograph", "editorial portrait", "documentary still".
  • Называйте свет: "overcast daylight", "golden hour backlight", "single softbox at camera left".
  • Называйте несовершенства: "slight motion blur", "visible grain", "shallow depth of field".

Сравните "a fisherman on a dock" и "a weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph, visible grain". Второй промпт ограничивает модель текстурой и освещением фотографии, а не общим изображением.

Движение к стилю иллюстрации

Иллюстрация заключается в назывании традиции, качества линии и палитры — и часто в удалении фотографических подсказок, которые вы только что изучили.

  • Называйте стиль: "flat vector illustration", "ink and watercolor", "mid-century editorial illustration", "isometric line art".
  • Называйте линии: "clean uniform strokes", "loose gestural linework".
  • Называйте палитру: "restrained two-color palette", "muted pastels".

Итерации, а не пресеты

Рассматривайте промпт как настраиваемую конфигурацию. Меняйте одну размерность за раз — заменяйте только фразу о медиуме, оставляя субъект и освещение неизменными — так вы узнаете, что делает каждый токен. Ведите краткий журнал вариантов промптов и их результатов; этот журнал ценнее любой библиотеки пресетов, потому что он откалиброван под вашу модель и ваш контент.

Если запрос предоставляет параметры помимо промпта — размер, seed или подобные — настраивайте их после того, как определились с промптом, а не до. Одновременное изменение промпта и трёх параметров не скажет вам, что именно сработало.

Диагностика типичных ошибок

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

Сбои аутентификации

Симптом: 401 или 403 с сообщением об учётных данных или разрешениях.

  • Действительно ли HIAPI_API_KEY задан в оболочке, запускающей команду? echo $HIAPI_API_KEY — пустая строка очень похожа на неверный ключ.
  • Заголовок точно Authorization: Bearer <key>? Отсутствие Bearer, лишние кавычки или перенос строки, вставленный в ключ, приведут к сбою.
  • Не отозван ли ключ и не ограничен ли он другим окружением? Если сомневаетесь, перегенерируйте и повторите тест с curl.

Некорректное тело запроса

Симптом: 400 с сообщением о теле, поле или разборе JSON.

  • Проверяйте JSON перед отправкой. В curl одна неэкранированная кавычка в промпте ломает тело. В Python json= справится с этим за вас — ещё одна причина предпочесть его.
  • Проверьте наличие Content-Type: application/json.
  • Сверьте имена полей со справочником API. Правильно написанное значение под неправильным именем поля всё равно даст 400.
  • Вернитесь к минимальному телу — только модель и промпт — убедитесь, что оно работает, и только потом добавляйте поля по одному.

Неверный идентификатор модели

Симптом: 404 или 400 с сообщением, что модель неизвестна или недоступна.

  • Сравните вашу строку с krea-3/text-to-image символ за символом. Префикс пространства имён, дефисы и сегменты пути важны.
  • Проверьте, не появились ли случайные пробелы или типографские кавычки из-за копирования из документации.
  • Убедитесь, что значение не переопределено значением по умолчанию из конфигурации где-то в коде.

Ответы о лимитах и квотах

Симптом: 429 или сообщение о лимитах или недостаточном балансе.

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

Если ничего из перечисленного не помогло, захватите полный ID запроса и тело ошибки из ответа и отправьте в поддержку. Тела ошибок в агрегирующих API обычно достаточно конкретны, чтобы указать на проблему; ошибка — пересказывать их вместо того, чтобы вставлять как есть.

Вывод в продакшен

Ваш текущий запрос — прототип. Четыре практики превратят его в то, что можно запускать постоянно.

Обрабатывайте ошибки по категориям, а не по строкам

Сопоставьте HTTP-коды поведениям: ошибки аутентификации — это дефект конфигурации, нужно кого-то позвать; ошибки 4xx в теле — это дефект кода, запрос должен громко упасть; 429 и 5xx — временные, их нужно повторять с экспоненциальной задержкой и джиттером. Никогда не повторяйте 400 — вы лишь потратите квоту на подтверждение одного и того же дефекта. Установите явные таймауты и считайте таймаут временной ошибкой.

if response.status_code == 429 or response.status_code >= 500:
    raise TransientError(response.status_code)
response.raise_for_status()

Логируйте промпты и версионируйте их

Каждое сгенерированное изображение должно быть прослеживаемо до точного промпта, который его создал. Храните промпт, идентификатор модели, параметры и ID запроса ответа вместе. Рассматривайте текст промпта как версионируемую конфигурацию — строку prompt_v3, закоммиченную в файл конфигурации, а не литерал, погребённый в функции. Когда качество результатов меняется, вам нужно знать, изменился ли промпт, параметры или модель.

Держите имя модели в конфигурации

krea-3/text-to-image должно появляться один раз — в константе или записи конфигурации. В этом и отдача от агрегирующей модели: замена модели, запуск сравнения или откат становятся изменением конфигурации, а не развёртыванием нового пути кода. Это также делает маршрутизацию разных рабочих нагрузок к разным моделям тривиальной в будущем.

Тестируйте на фикстурах

Сохраните успешные ответы, захваченные в этом учебнике, как фикстуры. Утверждайте, что ваш код разбора справляется с ними, и используйте записанные тела ошибок для тестирования сопоставления ошибок. Вы обнаружите дрейф структуры ответа раньше пользователей.

Начните с минимального вызова curl, подтвердите структуру ответа, перенесите его как есть в Python, затем итерируйте промпт по одной размерности — и сверяйтесь со справочником API HiAPI для деталей эндпоинта, которые могут меняться.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API