Как использовать gpt-image-2-beta через hiapi API: параметры, код и рабочий пример

gpt-image-2-beta — это минималистичный маршрут с фиксированной ценой для доступа к GPT Image 2 на hiapi: два входных поля, одна цена, без регулировки соотношения сторон или качества. В этом руководстве показан минимальный рабочий пример, точная структура параметров (подтверждённая зондированием работающего эндпоинта), а также сравнение с маршрутом по умолчанию gpt-image-2/text-to-image, чтобы вы могли решить, когда какой использовать.

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

Вам нужен API-ключ со страницы API Keys в панели управления hiapi — ключи начинаются с sk-. Актуальную цену за одно изображение смотрите на странице модели gpt-image-2-beta и на странице тарифов.

Как и любая модель изображений на hiapi, эта модель работает на едином эндпоинте асинхронных задач:

• POST https://api.hiapi.ai/v1/tasks — создание задачи генерации
• GET https://api.hiapi.ai/v1/tasks/{taskId} — опрос статуса задачи

Чем отличается beta-маршрут

gpt-image-2/text-to-image (маршрут по умолчанию) принимает aspect_ratio + resolution и тарифицируется по уровню разрешения ($0.03 за 1K, до $0.06 за 4K). gpt-image-2-beta сводит всё это к единой фиксированной цене $0.02 за изображение и одному необязательному полю size — буквальная строка пиксельных размеров, например "1024x1024" или "1600x900", а не пропорция. Если полностью опустить size, модель вернётся к своему размеру вывода по умолчанию.

Цена этого: вы отказываетесь от тонкого контроля пропорций и разрешения в обмен на более низкую и простую цену. Это подходит, когда вам нужно просто «недорого сгенерировать изображение», а точная композиция не важна.

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

# 1. Создать задачу
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-beta",
    "input": {
      "prompt": "бумажный самолётик, взлетающий со стопки документов, плоская векторная иллюстрация",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Опрашивать до status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

Готовое изображение находится в data.output[0].url. Этот URL имеет короткий срок действия expireAt — немедленно скачайте и переразместите его в своём хранилище; не ссылайтесь на него напрямую в производственном контенте.

Пример изображения, сгенерированного приведённым выше вызовом curl (с другим промптом), с size: "1024x1024".

Python: создание + опрос + сохранение на диск

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # например "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("талисман-рыжий панда, читающий книгу, плоская пастельная иллюстрация", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

Справочник параметров

Объект input для gpt-image-2-beta принимает только два поля — эта структура имеет additionalProperties: false, поэтому любое другое содержимое будет напрямую отклонено, а не молча проигнорировано.

Поле	Тип	Обязательное	Описание
prompt	string	Да	Текстовое описание изображения для генерации.
size	string	Нет	Буквальные пиксельные размеры, например "1024x1024", "1600x900". Не ключевое слово соотношения сторон. Если опустить — используется размер вывода модели по умолчанию.

Что не поддерживается (и какие ошибки вы получите)

Структура beta не принимает никаких полей, используемых маршрутом по умолчанию gpt-image-2/text-to-image или OpenAI Images API — aspect_ratio, resolution, quality, background, moderation, output_format, output_compression, n, user или style. Отправка любого из них немедленно возвращает HTTP 400, например:

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'quality', 'aspect_ratio' not allowed"
}

Если вы переносите код с маршрута по умолчанию или из OpenAI Images API, сначала сократите его до prompt + size, а затем направьте на gpt-image-2-beta.

Цены: beta vs по умолчанию vs @ext

Маршрут	Цена	Параметры управления
gpt-image-2-beta	$0.02/изображение, фиксированно	Только size (пиксельные размеры)
gpt-image-2/text-to-image (по умолчанию)	$0.03 (1K) / $0.04 (2K) / $0.06 (4K)	aspect_ratio + resolution
gpt-image-2/text-to-image@ext	$0.007–$0.76, в зависимости от качества × разрешения	16 соотношений сторон, уровни качества

Перед выбором маршрута для производства проверьте страницу тарифов — цены на любую модель могут меняться.

Советы по разработке на beta-маршруте

• Рассматривайте приведённый выше список полей как текущее соглашение, а не постоянное. Структура или цены beta-маршрута более подвержены изменениям, чем у маршрута по умолчанию — если вы зависите от него в производстве, регулярно перепроверяйте страницу модели.
• Поскольку size необязателен, если ваш макет зависит от конкретного размера, всегда передавайте его явно — не полагайтесь на то, что текущее значение по умолчанию останется неизменным.
• Обрабатывайте status: "fail" так же, как для любой другой модели изображений hiapi: читайте task.error.code / task.error.message и повторяйте попытки с экспоненциальной задержкой, а не предполагайте, что каждый сбой временный.

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

gpt-image-2-beta и gpt-image-2/text-to-image — это одна и та же модель? В основе — одна и та же модель GPT Image 2, но API-маршруты разные: beta-маршрут обменивает управление параметрами на фиксированную, более низкую цену.

Могу ли я запросить конкретное соотношение сторон? Напрямую — нет. Выберите строку size с нужным вам соотношением ширины к высоте (например, "1600x900" для 16:9), а не используйте перечисление aspect_ratio.

Что произойдёт, если вообще не передавать size? Задача всё равно выполнится — модель использует свой размер вывода по умолчанию.

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

Для полнофункционального маршрута с явным контролем соотношения сторон и разрешения см. Как использовать gpt-image-2/text-to-image через hiapi API. Готовы попробовать сами? Получите ключ на странице API Keys и запустите приведённый выше пример curl.