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

gpt-image-2.5-flare@pro — одна из моделей изображений, доступных через единый API задач hiapi. В этом руководстве сначала показан минимальный рабочий запрос на curl и Python, а затем описаны параметры и режимы, необходимые для продакшена: колбэки, идемпотентность и обработка ошибок.

Что вам понадобится

• Ключ API hiapi. Его можно получить в консоли hiapi — каждый ключ начинается с sk-.
• Базовый URL https://api.hiapi.ai. Каждый запрос требует заголовка Authorization: Bearer sk-<your-key>.

Генерация изображений в hiapi (как и все остальные асинхронные модели — видео, TTS, музыка) работает через одну и ту же конечную точку: POST /v1/tasks. Сначала вы создаёте задачу, затем можете опрашивать GET /v1/tasks/:id или получать колбэк по завершении задачи. Полный справочник: Единый асинхронный API.

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

curl

Создание задачи:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

Здесь возвращается ID задачи, а не изображение — генерация изображений асинхронная:

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

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

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status меняется в порядке queued → handling → archiving → success (или fail). Когда статус — success, изображение находится в data.output[0].url:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt — это Unix-временная метка: скачайте файл или разместите его заново до истечения срока, после чего URL перестанет работать.

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

Установите единственную зависимость командой pip install requests, экспортируйте HIAPI_API_KEY и запускайте.

Ключевые параметры

gpt-image-2.5-flare предоставляет два маршрута: маршрут по умолчанию (напрямую с ID модели gpt-image-2.5-flare) и pro-маршрут (с добавлением @pro, как во всех примерах выше). Явного суффикса @default не существует — передача его вернёт MODEL_UNAVAILABLE.

input принимает следующие поля:

• prompt (строка, обязательное) — единственное обязательное поле.
• aspect_ratio — 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, auto или явные размеры в пикселях, такие как 1536x1024, 2048x2048, 3840x2160.
• quality — low, medium, high, xhigh, max или auto.
• output_format — png, jpeg или webp.
• background — auto, transparent или opaque. Используйте transparent вместе с output_format: png или webp, чтобы получить материал с вырезанным фоном.

Схема строгая — неизвестные поля (size, n или любые не перечисленные поля) возвращают 400 INVALID_REQUEST с additional properties '<field>' not allowed, а не игнорируются молча. Если вам нужно редактировать существующее изображение, а не генерировать из пустого промпта, hiapi предоставляет это как отдельный ID модели — вариант «изображение в изображение» см. на странице модели.

Режимы для продакшена

Используйте колбэки вместо опроса. Добавьте в запрос создания объект callback:

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" в настоящее время — единственное поддерживаемое значение: когда задача достигает success или fail, hiapi отправляет на ваш URL один POST-запрос. Тело колбэка полностью совпадает с полем data, возвращаемым GET /v1/tasks/:id.

Отправляйте заголовок Idempotency-Key. Если на вашей стороне запрос истекает по таймауту и повторяется, ключ идемпотентности не даёт hiapi создать (и списать оплату за) вторую задачу для того же запроса.

Обрабатывайте ошибки явно. Недействительный или отозванный ключ возвращает HTTP 401:

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

Некорректный input возвращает HTTP 400 с error_code: "INVALID_REQUEST" и message, указывающим на проблемное поле — проверьте его перед повтором: повтор с тем же телом запроса при 400 снова завершится неудачей.

Цены на gpt-image-2.5-flare@pro (оплата за успешно сгенерированные изображения в зависимости от разрешения и уровня качества) см. на странице цен.

Связанная документация

• Справочник по единому асинхронному API — полный жизненный цикл задачи, все типы моделей
• Создание задачи — структура запроса/ответа POST /v1/tasks
• Получение деталей задачи — опрос GET /v1/tasks/:id
• Аутентификация — формат ключа API и заголовки
• Страница модели gpt-image-2.5-flare@pro

Частые вопросы

В чём разница между маршрутом по умолчанию и @pro? Это два отдельных маршрута одной линейки моделей, выбираемые по отправленному вами ID модели (gpt-image-2.5-flare и gpt-image-2.5-flare@pro). Перед выбором посмотрите страницу модели и цены, чтобы узнать текущие различия в стоимости и возможностях.

Могу ли я генерировать прозрачные PNG? Да — установите "background": "transparent" вместе с "output_format": "png" (или "webp").

Почему я получаю additional properties 'size' not allowed? Схема строгая. Используйте aspect_ratio (оно также принимает явные размеры в пикселях, такие как 1024x1024), а не поле size.

Как долго действителен URL результата? До Unix-временной метки expireAt в объекте output[0]. До этого момента скачайте файл или скопируйте его в собственное хранилище — после этого hiapi больше не будет предоставлять этот файл.

Нужно ли опрашивать результат, если настроен колбэк? Нет, но вы всё равно можете опрашивать — GET /v1/tasks/:id работает нормально независимо от того, настроен ли колбэк, и это можно использовать для ручной проверки, если ваш эндпоинт колбэка пропустил доставку.

Что будет, если мой запрос содержит одновременно input_urls и некорректный prompt? Валидация выполняется для всего тела запроса до создания задачи — любое недопустимое поле (включая некорректные массивы медиа) вернёт 400, и задача не будет создана (и оплата не будет списана).