Как использовать recraft-v4.1/text-to-image через HiAPI API: руководство по curl и Python

Что даёт этот эндпоинт

recraft-v4.1/text-to-image — это эндпоинт модели генерации изображений по тексту: вы отправляете текстовый промпт и несколько параметров формирования в теле запроса, а затем получаете сгенерированные данные изображения. Он отлично подходит, когда вы хотите получить готовое изображение за один вызов, не выстраивая самостоятельно многошаговый конвейер.

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

Практичный способ понять этот вызов:

• Prompt — описание желаемого изображения на естественном языке.
• Style — поле тела запроса, задающее визуальную обработку вывода.
• Resolution — поле тела запроса, определяющее размер вывода.

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

Предварительные требования и аутентификация

Перед первым вызовом убедитесь, что у вас есть:

• Учётная запись HiAPI и API-ключ. Держите его вне системы контроля версий и загружайте из переменных окружения.
• curl для быстрой проверки работоспособности и Python 3 с установленным requests (если вы планируете использовать пример на Python).
• Промпт, который вы действительно хотите отрендерить, — даже черновой достаточно, чтобы проверить правильность связки.

Аутентификация в HiAPI основана на заголовках. API-ключ передаётся через заголовок, и независимо от того, вызываете ли вы из curl, Python или другого HTTP-клиента, используется одна и та же схема заголовков. Выбор модели осуществляется через путь эндпоинта, поэтому при переключении модели заголовок аутентификации остаётся неизменным.

Безопасная локальная настройка выглядит так:

export HIAPI_API_KEY="your-key-here"

Затем ссылайтесь на $HIAPI_API_KEY в командах оболочки и на os.environ["HIAPI_API_KEY"] в Python. Никогда не встраивайте ключ в скрипты, которые могут быть закоммичены, и избегайте его вставки в логи или отчёты об ошибках. Если ключ скомпрометирован, смените его в настройках учётной записи, а не пытайтесь вычистить из истории.

Следующие примеры предполагают две вещи: базовый URL HiAPI API и путь модели recraft-v4.1/text-to-image. Перед интеграцией в сборку сверьте оба с API-справочником вашей учётной записи, поскольку точный хост и путь — единственное в этом руководстве, что следует копировать из актуальной документации, а не по памяти.

Рабочий запрос curl

Самый быстрый способ убедиться, что ключ, эндпоинт и структура полезной нагрузки работают, — один вызов curl. Запрос отправляет JSON-тело с промптом и полями формирования и передаёт API-ключ в заголовке:

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

Обратите внимание на несколько моментов в этом вызове:

• Путь эндпоинта. Имя модели находится в пути. Переход на другую модель позже означает изменение этого сегмента пути, а не перестройку запроса.
• Тело, а не строка запроса. prompt, style и resolution находятся в JSON-теле. Так URL остаётся стабильным, а полезную нагрузку легко записывать и воспроизводить.
• Аутентификация через заголовок. Заголовок Authorization несёт ключ; Content-Type должен быть application/json.

Если при первой попытке вы получите ответ не 200, проверьте в следующем порядке: задан ли ключ в оболочке, нет ли в базовом URL дублирующегося завершающего слэша, валиден ли JSON-тело (висячие запятые — обычно главный виновник). Как только вызов успешен, сохраните точную команду в черновой файл — рабочий вызов curl служит эталоном, с которым вы сравниваете каждое изменение SDK и клиента.

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

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

import os
import requests

HIAPI_BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

Принципы дизайна, которые стоит сохранить:

• Используйте json=, а не data=. Передача dict в json= устанавливает тип содержимого и сериализует тело за вас, поэтому полезная нагрузка побайтово совпадает с версией для curl.
• Явный таймаут. Генерация изображений не мгновенна; щедрый таймаут предотвращает ложные сбои из-за медленных, но здоровых запросов. Не полагайтесь на значения по умолчанию клиента.
• Сначала raise_for_status(). Преобразуйте HTTP-ошибки в исключения до попытки чтения тела ответа, чтобы 4xx или 5xx никогда не принимались за данные изображения.
• Конфигурация через окружение. Базовый URL и ключ берутся из окружения, что делает функцию переносимой между локальной средой, предпроизводственной и производственной.

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

Обработка синхронного ответа с изображением

recraft-v4.1/text-to-image возвращает данные изображения синхронно: изображение приходит в том же HTTP-ответе на запрос, без цикла опроса и без ID задачи, за которой нужно следить. Это упрощает клиент, но переносит две обязанности в ваш код — декодирование полезной нагрузки и явную обработку сбоев.

