HiAPI
Блог

Руководство

Как вызывать gpt-image-2.6-sunburst/text-to-image через HiAPI API: руководство по curl и Python

Аутентификация, структура запроса, рабочие примеры на curl и Python и устранение неполадок

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

Как выглядит интеграция от начала до конца

Каждый вызов генерации изображения по тексту в HiAPI следует одному и тому же жизненному циклу, и стоит понять его до написания любого кода. Ваше приложение формирует JSON-запрос с описанием целевого изображения, отправляет его вместе с учётными данными API на эндпоинт HiAPI, соответствующий gpt-image-2.6-sunburst/text-to-image, и получает ответ, содержащий данные сгенерированного изображения или URL, по которому его можно получить. После понимания этих трёх этапов остальная часть руководства — лишь дополнение деталями.

Этапы выглядят так:

  1. Аутентификация — прикрепите ваш API-ключ HiAPI к запросу, обычно в виде HTTP-заголовка. Согласование токенов для каждого вызова не требуется.
  2. Построение запроса — соберите JSON-тело запроса, содержащее ваш промпт и, при необходимости, такие параметры, как размер и количество изображений.
  3. Передача — отправьте тело запроса методом POST на эндпоинт. Вызов синхронный, поэтому клиент ожидает завершения генерации изображения.
  4. Обработка ответа — API возвращает структурированный JSON. В зависимости от конфигурации эндпоинта данные изображения приходят в виде URL или в виде закодированного содержимого изображения, которое нужно декодировать и записать на диск.

Одна деталь требует внимания с самого начала: идентификатор модели gpt-image-2.6-sunburst/text-to-image содержит косую черту. Считайте его непрозрачной строкой. Не пытайтесь разделить его на имя провайдера и имя модели и не выполняйте собственное URL-кодирование или нормализацию. Скопируйте его в точности как в документации и разместите в одном месте кода, чтобы потом не искать мучительно.

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

Аутентификация запросов к HiAPI

HiAPI использует схему аутентификации на основе API-ключа. Вы получаете ключ в панели управления аккаунта и отправляете его с каждым запросом. Стандартная форма — HTTP-заголовок в запросе:

Authorization: Bearer YOUR_API_KEY

Некоторые клиенты предпочитают отправлять ключ в выделенном заголовке, но если в документации вашего аккаунта не указано иное, используйте форму Authorization: Bearer, поскольку она из коробки совместима с большинством HTTP-инструментов.

Держите ключ вне исходного кода

Самая распространённая ошибка безопасности при первой интеграции — жёстко закодировать ключ в скрипте и закоммитить его. Избегайте этого с первого дня:

  • Читайте ключ из переменной окружения, например HIAPI_API_KEY, и немедленно завершайте работу при запуске, если переменная отсутствует.
  • Прежде чем создавать локальный файл .env, добавьте его в .gitignore.
  • В CI или продакшене передавайте ключ из хранилища секретов платформы, а не читайте из закоммиченного файла.

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

import os

api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
    raise RuntimeError("HIAPI_API_KEY is not set")

При отправке запроса тоже обращайтесь с ключом как с секретом

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

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

Анатомия запроса генерации изображения по тексту

Тело запроса — это JSON-объект. Для gpt-image-2.6-sunburst/text-to-image основных полей немного, и именно поэтому стоит точно понимать, что делает каждое поле, а не слепо копировать полезную нагрузку.

Поле model

"model": "gpt-image-2.6-sunburst/text-to-image"

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

Поле prompt

"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus"

Это описание изображения на естественном языке, обязательное поле. Практические советы по самому промпту:

  • Сначала пишите субъект, затем сцену и в конце — стиль или указания по освещению.
  • Предпочитайте конкретные существительные абстрактным понятиям; «красная керамическая кружка на деревянном столе» лучше, чем «хорошая сцена с кружкой».
  • Если вам нужен согласованный вывод при нескольких вызовах, сохраняйте формулировку неизменных частей стабильной и программно заменяйте только изменяющиеся части.

Необязательные параметры

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

  • size — размер вывода в формате, указанном в документации, например 1024x1024. Если опустить, применяется значение по умолчанию; если отправить неподдерживаемое значение, ожидайте ошибку валидации.
  • n — количество изображений, генерируемых для одного промпта. Каждое сгенерированное изображение оплачивается отдельно, поэтому держите значение минимально необходимым для вашего рабочего процесса.

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

Пример полного тела запроса

{
  "model": "gpt-image-2.6-sunburst/text-to-image",
  "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
  "size": "1024x1024",
  "n": 1
}

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

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

Прежде чем строить Python-клиент, убедитесь с помощью curl, что эндпоинт и учётные данные работают. Это изолирует проблемы аутентификации от проблем кода.

Команда вызова

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
    "size": "1024x1024",
    "n": 1
  }'

Несколько замечаний об этих флагах:

  • -sS сохраняет вывод аккуратным, но по-прежнему показывает ошибки передачи.
  • -X POST задаёт метод; тело передаётся через -d.
  • Одинарные кавычки вокруг JSON-тела не дают оболочке его испортить. В Windows cmd правила кавычек в JSON другие, поэтому используйте curl.exe и двойные кавычки с экранированием внутренних кавычек либо запускайте вызов из shell-скрипта или Python.

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

Проверьте сырой ответ

Когда что-то идёт не так, вам нужны код состояния и тело ответа. Добавьте -i, чтобы включить заголовки ответа, или -w "\nHTTP %{http_code}\n", чтобы вывести код состояния в конце:

curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

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

Тот же вызов на Python

Версия на Python сохраняет JSON-тело побайтово идентичным. Меняется только способ передачи. Использование requests добавляет зависимость, но делает код читаемым; для любого применения, кроме одноразового скрипта, его стоит установить.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-image-2.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
    "size": "1024x1024",
    "n": 1,
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.hiapi.ai/v1/images/generations",
    headers=headers,
    json=payload,
    timeout=120,
)

print(response.status_code)
response.raise_for_status()
data = response.json()
print(data)

Почему json=payload, а не data=json.dumps(payload): передача dict в аргумент-ключевое слово json сериализует его и автоматически задаёт заголовок Content-Type. Передача строки в data тоже работает, но легко забыть задать заголовок, что позже проявится как непонятная ошибка валидации.

Если вы предпочитаете стандартную библиотеку

Чтобы обойтись без зависимостей, используйте urllib.request из стандартной библиотеки. Словарь полезной нагрузки остаётся тем же:

import json, os, urllib.request

payload = {
    "model": "gpt-image-2.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
}

request = urllib.request.Request(
    "https://api.hiapi.ai/v1/images/generations",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
)

with urllib.request.urlopen(request, timeout=120) as response:
    data = json.loads(response.read().decode("utf-8"))

В любом случае генерация изображения происходит медленнее, чем типичный вызов JSON API. Устанавливайте таймаут с запасом, иначе вы получите таймаут на запросе, который вот-вот преуспеет, и заплатите за него дважды при повторной попытке.

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

Успешный ответ — это JSON. Вывод изображения обычно приходит в виде URL (который нужно получить отдельно) или в виде закодированного содержимого изображения в полезной нагрузке. Обратитесь к документации эндпоинта, чтобы подтвердить, какая форма применяется, затем обрабатывайте обе формы защитно, поскольку при изменении параметров точная форма может отличаться.

Чтение структуры ответа

Ответ — это JSON-объект, содержащий сгенерированный вывод и метаданные. Прежде чем писать код разбора, исследуйте его один раз в интерактивном режиме:

print(json.dumps(data, indent=2)[:2000])

Найдите, где находится изображение. Если вы видите поле URL, загрузите его. Если вы видите содержимое в base64, декодируйте его. Не предполагайте, что URL действителен вечно — считайте его кратковременным и сразу скопируйте байты в собственное хранилище.

Сохранение результата на основе URL

image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

Сохранение закодированного результата

import base64

encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(encoded))

В реальных рабочих нагрузках используйте отдельное имя файла для каждого вызова — метку времени, ID запроса или slug, производный от промпта. Если вы планируете позже перегенерировать или аудировать вывод, сохраните промпт вместе с изображением в sidecar JSON-файле.

Обрабатывайте успешный ответ в одном месте

Оберните разбор ответа в функцию, возвращающую список байтовых строк, по одной на изображение. Так каждый вызывающий код просто записывает или загружает байты, не зная, пришли ли они из URL или из закодированного содержимого. Эта абстракция окупится, когда вы позже смените модель.

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

Большинство неудач при первой интеграции попадают в несколько категорий. Прежде чем менять что-либо ещё, сопоставьте код состояния и сообщение с исправлением ниже.

Ошибки аутентификации

Запрос отклонён из-за отсутствующих или недействительных учётных данных — значит, заголовок Authorization отсутствует, имеет неверный формат или содержит отозванный ключ. Проверяйте в таком порядке:

  1. Убедитесь в имени заголовка и формате значения, включая буквальное слово Bearer, за которым следует пробел.
  2. Убедитесь, что переменная окружения действительно заполнена в оболочке или процессе, выполняющем вызов — ключ, заданный в одном терминале, не будет существовать в другом.
  3. Убедитесь, что ключ не был ротирован или обрезан при копировании.

Ошибки валидации тела запроса

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

  • Отсутствует model или prompt — оба обязательны. Отправляйте их явно при каждом вызове, а не полагайтесь на значения по умолчанию.
  • Неизвестная модель — перепроверьте идентификатор gpt-image-2.6-sunburst/text-to-image, включая косую черту и регистр. Не вставляйте вокруг него пробельные символы.
  • Недопустимый размер — используйте поддерживаемую строку размера в формате, указанном в документации. Если вы намеренно опускаете size, удалите его, а не отправляйте null.
  • Некорректный JSON — обычно это проблема кавычек в оболочке при curl или кодировки строк в Python. Проверьте с помощью json.dumps(payload) перед отправкой и проверьте, что фактически передаётся.

Ограничения скорости и квоты

Если вы получаете ответ с ограничением скорости, повторяйте с задержкой и джиттером, а не сразу. Если сообщение указывает на проблему с квотой, проверьте тариф и панель использования аккаунта, а не тело запроса — полезная нагрузка, скорее всего, корректна.

Ошибки сервера

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

Ошибки типа содержимого

Отправка тела запроса без Content-Type: application/json может привести к непонятным ошибкам валидации, поскольку сервер не может разобрать полезную нагрузку. В curl задавайте заголовок явно; в Python позвольте параметру json= сделать это.

Подготовка интеграции к продакшену

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

Сделайте идентификатор модели конфигурируемым

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

Повторяйте попытки продуманно

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

Выберите таймауты, соответствующие рабочей нагрузке

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

Разделите клиент на слои

Держите три части раздельными: построитель полезной нагрузки, преобразующий входные данные приложения в словарь запроса; функция передачи, выполняющая HTTP-вызов; обработчик, декодирующий ответ в байты. Тестировать построитель без сетевых вызовов очень легко; подменить передачу моком тоже очень легко. Такое разделение также делает смену модели редактированием одного файла, а не поиском по всей кодовой базе.

Логируйте то, что понадобится при инциденте

Записывайте метку времени, эндпоинт, идентификатор модели, HTTP-статус, хеш или усечённую форму промпта и длительность запроса. Никогда не логируйте API-ключи или полные заголовки. Если вы храните сгенерированные изображения, задавайте путь хранения по ID запроса, чтобы обращение в поддержку можно было проследить до фактического вызова.

Когда аутентификация обрабатывается переменными окружения, а полезная нагрузка изолирована в функции-построителе, схема, которую вы отработали на gpt-image-2.6-sunburst/text-to-image, напрямую переносится на любую другую модель изображений на том же эндпоинте HiAPI.

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

Все статьи →

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

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

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