HiAPI
Блог

Руководство

Как вызвать gpt-image-2.6-flare/text-to-image через HiAPI API: curl, Python и рабочий запрос

Nov 10, 2026
Абстрактная обложка из перекрывающихся полупрозрачных стеклянных листов, превращающих бледное поле в прохладные синие полосы, матовая и архитектурная, без текста.
На этой странице

Что вы создадите в этом руководстве

Большинство руководств по генерации изображений из текста заканчиваются скриншотом одного успешного ответа. Этого недостаточно, чтобы что-то вывести в продакшен. Это руководство проведёт вас с нуля до многоразовой, работающей интеграции с gpt-image-2.6-flare/text-to-image через единый API HiAPI.

К концу у вас будет три вещи:

  • Запрос, подтверждённый как работающий, — сначала в виде команды curl, затем в виде эквивалентного скрипта на Python.
  • Чёткая мысленная модель того, как HiAPI организует вызовы генерации изображений из текста — путь эндпоинта, заголовок аутентификации, нагрузка с промптом и тело ответа — чтобы вы могли адаптировать пример под свои промпты, а не заучивать его.
  • Шаблоны для масштабирования этого одиночного вызова до пакетной обработки, а также способ определять, какие сбои следует повторять, а какие — исправлять.

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

Предварительные требования и учётные данные

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

  1. Аккаунт HiAPI. Войдите в панель управления, чтобы создать и управлять учётными данными.
  2. API-ключ. Создайте его в разделе API-ключей панели управления. Относитесь к нему как к паролю: он авторизует каждый запрос, списываемый с вашего аккаунта.
  3. Способ отправки 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. Поскольку путь эндпоинта, заголовок аутентификации и структура нагрузки общие, адаптация скрипта к новой модели обычно означает изменение идентификатора модели и иногда одной-двух настроек — небольшое изменение кода даёт значимо другие выходные данные.

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

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

Все статьи →

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

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

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