Надёжный путь обработки выглядит так:

1. Проверяйте статус до разбора. Считайте любой статус, отличный от 200, ошибкой и отображайте тело ответа — оно обычно объясняет, в чём проблема.
2. Читайте поле изображения осознанно. JSON ответа несёт данные изображения; в зависимости от полученного поля это может быть URL или закодированные байты изображения. Обрабатывайте оба пути, а не предполагайте один из них.
3. Декодируйте с защитой. Если полезная нагрузка закодирована в base64, декодируйте и записывайте байты в файл. Не проводите двоичные данные через пути, предназначенные только для текста, и не выводите их в терминал.
4. Ограничивайте размер полезной нагрузки. Синхронные ответы с изображениями велики по сравнению с типичным JSON. Записывайте на диск потоком, если клиент это поддерживает, и избегайте одновременного хранения нескольких ответов в памяти.

Минимальный шаг сохранения для полезной нагрузки в base64:

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

Два режима сбоя заслуживают отдельной обработки. Таймауты следует повторять с экспоненциальной задержкой, но только при ожидании идемпотентности — повторная генерация изображения даёт другой результат, поэтому записывайте промпт при каждой попытке. Клиентские ошибки (например, неверный формат тела запроса или недопустимое значение параметра) не исправятся от повтора; быстро завершайте с ошибкой и записывайте текст ответа. Наконец, перед декодированием проверяйте наличие поля изображения, чтобы изменение схемы или ошибочная полезная нагрузка вызывали понятное исключение, а не запутанную ошибку декодирования.

Настройка стиля и разрешения под ваш сценарий

style и resolution — два поля тела запроса с наибольшим влиянием на результат, и оба дешевы в итерации, поскольку передаются вместе с промптом.

Style

style задаёт визуальную обработку вывода. Используйте его для сохранения единообразия серии изображений — например, фиксируйте один стиль для набора продуктовых иллюстраций или заголовочных изображений статей, чтобы они выглядели как комплект. Когда результат кажется неправильным, сначала проверьте, соответствует ли стиль содержимому: применение стиля, ориентированного на иллюстрацию, к реалистичному промпту будет конфликтовать с текстом. Прежде чем добавлять детали, попробуйте простые промпты с фиксированным стилем, чтобы понять, вызван ли плохой результат стилем или формулировкой.

Resolution

resolution определяет размер вывода. Согласуйте его с целевым назначением: для аватаров и миниатюр выбирайте размеры, близкие к квадратным, для баннеров и главных изображений — более широкие. Два практических правила:

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

Отладка неожиданного вывода

Когда изображение выглядит неправильно, изолируйте одну переменную за раз. Оставьте промпт неизменным и измените style; затем оставьте оба неизменными и измените resolution. Если ничего не помогает, перепишите промпт, используя конкретные существительные и явные композиционные подсказки, а не добавляя прилагательные. Также убедитесь, что вы не отправляете незаметно неверный тип значения — строка стиля, не соответствующая допустимым вариантам, может быть отклонена или проигнорирована в зависимости от логики валидации. Записывайте точное тело каждого запроса — это единственная надёжная запись о том, откуда взялось изображение.

Обёртка для производственной среды

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

• Инкапсулировать транспорт. Одна функция владеет URL, заголовками, структурой полезной нагрузки и таймаутом. Вызывающий код передаёт только промпт и параметры, и ничего больше.
• Добавить повторные попытки с задержкой. Повторяйте таймауты и ответы 5xx ограниченное число раз; никогда не повторяйте ошибки 4xx. Поскольку генерация изображений не идемпотентна, устанавливайте низкий лимит повторов и сохраняйте связь промпта с каждой попыткой.
• Записывать запросы, а не только результаты. Записывайте промпт, стиль, разрешение, статус и длительность. Когда кто-то спрашивает, почему изображение выглядит именно так, журнал и есть ответ.
• Сделать модель параметром. Передавайте путь модели как параметр со значением по умолчанию recraft-v4.1/text-to-image. Тогда переключение на другую модель изображений становится изменением конфигурации, а не рефакторингом, что делает параллельную оценку недорогой.

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

С аутентификацией, рабочим запросом и явной обработкой ответов у вас есть всё необходимое для вызова recraft-v4.1/text-to-image из HiAPI через curl и Python, а также возможность позже переключить модель, не трогая остальной код.