GPT Image 2.5 Sunburst Standard

Создавайте или редактируйте изображение по тексту и с использованием до 16 референсных изображений: в 1K, 2K, 4K либо с точным размером в пикселях. Оплата по токенам, которые фактически ушли на генерацию; параметр quality задаёт число выходных токенов.

• Оплата по токенам: текстовый ввод, ввод изображений и выходные токены по тарифам за 1 млн токенов. Цены за изображение ниже — оценка при качестве medium.
• quality определяет, сколько выходных токенов уйдёт на генерацию, а значит и цену: чем ниже значение, тем дешевле. Без поля используется medium.
• Только асинхронно: создайте задачу через POST /v1/images/tasks, затем опрашивайте GET /v1/tasks/{task_id}. Генерация идёт на стороне BeatAPI, поэтому даже долгая генерация не держит ваше соединение. Синхронный POST /v1/images/generations для этой модели недоступен.
• Одна задача создаёт одно изображение. Для нескольких изображений создайте несколько задач.
• Генерация по тексту либо редактирование и объединение до 16 референсных изображений по общедоступным HTTPS-ссылкам.
• Задайте кадр через resolution и aspect_ratio либо одним точным size, например 1536x1024. Сочетать эти способы нельзя.

Открывает модель в API Explorer. Введите свой API-ключ BeatAPI, чтобы создать задачу. Это настоящий запрос: его стоимость спишется с вашего баланса.

Идентификаторы моделей

Модель с фиксированной ценой и эта модель принимают один и тот же запрос; различаются только quality и способ расчёта цены. Значения ниже взяты прямо из контракта шлюза.

Адрес API и авторизация

POST https://api.beatapi.io/v1/images/tasks

Передавайте тело запроса в JSON с заголовком Content-Type: application/json. Idempotency-Key необязателен. Для каждого логического запроса используйте уникальное значение длиной не более 255 символов и повторно используйте его только для отправки точно такого же тела. В течение 24 часов повтор с тем же ключом и телом возвращает первый ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом возвращает 409 idempotency_conflict. Ответы, отличные от 2xx, не сохраняются, поэтому повтор после 400 или 402 выполняется заново.

Как выполняется запрос

Режимы ввода

Параметры запроса

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]

"size": "1536x1024"

"quality": "low"

Перед созданием задачи шлюз также проверяет следующие сочетания параметров:

• size задаётся как WIDTHxHEIGHT и заменяет resolution и aspect_ratio. Обе стороны кратны 16 и находятся в диапазоне 16–3840 пикселей; общее число пикселей — 655 360–8 294 400, отношение длинной стороны к короткой — не более 3:1.
• Размер оплачивается по токенам, которые расходует генерация, а не по уровню разрешения.
• quality задаёт число выходных токенов, а значит и цену; по умолчанию medium.
• Оплата по токенам по прейскурантным тарифам за токены, которые расходует каждая генерация (текстовый ввод, ввод изображений, вывод); указанные цены за изображение — оценка при качестве medium.
• Это официальная версия с оплатой по токенам: принимает quality low, medium, high, xhigh, max; gpt-image-2.5-sunburst (фиксированная цена за изображение) такого не поддерживает.

Ограничения входных материалов

До создания задачи шлюз проверяет каждый входной материал. Если ограничение нарушено, возвращается 400 bad_request с указанием материала. Средства не списываются.

• Референсные изображения: PNG, JPEG или WebP с определением формата по содержимому; до 50 MB каждый (десятичные мегабайты; проверяется, если сервер сообщает размер), от 1 до 16 ссылок. GIF, HEIC и SVG отклоняются.
• Для самих референсных изображений ограничения числа пикселей и соотношения сторон не проверяются.
• Если сервер не ответил вовремя, ссылка не отклоняется при создании. Шлюз скачивает её повторно при запуске обработки. Если скачать по-прежнему нельзя, задача завершается ошибкой с возвратом средств.
• Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url.

Размер кадра: resolution и aspect_ratio либо size

Размер и пропорции изображения можно задать двумя взаимоисключающими способами:

• Класс и пропорции. Передайте resolution (1K, 2K или 4K) и при необходимости aspect_ratio. Без обоих полей используются 1K и auto, то есть квадратный кадр.
• Точный размер. Передайте только size, например 1536x1024. Число пикселей меняет число выходных токенов; до расчёта резервируется оценка класса, в который попадает размер (см. правила сочетания выше).

Передача size вместе с resolution или aspect_ratio отклоняется с сообщением "size" already fixes the output; do not send "resolution" with it (либо "aspect_ratio"). Проверка действует даже для значения по умолчанию другого поля.

Создать задачу и опрашивать

Эта модель работает только как задача. POST /v1/images/tasks отвечает сразу, идентификатор задачи — в data.id; затем вызывайте GET /v1/tasks/{task_id} каждые data.poll_after_seconds, пока data.status не станет succeeded или failed. Генерация идёт на стороне BeatAPI, поэтому даже долгая генерация не держит ваше соединение и не упирается в тайм-аут клиента. Синхронный POST /v1/images/generations для этой модели недоступен.

