GPT Image 2.5 Sunburst · API

Быстрый старт

Три шага: отправить задачу, опросить её и забрать ссылку на изображение. Замените YOUR_API_KEY своим ключом, и команды ниже заработают как есть.

Шаг 1 · Отправка (сразу возвращает id задачи, HTTP 202)

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-sunburst", "prompt": "Картина маслом: гавань в сумерках, заметные мазки, тёплая палитра", "size": "16:9", "resolution": "2K"}'

Ответ (HTTP 202)

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gpt-image-2.5-sunburst"
}

Шаг 2 · Опрашивайте каждые 2–3 секунды, пока status не станет succeeded или failed

curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ при успехе

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gpt-image-2.5-sunburst",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.5-sunburst"}
}

Шаг 3 · data[0].url — это изображение (PNG). Оно хранится 15 дней; чтобы пользоваться им дольше, скачайте его в своё хранилище.

Полный пример (Python: отправить, дождаться, сохранить на диск)

import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. отправка
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Картина маслом: гавань в сумерках, заметные мазки, тёплая палитра",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. опрос каждые 3 секунды до завершения
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. скачивание изображения
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gpt-image-2.5-sunburst.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

Аутентификация

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Чтобы начать, создайте API-ключ в консоли.

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

JSON-тело запроса POST /v1/images/generations:

Другие параметры OpenAI (background, output_format, response_format, style и т. п.) не влияют на цену, и их действие не гарантируется; результат всегда в PNG и возвращается в виде url.

Цена

Оплата за изображение; цена зависит только от уровня, а пропорция и режим (из текста или из изображения) на неё не влияют. Цена уровня резервируется при отправке и полностью возвращается, если задача завершится ошибкой. 1 кредит = $0.005.

Пропорции, разрешение и размер изображения

Пропорцию задаёт size, уровень — resolution. Изображение выдаётся ровно того размера, что указан в таблице: уровень задаёт длинную сторону, а вторая вычисляется по пропорции. Пропорции, которых нет в таблице, работают по тому же правилу.

• В 1K модель строит композицию в ближайшем горизонтальном, вертикальном или квадратном формате, а шлюз затем обрезает изображение по центру и масштабирует до размера из таблицы; чем дальше пропорция от 3:2, 2:3 или 1:1, тем больше обрезается по краям. Шлюз добавляет к вашему промпту фразу о пропорции (на английском), чтобы объект остался целым и по центру; всё, что обязательно должно сохраниться, держите подальше от краёв.
• Уровни, которые рисуются нативно (см. «Качество и исходное разрешение» ниже), рисуются сразу в вашей пропорции, поэтому края не обрезаются.
• В size можно указать и размер в пикселях (например, 1536x1024): изображение выдаётся ровно такого размера (с пропорциональным уменьшением, если длинная сторона больше 4096). Уровень тогда берётся из resolution, а без него — по длинной стороне: до 1536 — 1K, до 2048 — 2K, больше — 4K. resolution может повысить уровень, но не понизить, и не меняет итоговый размер, поэтому не сочетайте маленький размер с высоким уровнем.

Качество и исходное разрешение

• Без quality изображение рисуется с уровнем детализации OpenAI medium. В 1K можно выбрать low, medium или high — и для текста в изображение, и для изображения из изображения; 2K и 4K всегда рисуются в medium. Любое другое значение (auto, xhigh, max и т. п.) считается medium и никогда не вызывает ошибку. Цена зависит только от уровня разрешения и не зависит от quality.
• Если в quality указано 1K, 2K или 4K, а resolution не передан, это значение считается уровнем разрешения (размер и цена — по этому уровню).
• 1K рисуется в собственном кадре модели — около 1,57 мегапикселя (1254×1254 для квадрата), — и шлюз масштабирует его до размера из таблицы выше.
• 2K и 4K рисуются нативно в нужной вам пропорции — до 3840 px по стороне и около 8,3 мегапикселя: 2K 1:1 приходит как 2048×2048, 4K 16:9 — как 3840×2160, 4K 1:1 — как 2880×2880. Если размер 4K в таблице больше, шлюз увеличивает изображение до него (около 7% по каждой стороне для 16:9, больше для более квадратных пропорций); чтобы получить исходные пиксели без изменений, передайте в size размер в пикселях в этих пределах, например 3840x2160.
• Уровни, которые рисуются нативно, всегда рисуются только нативно: при высокой нагрузке задача ждёт в очереди, а если изображение всё равно не удаётся нарисовать, задача завершается ошибкой с полным возвратом средств — увеличенное изображение 1K вместо него не выдаётся.
• В 1K параметр quality иногда не действует.

Изображение из изображения и референсы

• Передайте image (одно изображение) или images (несколько, до 8; сверх 8 не используются) — и задача выполнится как изображение из изображения; в промпте напишите, что изменить. POST /v1/images/edits принимает те же параметры.
• Оба эндпоинта принимают только JSON-тело, а не загрузку файлов через multipart, поэтому images.edit() из OpenAI SDK напрямую не подойдёт: передавайте ссылки или base64, как в примере ниже.
• Каждый референс — это публичная ссылка на изображение (http или https), data: URI или просто base64, до 16MB каждый, в распространённом формате: JPEG, PNG, WebP и т. п.
• Ссылка должна отдавать само изображение, а не веб-страницу и не адрес за логином или с защитой от хотлинка. Референс, который не удаётся прочитать, отклоняется при отправке с ошибкой 400, где указано, какой именно и почему; задача не создаётся, ничего не списывается.
• Пропорцию результата задаёт size, а не референс. Чтобы сохранить исходную пропорцию, укажите её в size.
• Референсы мы размещаем у себя и храним 7 дней.

Изображение из изображения по двум референсам

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-sunburst", "prompt": "Сохрани людей, замени фон на ночной пляж с гирляндами тёплого света", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

Статус задачи и поля ответа

GET /v1/images/jobs/{id} возвращает эти статусы; все поля описаны в разделе Асинхронные задачи. Опрашивайте каждые 2–3 секунды или используйте вебхук.

Один аккаунт выполняет до 50 задач одновременно; остальные ждут в порядке отправки, а задача, не начавшаяся за 15 минут, завершается ошибкой с полным возвратом. Записи о задачах хранятся 3 дня, ссылки на изображения — 15 дней.

Сколько ждать

От отправки до результата 1K обычно занимает 20–60 секунд; 2K и 4K рисуются нативно и обычно занимают 30–120 секунд. Изображение из изображения и несколько референсов занимают больше времени, а задача, которую шлюз автоматически перезапустил, может занять несколько минут.

Реальные вызовы за последние 7 дн.: медиана 26 с, 90% завершаются за 43 с.

Ошибки и возвраты

Ошибка при отправке сразу возвращается как HTTP 4xx / 5xx: задача не создаётся, ничего не списывается. О неудаче после того, как задача принята, сообщает эндпоинт задачи, а резерв возвращается полностью. Все коды перечислены в разделе Коды ошибок.

Ошибки при отправке

Неудачные задачи (status — failed)

Вебхуки вместо опроса

Добавьте при отправке callback_url — как только задача завершится, успешно или с ошибкой, шлюз отправит на этот URL ровно то же, что возвращает эндпоинт опроса; запрос подписан, а при неудачной доставке повторяется. Общий адрес для всего аккаунта можно также задать в консоли, в разделе «Настройки → Вебхуки». Документация по вебхукам →

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-sunburst", "prompt": "Картина маслом: гавань в сумерках, заметные мазки, тёплая палитра", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'