GPT Image 2.5 Sunburst API генерации изображений по тексту: рабочие руководства на curl и Python

Если вы хотите генерировать изображения через API hiapi с помощью gpt-image-2.5-sunburst/text-to-image, это руководство проведёт вас через полный и рабочий запрос — отдельно с curl и с Python: от создания задачи до скачивания итогового URL изображения. Каждый показанный здесь запрос/ответ был реально выполнен на боевом API перед публикацией.

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

• Учётная запись hiapi и API-ключ (sk-...). Его можно получить в консоли hiapi.
• curl или Python 3.8+, если вы повторяете пример на Python.
• Бюджет как минимум на одно выходное изображение. gpt-image-2.5-sunburst/text-to-image тарифицируется по выходному разрешению — перед запуском в продакшене проверьте актуальные цены, поскольку тарифы могут меняться.

Все запросы используют стандартные заголовки:

Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

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

Все модели изображений hiapi работают на одном и том же API асинхронных задач: вы создаёте задачу через POST, затем опрашиваете (или получаете webhook-обратный вызов), пока она не достигнет терминального состояния, после чего читаете URL изображения из output[0].url.

1. Создание задачи (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "Минималистичный продуктовый снимок керамической кофейной воронки на мраморной столешнице, мягкий утренний свет, вид как через объектив 35 мм",
      "resolution": "2K",
      "aspect_ratio": "4:3",
      "background": "auto"
    }
  }'

Успешный вызов возвращает только идентификатор задачи — генерация выполняется асинхронно:

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

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

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

Продолжайте опрашивать каждые несколько секунд, пока data.status не станет терминальным значением. При успехе ответ выглядит так (taskId/URL сокращены для удобства чтения):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01ABCDEF...",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "status": "success",
    "storage": "temp",
    "created": 1789144334,
    "completed": 1789144407,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../output-0.png",
        "artifactId": "146251",
        "expireAt": 1789749206
      }
    ]
  },
  "message": "success"
}

Изображение берётся из data.output[0].url. Этот URL истекает (см. expireAt, метку времени Unix) — сразу после успешного завершения задачи скачайте байты и сохраните их у себя, не относитесь к ссылке как к постоянной.

3. Сквозной пример на Python

import time
import requests

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


def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task("Минималистичный продуктовый снимок керамической кофейной воронки на мраморной столешнице")
    task = wait_for_task(task_id)
    image_url = task["output"][0]["url"]
    print(f"Done: {image_url}")

    img_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(img_bytes)

Какие поля фактически принимает input

Схема gpt-image-2.5-sunburst/text-to-image небольшая и строгая. Принимаются только следующие поля — любые другие (quality, size, n, output_format, style, seed) будут отклонены с ошибкой 400:

Поле	Обязательно	Значения
prompt	Да	Любая строка
resolution	Нет (по умолчанию 1K)	1K, 2K, 4K
aspect_ratio	Нет	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
background	Нет	transparent, opaque, auto

Обратите внимание, что это отличается от схемы базовой модели gpt-image-2.5-sunburst: последняя принимает уровни quality (low/medium/high/xhigh/max/auto) и поддерживает редактирование изображения по изображению через image_urls. Цены у них тоже разные — прежде чем опираться на конкретные цифры, сверьтесь с /en/pricing, поскольку тарифы могут меняться.

Паттерны для продакшена

Использование webhook-обратных вызовов вместо опроса

Для любых сценариев, кроме быстрых скриптов, пропустите опрос и позвольте hiapi вызвать вас по завершении задачи. Добавьте объект верхнего уровня callback в тот же запрос POST /v1/tasks:

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

when: "final" — единственное поддерживаемое сейчас значение: когда задача достигает терминального состояния (success или fail), ваш эндпоинт вызывается один раз, а структура полезной нагрузки совпадает с результатом, получаемым при опросе.

Опрос vs. обратный вызов: опрос проще правильно реализовать в скрипте или notebook, и он не требует публичного эндпоинта, но тратит запросы и добавляет задержку (в среднем равную вашему интервалу опроса) перед тем, как вы узнаете о завершении. Для серверных интеграций и любых сценариев с высокой нагрузкой лучше подходит обратный вызов — вы полностью избегаете цикла опроса и получаете уведомление сразу после готовности задачи.

Идемпотентность при повторных попытках

API задач принимает строку верхнего уровня idempotency_key наравне с model/input/callback. Если ваш клиент может повторить POST после таймаута (вы отправили запрос, но так и не получили ответ), добавьте стабильный ключ — так у вас будет чёткий сигнал для сверки, а не догадки о том, действительно ли исходный запрос дошёл.

Обработка ошибок

Недействительный или истёкший API-ключ возвращает HTTP 401 и структурированное тело ошибки:

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

Неверные значения input (некорректный элемент перечисления, отсутствующий prompt, неподдерживаемые поля) возвращают HTTP 400 до создания задачи — поэтому с вас не спишут средства:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Явно проверяйте оба случая: повторяйте попытки при временных сетевых/5xx ошибках, но воспринимайте 400 как сигнал исправить тело запроса, а не как повод слепо повторять его.

Полезные ресурсы

• Страница модели gpt-image-2.5-sunburst — полный справочник параметров и актуальные цены для базовой модели и маршрута /text-to-image.
• Цены hiapi — текущие тарифы по разрешению для этой и всех остальных моделей.
• Рецепты промптов для GPT Image 2.5 Sunburst — если перед написанием скрипта вам нужны примеры промптов для вдохновения, здесь их можно найти.

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

Нужно ли указывать resolution? Нет — если опустить, по умолчанию используется 1K. Если вам нужен вывод в 2K или 4K, задайте его явно, поскольку цена растёт с разрешением.

Можно ли передать quality, как в документации других моделей GPT Image? На этом маршруте — нет. gpt-image-2.5-sunburst/text-to-image полностью отклоняет quality — этот параметр существует только у идентификатора базовой модели gpt-image-2.5-sunburst, у которой другая схема и другое ценообразование.

Почему мой запрос возвращает идентификатор задачи, а не изображение напрямую? Каждая модель изображений на hiapi работает через один и тот же API асинхронных задач (POST /v1/tasks → опрос или обратный вызов → output[0].url), независимо от того, насколько быстро на самом деле работает базовая модель. Один раз постройте интеграцию вокруг этого паттерна, и после этого каждая новая модель будет работать так же.

Что будет, если я не скачаю выходной URL вовремя? Он истечёт — поле expireAt в ответе задачи содержит метку времени Unix, после которой временный URL перестанет работать. Как только status станет success, сразу скачайте и сохраните байты у себя.

Можно ли делать редактирование изображения по изображению с этой моделью? На маршруте /text-to-image — нет. Для редактирования изображений используйте идентификатор базовой модели gpt-image-2.5-sunburst и передавайте поле ввода image_urls — точную схему см. на её странице модели.

Готовы попробовать сами? Получите API-ключ в консоли hiapi и просто замените prompt в приведённом выше примере на Python.