# 1. Create the task. The call returns at once; the task ID is in data.id.
TASK_ID=$(curl -sS -X POST https://api.beatapi.io/v1/images/tasks \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2.5-sunburst-std","prompt":"A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field","resolution":"2K","quality":"medium"}' | jq -r '.data.id')
# 2. Poll until the task is final. The render runs on BeatAPI, not on this connection.
while true; do
  TASK=$(curl -sS "https://api.beatapi.io/v1/tasks/$TASK_ID" -H "Authorization: Bearer $BEATAPI_API_KEY")
  STATUS=$(echo "$TASK" | jq -r '.data.status')
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then break; fi
  sleep 5
done
echo "$TASK" | jq '.data.output.media[].url, .data.usage'

Через Capabilities API это та же задача: запустите её через POST /v1/capabilities/run, затем отправляйте запрос статуса с полученным идентификатором задачи, пока не будет succeeded или failed.

{"reference":"model:gpt-image-2.5-sunburst-std","input":{"model":"gpt-image-2.5-sunburst-std","prompt":"A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field","resolution":"2K","quality":"medium"}}

{"reference":"model:gpt-image-2.5-sunburst-std","operation":"status","task_id":"<task_id>"}

Оплата по токенам и фиксированная цена

Параметры, которые модель не принимает

Эндпоинт изображений знает несколько полей, которые используют другие модели изображений. Такое поле здесь отклоняется, а не игнорируется, чтобы вы не платили за настройку без эффекта:

• seed, output_format, enhance_prompt → field "seed" is not supported by model gpt-image-2.5-sunburst-std (с названием переданного поля). Формат результата выбрать нельзя: смотрите mime_type в результате.
• Любое другое неизвестное поле, например n или moderation → unknown field: n. Поля n нет: одна задача создаёт одно изображение.

В отличие от модели с фиксированной ценой gpt-image-2.5-sunburst, эта модель принимает quality.

Примеры запросов

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst-std",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K",
  "quality": "medium"
}'

Изображение по тексту

Горизонтальное изображение в 2K по промпту, с указанием класса и пропорций.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst-std",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K",
  "quality": "medium"
}'

Черновик в низком качестве

Первый запрос с quality: "low" и 1K: выходных токенов меньше, цена ниже. Подходит для черновиков и предпросмотра.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst-std",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "1K",
  "quality": "low"
}'

Редактирование одного изображения

Изменение фона с сохранением товара. Пропорции заданы явно, поскольку auto создаёт квадрат.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst-std",
  "prompt": "Keep the bottle exactly as it is. Replace the background with a sunlit kitchen counter and add a soft reflection under the bottle.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "1:1",
  "resolution": "1K"
}'

Объединение нескольких изображений

Укажите каждый референс в промпте по его порядку.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst-std",
  "prompt": "Place the bottle from the first image on a neon-lit stage like the one in the second image. Keep the bottle label readable.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "2K"
}'

Точный размер

Кадр 1536x1024. Передаётся только size, без resolution и aspect_ratio. Резервируется оценка для 1K.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst-std",
  "prompt": "A flat illustration of a lighthouse on a cliff at dawn, pastel colours, clean shapes",
  "size": "1536x1024"
}'

Прозрачный фон

Объект в стиле стикера без фона. Результат — PNG с альфа-каналом.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst-std",
  "prompt": "A single cartoon red fox sitting, sticker style, thick white outline, isolated on a transparent background",
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "background": "transparent"
}'

Ответы

Создание задачи (201)

Объект задачи. Поле output равно null, пока задача не завершится успешно. Поля с пометкой «во время выполнения» исчезают после завершения задачи.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.5-sunburst-std",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.5-sunburst-std",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.017394,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.017394
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Успешно завершённая задача

GET /v1/tasks/{task_id} возвращает HTTP 200 со status: "succeeded" и результатом в data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.5-sunburst-std",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.5-sunburst-std",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "image",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png",
          "mime_type": "image/png"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png"
    },
    "usage": {
      "credits_reserved": 0.017394,
      "credits_settled": 0.017394,
      "credits_refunded": 0,
      "credits_charged": 0.017394
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Поля результата

Задача, завершившаяся ошибкой

Если задача завершилась ошибкой, GET /v1/tasks/{task_id} всё равно возвращает HTTP 200: сведения об ошибке находятся в теле ответа. Зарезервированная сумма возвращается полностью, поэтому списания нет.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.5-sunburst-std",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.5-sunburst-std",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.017394,
      "credits_settled": 0,
      "credits_refunded": 0.017394,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Полный пример

Создайте задачу, дождитесь её завершения с интервалом опроса, указанным сервером, и выведите ссылки на результаты. Задайте BEATAPI_API_KEY в переменной окружения и установите requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/images/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "gpt-image-2.5-sunburst-std",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K",
  "quality": "medium"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Оплата

• Оплата по токенам по тарифам за 1 млн токенов из таблицы ниже: текстовый ввод (промпт), ввод изображений (референсы в images) и вывод (само изображение). Токены считает модель; quality, кадр и референсные изображения меняют их число.
• Цены за изображение — оценка одной генерации при качестве medium в квадратном кадре каждого класса без референсных изображений. low расходует меньше выходных токенов, более высокие значения — больше.
• При создании задачи с баланса (и с квоты ключа, если она задана) резервируется оценка для её класса. При успехе списание пересчитывается по токенам, которые фактически ушли на генерацию, поэтому итоговый data.usage может отличаться от резерва. Запрос, отклонённый до создания задачи, бесплатен.
• Неудачная задача возвращается полностью.
• Модель с фиксированной ценой gpt-image-2.5-sunburst — та же модель по одной цене за изображение, сколько бы токенов ни ушло на генерацию.

Текущие базовые цены совпадают с указанными на странице цен. Если для аккаунта согласована скидка, стоимость будет ниже. Фактически списанная сумма всегда указана в data.usage задачи.

Частые ошибки

Краткий справочник HTTP-ошибок

Ошибки до создания задачи возвращаются с HTTP-статусом, отличным от 2xx, без списания средств. Обрабатывайте error.code или error.retryable; причина указана в message. Полный список и правила повторов приведены в разделе ошибок.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}