Руководство
Как использовать krea-3/text-to-image через API HiAPI: curl, Python и рабочий запрос
На этой странице
Почему стоит вызывать 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 для деталей эндпоинта, которые могут меняться.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий