Как использовать gpt-image-2.5-sunburst через hiapi API: curl, Python и рабочие примеры запросов

Чтобы генерировать или редактировать изображения с помощью gpt-image-2.5-sunburst, отправьте задачу с промптом в POST /v1/tasks, а затем опрашивайте GET /v1/tasks/<id> (или принимайте callback), пока задача не завершится, после чего прочитайте URL изображения из data.output[0].url. Это руководство охватывает минимальный запрос, полный набор параметров и схемы, необходимые перед запуском в продакшен (callback, идемпотентность, обработка ошибок).

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

Вам понадобится API-ключ hiapi. Создайте его в консоли — каждый запрос аутентифицируется с помощью Authorization: Bearer sk-<your-key>. Нет бесплатного уровня, который позволял бы вызывать его из браузера, и нет способа обойтись без ключа; все примеры ниже предполагают, что у вас уже есть ключ.

Минимальный рабочий пример

gpt-image-2.5-sunburst/text-to-image требует в input только prompt. Соотношение сторон по умолчанию — auto, разрешение по умолчанию — 1K.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

Он сразу возвращает id задачи:

{"code":200,"data":{"taskId":"tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ"},"message":"success"}

Опрос результата:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

Версия того же цикла запросов на Python:

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url указывает на временное хранилище — в ответе есть expireAt (в секундах Unix). Скачайте байты и сохраните их (в вашем хранилище, S3, R2 и т. п.) до этого срока; не считайте эту ссылку постоянной.

Полный справочник параметров

У gpt-image-2.5-sunburst два model id: gpt-image-2.5-sunburst/text-to-image для генерации по промпту и gpt-image-2.5-sunburst/image-to-image для редактирования или компоновки по референсным изображениям. Оба принимают одинаковые поля; разница в том, что image_urls обязателен для image-to-image и не используется в text-to-image:

Поле	Тип	Значение по умолчанию	Описание
prompt	string, 1–8000 символов	—	Обязательно. При редактировании опишите, что нужно изменить и что должно остаться в точности неизменным.
image_urls	массив URL	—	Только для image-to-image, обязательно, 1–16 изображений в формате JPEG, PNG или WebP, каждое до 20 мегапикселей и не более 30 MB. Должен быть публично доступный URL или data URI.
aspect_ratio	перечисление	"auto"	auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, 8:9.
resolution	перечисление	"1K"	1K, 2K, 4K. Определяет цену.
background	перечисление	нет	transparent, opaque, auto. transparent работает только при 1K, и в этом случае возвращается PNG с альфа-каналом.

Пример редактирования — передайте одно или несколько референсных изображений и опишите только желаемые изменения:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

Схема строгая (additionalProperties: false) — неизвестные поля отклоняются, поэтому не переносите параметры из других моделей изображений (например, size, strength, n).

Схемы для продакшена

В реальном бэкенде используйте callback вместо опроса. Добавьте блок callback, чтобы избавиться от цикла опроса:

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final" срабатывает ровно один раз, когда задача достигает конечного состояния (success или fail). Ваш эндпоинт должен быстро вернуть 2xx и выполнить фактическую работу асинхронно (скачать вывод, обновить собственную базу данных) — hiapi повторяет попытки для callback, не получивших быстрого подтверждения.

Сделайте повторы идемпотентными. Если запрос клиента завершился таймаутом, вы не можете быть уверены, была ли задача создана. Отправьте в запросе создания заголовок Idempotency-Key (не более 255 байт) и используйте один и тот же ключ при повторах: для одного аккаунта и ключа будет создана только одна задача, а повтор вернёт исходный taskId. Без этого повторная обработка одного и того же промпта оплачивается дважды.

Обрабатывайте конечные состояния, которые реально встретите:

• success — прочитайте data.output[0].url и своевременно скачайте файл (соблюдая expireAt).
• fail — перед повтором проверьте data.error, чтобы понять причину сбоя; не пытайтесь слепо повторять каждую неудачу, некоторые из них связаны с самим промптом (например, нарушение политики), и повтор в том же виде снова завершится ошибкой.
• Опрос несуществующего id задачи (опечатка, истёк срок) вернёт HTTP 404 с телом {"code":404,"message":"task not found"}.

Ошибка аутентификации — это HTTP 401, а не ошибка уровня задачи:

{"error":{"code":"permission_denied","message":"This API key is invalid...","request_id":"...","type":"hiapi_error"}}

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

Связанные материалы

• Страница модели GPT Image 2.5 Sunburst — живые примеры и актуальные цены.
• GPT Image 2.5: генерация, редактирование и миграция — если вы переходите с более раннего маршрута Image 2 на серию 2.5 (Flare или Sunburst), здесь описаны различия в параметрах.
• Как изменить стиль изображений с помощью AI — если режим редактирования Sunburst — лишь часть вашего пайплайна, здесь есть более широкий разбор image-to-image.
• Документация по аутентификации и быстрый старт — о полном жизненном цикле запроса за пределами этой одной модели.

Часто задаваемые вопросы

gpt-image-2.5-sunburst поддерживает редактирование изображений или только генерацию из текста? Поддерживает и то и другое — через два model id. Используйте gpt-image-2.5-sunburst/image-to-image с image_urls (1–16 референсных изображений) для редактирования или компоновки, а gpt-image-2.5-sunburst/text-to-image — для генерации только по тексту.

Что произойдёт, если я отправлю пустой массив image_urls вместо того, чтобы опустить его? Не делайте так. В image-to-image image_urls обязателен и требует как минимум одного URL. Для генерации только по тексту используйте model id text-to-image.

Сколько стоит одно изображение? Зависит от resolution: $0.05 для 1K, $0.08 для 2K и $0.12 для 4K — одинаково для text-to-image и image-to-image. Во время акции ко Дню программиста (до 9 ноября 2026 г., 00:00 UTC+8) действует скидка 50% на все тарифы: $0.025, $0.04 и $0.06. Перед масштабированием проверьте актуальные цены на странице модели.

Можно ли получить фиксированный размер в пикселях вместо соотношения сторон? Да — помимо строк-соотношений вроде 16:9, aspect_ratio принимает буквальные размеры, такие как 1024x1024, 1536x1024 или 3840x2160.

Почему при опросе задачи возвращается 404? Либо в taskId опечатка, либо на эндпоинте/в регионе, которые вы опрашиваете, этой задачи нет. Внимательно проверьте id, сохранённый из ответа на создание — hiapi не делает записи задач недействительными молча в течение любого нормального окна опроса.

Можно ли вызвать это для тестирования без API-ключа? Нет. Каждый запрос к /v1/tasks требует Authorization: Bearer sk-<key>; анонимного режима или режима только через браузер нет.