Руководство
Как вызвать gpt-image-2.6-flare/text-to-image через HiAPI API: curl, Python и рабочий запрос
На этой странице
Что вы создадите в этом руководстве
Большинство руководств по генерации изображений из текста заканчиваются скриншотом одного успешного ответа. Этого недостаточно, чтобы что-то вывести в продакшен. Это руководство проведёт вас с нуля до многоразовой, работающей интеграции с gpt-image-2.6-flare/text-to-image через единый API HiAPI.
К концу у вас будет три вещи:
- Запрос, подтверждённый как работающий, — сначала в виде команды
curl, затем в виде эквивалентного скрипта на Python. - Чёткая мысленная модель того, как HiAPI организует вызовы генерации изображений из текста — путь эндпоинта, заголовок аутентификации, нагрузка с промптом и тело ответа — чтобы вы могли адаптировать пример под свои промпты, а не заучивать его.
- Шаблоны для масштабирования этого одиночного вызова до пакетной обработки, а также способ определять, какие сбои следует повторять, а какие — исправлять.
Мы будем держать код компактным и с минимумом зависимостей. Пример на Python использует только стандартную библиотеку, поэтому вы можете запустить его в любой среде с установленным Python; когда освоитесь со структурой запроса, адаптируйте его под requests или асинхронный клиент. Если хотите сразу перейти к рабочему вызову, пропустите к разделу с curl, а затем вернитесь к пояснениям.
Предварительные требования и учётные данные
Перед первым вызовом убедитесь, что у вас есть следующее:
- Аккаунт HiAPI. Войдите в панель управления, чтобы создать и управлять учётными данными.
- API-ключ. Создайте его в разделе API-ключей панели управления. Относитесь к нему как к паролю: он авторизует каждый запрос, списываемый с вашего аккаунта.
- Способ отправки HTTP-запросов. Либо оболочка с установленным
curl, либо Python 3 со стандартной библиотекой (urllibиjsonпоставляются вместе с Python).
Обработка ключа через переменные окружения
Никогда не вставляйте ключ напрямую в исходные файлы, которые могут быть закоммичены. Вместо этого экспортируйте его в оболочке:
export HIAPI_API_KEY="your-api-key-here"
В Windows PowerShell используйте $env:HIAPI_API_KEY = "your-api-key-here". В CI внедряйте его как секрет. В долго работающих сервисах загружайте при запуске из менеджера секретов.
Понимание расположения базового URL
HiAPI предоставляет единый унифицированный API, поэтому базовый URL остаётся стабильным между моделями. Храните его в одном значении конфигурации — переменная окружения подойдёт идеально — а не разбрасывайте по коду. Так переключение между stage и продакшеном или направление тестов на mock-сервер потребует изменения одной строки.
Идентификатор модели, которую вы будете вызывать, — gpt-image-2.6-flare/text-to-image. Обратите внимание, что он содержит косую черту; сохраняйте идентификатор целиком и размещайте его на том месте пути, которое ожидает построитель запросов, ровно как в примерах ниже.
Ключ экспортирован, базовый URL записан — теперь можно посмотреть на сам запрос.
Анатомия запроса генерации изображения из текста
Каждый вызов генерации изображения из текста в HiAPI состоит из одних и тех же четырёх компонентов. Как только вы их поймёте, переключение модели или промпта станет механическим.
1. Путь эндпоинта
Запрос использует идентификатор модели как часть пути: gpt-image-2.6-flare/text-to-image, добавленный к вашему базовому URL. Это адрес, который направляет ваш вызов к правильной модели за унифицированным интерфейсом.
2. Заголовок аутентификации
Аутентификация выполняется с помощью bearer-токена в заголовке Authorization:
Authorization: Bearer $HIAPI_API_KEY
Этот заголовок обязателен в каждом запросе. Его отсутствие или неверный формат — самая частая причина сбоя первого вызова.
3. Тело запроса
Вызов генерации изображения из текста — это POST с JSON-телом. В центре — промпт, естественно-языковое описание желаемого изображения. Тело также содержит настройки генерации. Поскольку HiAPI нормализует структуру запросов между моделями, вы можете переиспользовать построитель запросов и менять идентификатор модели, когда захотите сравнить результаты.
4. Тело ответа
Успешный ответ возвращает сгенерированное изображение (или ссылку на него) вместе с метаданными о генерации. Ваш клиент должен проверить HTTP-статус, прежде чем пытаться разобрать изображение. Относитесь к ответу как к данным, а не как к тому, на что смотрят глазами — для автоматизации вам нужны байты изображения или URL, и вам нужно хранить рядом с ними любой идентификатор запроса, чтобы связать файл с вызовом, который его создал.
Это вся модель. Всё дальнейшее — конкретные воплощения этих четырёх компонентов.
Рабочий запрос через curl
Вот полный вызов. Замените промпт своим текстом и запустите:
curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
}' \
--output response.json
Разбор по строкам:
-X POST— генерация — это вызов, изменяющий состояние, поэтому используется POST.- URL — базовый URL из переменной окружения, за которым следует идентификатор модели и
/text-to-image. Кавычки защищают от неверной интерпретации специальных символов оболочкой. Authorization: Bearer ...— учётные данные. Форма$HIAPI_API_KEYне позволяет буквальному ключу попасть в историю оболочки.Content-Type: application/json— сообщает серверу разбирать тело как JSON. Его отсутствие — частая причина запутанных ошибок 4xx.-d '{...}'— JSON-нагрузка. Полеprompt— то, что вы меняете чаще всего; при оптимизации результата добавляйте сюда настройки генерации.--output response.json— записывает тело ответа в файл, чтобы двоичная нагрузка изображения не засоряла терминал. Откройте его или, если ответ закодирован в JSON, передайте черезjq.
Быстрая проверка работоспособности
Если команда быстро возвращается и response.json не пуст, у вас есть работающая интеграция. Если вместо этого вы получили 4xx, проверьте тело ответа — HiAPI возвращает описательные ошибки, а раздел обработки ошибок ниже охватывает частых подозреваемых.
Как только это заработает, сохраните команду в shell-скрипте рядом с проектом. Это самый быстрый способ проверить изменение учётных данных или подтвердить, что сбой на вашей стороне.
Тот же запрос на Python
Вызов curl напрямую переводится в Python. Этот скрипт использует только стандартную библиотеку, читает ключ из переменных окружения и записывает ответ с изображением на диск:
import json
import os
import urllib.error
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"
def generate_image(prompt: str, settings: dict | None = None) -> bytes:
payload = {"prompt": prompt}
if settings:
payload.update(settings)
request = urllib.request.Request(
f"{BASE_URL}/{MODEL}",
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=120) as response:
return response.read()
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc
if __name__ == "__main__":
body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
with open("output.bin", "wb") as f:
f.write(body)
print(f"wrote {len(body)} bytes")
Несколько намеренных решений:
- Таймаут задан с запасом. Генерация изображений медленнее завершения текста; лимит в 120 секунд предотвращает бесконечное зависание, но всё ещё терпит медленные, но успешные вызовы.
- Функция возвращает байты, а не путь. Это делает её многоразовой — вы можете загрузить байты в объектное хранилище или вернуть их из веб-обработчика.
- Ошибки оборачиваются вместе с телом ответа. При ошибке сообщение скажет вам, что ответил сервер, а не только код статуса.
- Построитель нагрузки принимает необязательные настройки. Когда вы добавляете параметры генерации, расширяйте словарь
settings, а не хардкодьте их в функции.
После экспорта двух переменных окружения запустите его с помощью python generate.py. Если вы предпочитаете requests, замените построение запроса на requests.post(url, json=payload, headers=headers); структура идентична.
Пакетная обработка и шаблоны параллелизма
Один промпт — это демонстрация; множество промптов — это работа. Этот переход вносит две проблемы: пропускную способность и отлаживаемость.
Итерация по промптам из файла
Поместите промпты в файл с разделителями-переводами строк или в JSON-массив. Назначьте каждому промпту ID (slug, индекс или хеш) и называйте выходной файл этим ID. Когда пакет из сотен изображений завершится, вы сможете сопоставить каждый файл с его промптом без догадок.
prompts = [
("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
body = generate_image(text)
with open(f"out/{prompt_id}.bin", "wb") as f:
f.write(body)
Явное управление параллелизмом
Вызовы генерации интенсивно используют ввод-вывод, поэтому параллелизм помогает пропускной способности — но неограниченный параллелизм вызовет ограничения скорости и утопит вас в ошибках. Сначала выполняйте последовательно, измерьте время одного вызова, затем увеличивайте параллелизм с помощью пула с ограниченным числом рабочих потоков. Обычно достаточно простого пула потоков с небольшим фиксированным числом рабочих (для начала от четырёх до восьми).
Для более крупных задач используйте асинхронный клиент или очередь с рабочими потоками. Ключевая дисциплина та же: ограниченный параллелизм, один выходной файл на ID промпта, одна строка лога на запрос с ID, статусом и затраченным временем.
Сохранение манифеста
Во время пакетного запуска пишите небольшой JSON-манифест, записывающий каждый ID промпта и его результат. Если процесс умрёт на полпути, манифест скажет вам, откуда возобновить, вместо повторного списания средств за весь пакет. Эта практика экономит больше времени, чем любая хитрая оптимизация.
Обработка ошибок и повторные попытки
Сбои делятся на две категории: те, которые вы исправляете, и те, которые вы повторяете. Путаница между ними тратит время, а в шторме повторных попыток — и деньги.
Исправляйте эти
- 401 / 403 — аутентификация. Ключ отсутствует, просрочен или не имеет прав доступа. Проверьте, что
HIAPI_API_KEYдействительно экспортирован в оболочке, где выполняется команда — частая ловушка — экспортировать в одном терминале и запускать скрипт в другом. - 400 — некорректная нагрузка. Неверный JSON, отсутствующий
promptили неожиданный тип поля. Тело ошибки обычно указывает на проблемное поле. В вызове curl осторожно используйте кавычки в JSON. - 404 — неверный путь. Убедитесь, что идентификатор модели написан точно как в документации, а ваш базовый URL не содержит дублированных или отсутствующих сегментов пути.
Повторяйте эти с экспоненциальной задержкой
- 429 — ограничение скорости. Замедлитесь. Соблюдайте любые подсказки retry-after в ответе и используйте экспоненциальную задержку со случайным разбросом. В долгосрочной перспективе ограничьте параллелизм.
- 5xx — ошибки сервера. Обычно временные. Повторите ограниченное число раз (три — разумное значение по умолчанию), с увеличивающейся задержкой, затем явно сообщите об ошибке.
Минимальная обёртка для повторных попыток
import random, time
def with_retries(fn, attempts=3):
for i in range(attempts):
try:
return fn()
except RuntimeError as exc:
if i == attempts - 1:
raise
time.sleep((2 ** i) + random.uniform(0, 0.5))
Оберните ею generate_image. Ключевой момент — сделать операцию идемпотентной со своей стороны: поскольку выходные файлы именуются по ID промпта, повторная попытка перезаписывает, а не дублирует. Записывайте каждый сбой вместе с ID промпта и сообщением сервера — когда действительно понадобится эскалация, этот лог — именно то, что нужно команде поддержки для воспроизведения проблемы.
Дальнейшие шаги
Теперь у вас есть рабочий запрос, функция Python, которую стоит сохранить, и шаблоны для её масштабирования. Чтобы закалить для продакшена, добавьте структурированное логирование с ID запросов, сохраняйте манифест в постоянное хранилище, чтобы пакетные задания восстанавливались после сбоев, и валидируйте промпты перед отправкой, чтобы некорректный ввод быстро и дёшево давал сбой.
Самый полезный следующий шаг — переиспользовать этого же клиента с другими моделями на HiAPI API. Поскольку путь эндпоинта, заголовок аутентификации и структура нагрузки общие, адаптация скрипта к новой модели обычно означает изменение идентификатора модели и иногда одной-двух настроек — небольшое изменение кода даёт значимо другие выходные данные.
Начните с одного промпта, подтвердите создание файла, а затем пусть остальное сделает пакетный запускатор.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий