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

gpt-image-2.5-sunburst@pro — это Pro-маршрут модели gpt-image-2.5-sunburst на hiapi. Это руководство проведёт вас с нуля до работающего запроса: что такое model id на самом деле, какие именно поля input он принимает, готовый к запуску пример на curl/Python, а также production-паттерны, которые понадобятся перед запуском без присмотра (идемпотентность, callback-и, обработка ошибок).

Что нужно подготовить

• Аккаунт hiapi и API key из консоли. Каждый запрос ниже аутентифицируется через Authorization: Bearer sk-<your key>.
• Это всё — отдельно устанавливать SDK не нужно. Каждая модель на hiapi вызывается через один и тот же асинхронный эндпоинт задач, поэтому если вы уже вызывали любую другую модель hiapi, структура этого запроса будет вам знакомой.

Единственная особенность этой модели: @pro — это суффикс маршрута, а не псевдоним. hiapi для некоторых моделей предоставляет более одного режима вызова, и gpt-image-2.5-sunburst — одна из них: обычный model id и id с суффиксом @pro принимают разные поля input и тарифицируются по разным ценовым уровням. Это руководство посвящено именно gpt-image-2.5-sunburst@pro; используя голый id gpt-image-2.5-sunburst, вы получите другой режим и другую схему (см. FAQ).

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

Каждая генеративная модель hiapi — изображения, видео или аудио — вызывается через один унифицированный эндпоинт: POST /v1/tasks. Вы отправляете model и input, сразу получаете taskId, а генерация выполняется асинхронно.

Для gpt-image-2.5-sunburst@pro input принимает:

Поле	Тип	Обязательно	Описание
prompt	string	да	от 1 до 32 000 символов
image_urls	string[]	нет	от 1 до 16 публичных URL в формате JPEG/PNG/WebP; если указано, выполняется генерация по изображению, а не по тексту (SVG не поддерживается)
aspect_ratio	enum	нет	например 1:1, 16:9, 9:16 или явный размер вроде 1536x1024; по умолчанию 1:1
quality	enum	нет	low / medium / high / xhigh / max / auto; по умолчанию medium — перед повышением посмотрите замечания по production ниже
background	enum	нет	transparent, opaque или auto; по умолчанию auto
output_format	enum	нет	png, jpeg или webp; по умолчанию webp

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper on a light wood table, soft studio lighting",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

Это сразу вернёт taskId:

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

Затем опрашивайте для получения результата:

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Как только data.status станет success, изображение находится в data.output[0].url. Скачайте его сразу — у этого URL есть expireAt, он не подходит для постоянных внешних ссылок.

Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper "
                      "on a light wood table, soft studio lighting",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

Production-паттерны

Опрос и callback-и. Цикл выше подходит для скриптов и низкой нагрузки. Для любого серверного сценария предпочитайте callback вместо опроса: добавьте в тот же запрос объект callback —

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url должен быть HTTPS, а when: "final" (сейчас единственное поддерживаемое значение) уведомит вас один раз как при успехе, так и при ошибке — без цикла опроса и лишних запросов. hiapi может доставлять callback несколько раз, поэтому дедуплицируйте на своей стороне по taskId.

Идемпотентность. Добавьте заголовок Idempotency-Key к POST /v1/tasks (произвольная строка до 255 байт, например id заказа). Если сетевой таймаут заставит ваш клиент повторить ту же отправку, платформа вернёт исходный taskId (в заголовке ответа будет Idempotent-Replay: true), а не создаст — и не спишет оплату за — вторую задачу. Ключ действует в рамках вашего аккаунта и истекает через 24 часа; повторное использование его с другим телом запроса вернёт 422 IDEMPOTENCY_KEY_MISMATCH вместо молчаливого создания новой задачи, так что несовпадение — это сигнал проверить логику повторов, а не слепо повторять запрос.

Ошибки аутентификации. Неверно отформатированный или неправильный API key быстро завершается ошибкой с кодом 401 и кодом ошибки permission_denied ещё до создания какой-либо задачи:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Если вы видите это, причина почти всегда в самом key (ошибка в переменной окружения, истёкший key, отсутствующий префикс sk-) — а не в теле запроса. Пока key не исправлен, считайте это неповторяемой ошибкой.

О quality. quality по умолчанию равно medium, и это разумное значение для релиза — повышение одновременно увеличивает стоимость и время генерации, поэтому переходите на high/xhigh/max только после того, как в ваших собственных тестах убедитесь, что данный prompt при этом уровне всё ещё надёжно отрабатывает.

Связанные страницы

• Страница модели gpt-image-2.5-sunburst — возможности серии моделей, примеры вывода и все доступные режимы.
• Документация унифицированного асинхронного API — полный контракт /v1/tasks, общий для всех генеративных моделей hiapi (идемпотентность, callback-и, коды состояния).
• Документация по аутентификации — как создавать API key и управлять ими.
• Руководство по API gpt-image-2.5-sunburst — если вам нужен базовый (не @pro) режим, здесь подробно описана его отдельная схема на основе resolution.
• Цены — текущая стоимость одного изображения по уровням quality.

FAQ

Являются ли gpt-image-2.5-sunburst@pro и gpt-image-2.5-sunburst разными моделями? Это одна серия моделей, но разные маршруты. Голый id gpt-image-2.5-sunburst (и его режим /text-to-image) принимает поле resolution (1K/2K/4K) и не имеет полей quality или image_urls. @pro заменяет это уровнями quality и добавляет необязательный image_urls, поэтому используйте этот маршрут, когда хотите управлять уровнем качества или выполнять генерацию по изображению в рамках одного вызова.

Нужно ли мне референсное изображение? Нет. Для генерации по тексту полностью опустите image_urls. Если указать от 1 до 16 публичных URL изображений, вывод будет обусловлен референсными изображениями.

Могу ли я использовать эту модель без API key? Нет — каждый запрос требует действительного заголовка Authorization: Bearer с реальным API key hiapi из вашего аккаунта. Неаутентифицированного или бесплатного режима без ключа не существует.

Сколько это стоит? Цена зависит от уровня quality и поддерживается в актуальном состоянии на странице цен, а не дублируется здесь — сверяйтесь с ней перед оценкой затрат при масштабировании.

Что делать, если мой callback так и не пришёл? Доставка callback не гарантирует мгновенность, и hiapi может повторять доставку (поэтому дедуплицируйте по taskId). Если вам нужен жёсткий предел, после таймаута сохраняйте запасной опрос GET /v1/tasks/:id вместо бесконечного ожидания callback.

Почему я получаю статус fail, а не ошибку при отправке? Отправка (возвращающая 200/taskId) означает лишь то, что запрос принят — сама генерация всё ещё может асинхронно завершиться ошибкой. Проверяйте data.status после опроса или через callback, и перед повторной отправкой проверьте data.error, чтобы узнать причину.