GPT Image 2.6 Sunburst

Создавайте или редактируйте изображение по тексту и с использованием до 16 референсных изображений: в 1K, 2K, 4K либо с точным размером в пикселях, — или короткую GIF-анимацию по промпту. Оплата по токенам, которые фактически ушли на генерацию; параметр 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. Сочетать эти способы нельзя.
• output_format: "gif" делает по одному промпту анимацию из 9 кадров по 200 мс; size задаёт кадр (512–960 px). Оплата за токены, как у обычного изображения.

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

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

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

Адрес 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"

"output_format": "gif"

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

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

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

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

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

Размер кадра: 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"). Проверка действует даже для значения по умолчанию другого поля.

GIF не использует ни то, ни другое: у него нет resolution и aspect_ratio, а его size — это размер одного кадра (от 512 до 960 px).

Создание GIF-анимации

Отправьте "output_format": "gif" и опишите в prompt объект и движение. Результат — короткая GIF-анимация из 9 кадров по 200 мс:

• Только по промпту. images отклоняется с ошибкой gpt-image-2.6-sunburst output_format "gif" is made from the prompt alone: leave out "images".
• Кадр можно задать. size — размер одного кадра: обе стороны кратны 16 и лежат в пределах от 512 до 960 px, например 768x768. Девять кадров рисуются как один лист 3x3, поэтому кадр меньше обычного изображения. Без size кадр выбирает модель. size вне диапазона отклоняется с ошибкой a gif frame's "size" edges must be between 512 and 960 pixels: its nine frames are rendered as one 3x3 sheet.
• Без разрешения и соотношения сторон. Не передавайте resolution и aspect_ratio: resolution, отличное от 1K, или aspect_ratio, отличное от auto, отклоняется с ошибкой gpt-image-2.6-sunburst output_format "gif" has a fixed size: leave out "resolution" (с названием переданного поля).
• Без управления кадрами. frame_count и frame_duration_ms не поддерживаются: unknown field: frame_count.
• Оплата за токены. GIF оплачивается как обычное изображение — по токенам, которые использовал его лист кадров 3x3 (ставки в таблице ниже).

Страница не обещает, что анимация зациклена. У сохранённого файла mime_type равен image/gif.

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

Эта модель работает только как задача. 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.6-sunburst","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.6-sunburst","input":{"model":"gpt-image-2.6-sunburst","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.6-sunburst","operation":"status","task_id":"<task_id>"}

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

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

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

• background, seed, enhance_prompt → field "background" is not supported by model gpt-image-2.6-sunburst (с переданным полем и названием вызванной модели). В GPT Image 2.6 нет поля background, поэтому прозрачный фон запросить нельзя.
• Любое другое неизвестное поле, например n, moderation или frame_count → unknown field: n. Поля n нет: одна задача создаёт одно изображение или один GIF.

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

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.6-sunburst",
  "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.6-sunburst",
  "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.6-sunburst",
  "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.6-sunburst",
  "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.6-sunburst",
  "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.6-sunburst",
  "prompt": "A flat illustration of a lighthouse on a cliff at dawn, pastel colours, clean shapes",
  "size": "1536x1024"
}'

GIF-анимация

Анимация из 9 кадров только по промпту: без images, resolution и aspect_ratio. size задаёт каждый кадр. Оплата за токены.

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.6-sunburst",
  "prompt": "A paper boat drifting on gentle blue waves, flat illustration, soft morning light",
  "output_format": "gif",
  "size": "768x768"
}'

Ответы

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

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

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.6-sunburst",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-sunburst",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.077328,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.077328
    },
    "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.6-sunburst",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-sunburst",
    "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.077328,
      "credits_settled": 0.077328,
      "credits_refunded": 0,
      "credits_charged": 0.077328
    },
    "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.6-sunburst",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-sunburst",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.077328,
      "credits_settled": 0,
      "credits_refunded": 0.077328,
      "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.6-sunburst",
  "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 может отличаться от резерва. Запрос, отклонённый до создания задачи, бесплатен.
• Неудачная задача возвращается полностью.
• GIF оплачивается за токены, как обычное изображение, — по токенам, которые использовал его лист кадров 3x3.
• Линия с фиксированной ценой gpt-image-2.6-sunburst-beta продаёт GPT Image 2.6 по одной цене за изображение по классу размера и одной цене за GIF, независимо от того, сколько использовала генерация.

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

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

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

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

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