GPT Image 2.5 API

Краткое практическое введение

GPT Image 2.5 создаёт изображения по текстовому заданию и помогает редактировать готовые картинки по референсам. Через API удобно запускать:

• генерацию с нуля - например, иллюстрацию, рекламный баннер, карточку товара или концепт персонажа;
• редактирование по изображениям - например, сохранить объект, стиль или композицию и изменить детали по инструкции;
• подготовку результата в нужном формате - PNG, JPEG или WebP, с выбранным качеством, разрешением, фоном и сжатием.

Каждый вызов создаёт асинхронную операцию. В ответ на создание вы сразу получаете id и стартовый статус, а готовые ссылки на изображения забираете отдельным запросом проверки статуса.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Запрос создаёт новую операцию и сразу возвращает id, стартовый статус и стоимость.
• Выполнение асинхронное.

Доступны два режима модели:

• flare - быстрый режим для повседневной генерации, серий картинок и прототипов;
• sunburst - режим для более точного редактирования, финальных рекламных изображений и сцен, где важна аккуратность деталей.

Тело запроса

Базовая форма запроса:

{
  "tool": "gpt-image-2-5",
  "input": {
    "...": "..."
  }
}

• tool - slug нейросети. Для этой модели всегда используйте "gpt-image-2-5".
• input - параметры конкретного запуска.
• Параметры передаются напрямую внутри input. Дополнительная вложенность не нужна.

Параметры

Параметр	Тип	Обязательный	Описание
model_variant	enum	Да	Режим модели. Варианты: flare, sunburst.
prompt	string	Да	Текстовое задание для генерации или редактирования. Опишите объект, стиль, композицию, свет, ограничения и нужные изменения. От 3 до 20000 символов.
image_urls	string[] (url)	Нет	Массив внешних URL изображений для редактирования или референсов. Можно передать до 16 файлов. Разрешены только http/https ссылки. Допустимые расширения для Public API: .jpg, .jpeg, .png, .webp.
quality	enum	Да	Качество результата. Варианты: low, medium, high, xhigh, max. Чем выше качество, тем больше деталей и выше цена.
size	enum	Да	Соотношение сторон итогового изображения. Варианты: auto, 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3.
resolution	enum	Да	Разрешение результата. Варианты: 1k, 2k, 4k. Влияет на размер изображения и стоимость.
output_format	enum	Да	Формат готового изображения. Варианты: png, jpeg, webp.
background	enum	Да	Настройка фона. Варианты: auto, opaque, transparent.
output_compression	number	Да	Уровень сжатия от 0 до 100. Применяется к jpeg и webp. Для png параметр не влияет на результат.
moderation	enum	Да	Режим проверки запроса. Варианты: low, auto. Auto включает более строгую автоматическую проверку.

Прозрачный фон используйте только с output_format = png или webp. Для jpeg выбирайте background = auto или opaque.

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

Сценарий 1. Генерация без изображений

Используйте этот вариант, когда нужно создать картинку только по текстовому описанию.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "gpt-image-2-5",
    "input": {
      "model_variant": "flare",
      "prompt": "Крупный план керамической чашки с матовой глазурью на деревянном столе, утренний мягкий свет, чистый минималистичный фон, реалистичная предметная фотография",
      "quality": "medium",
      "size": "1:1",
      "resolution": "2k",
      "output_format": "png",
      "background": "auto",
      "output_compression": 80,
      "moderation": "low"
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gpt-image-2-5',
    input: {
      model_variant: 'flare',
      prompt:
        'Крупный план керамической чашки с матовой глазурью на деревянном столе, утренний мягкий свет, чистый минималистичный фон, реалистичная предметная фотография',
      quality: 'medium',
      size: '1:1',
      resolution: '2k',
      output_format: 'png',
      background: 'auto',
      output_compression: 80,
      moderation: 'low',
    },
  }),
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    "https://bratuha.ru/api/v1/operations",
    headers={
        "Authorization": "Bearer brth_ваш_ключ",
        "Content-Type": "application/json",
    },
    json={
        "tool": "gpt-image-2-5",
        "input": {
            "model_variant": "flare",
            "prompt": "Крупный план керамической чашки с матовой глазурью на деревянном столе, утренний мягкий свет, чистый минималистичный фон, реалистичная предметная фотография",
            "quality": "medium",
            "size": "1:1",
            "resolution": "2k",
            "output_format": "png",
            "background": "auto",
            "output_compression": 80,
            "moderation": "low",
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 2. Редактирование или генерация по референсам

Передайте image_urls, когда нужно изменить готовое изображение или использовать несколько картинок как визуальные ориентиры. В массиве ниже показаны две ссылки, но можно передать до 16 изображений.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "gpt-image-2-5",
    "input": {
      "model_variant": "sunburst",
      "prompt": "Сохранить форму товара и ракурс с первого изображения, взять цветовую палитру со второго изображения, заменить фон на светлую студию и добавить мягкую тень под объектом",
      "image_urls": [
        "https://cdn.example.com/source-image-1.jpg",
        "https://cdn.example.com/source-image-2.png"
      ],
      "quality": "high",
      "size": "4:5",
      "resolution": "2k",
      "output_format": "webp",
      "background": "opaque",
      "output_compression": 80,
      "moderation": "low"
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gpt-image-2-5',
    input: {
      model_variant: 'sunburst',
      prompt:
        'Сохранить форму товара и ракурс с первого изображения, взять цветовую палитру со второго изображения, заменить фон на светлую студию и добавить мягкую тень под объектом',
      image_urls: [
        'https://cdn.example.com/source-image-1.jpg',
        'https://cdn.example.com/source-image-2.png',
      ],
      quality: 'high',
      size: '4:5',
      resolution: '2k',
      output_format: 'webp',
      background: 'opaque',
      output_compression: 80,
      moderation: 'low',
    },
  }),
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    "https://bratuha.ru/api/v1/operations",
    headers={
        "Authorization": "Bearer brth_ваш_ключ",
        "Content-Type": "application/json",
    },
    json={
        "tool": "gpt-image-2-5",
        "input": {
            "model_variant": "sunburst",
            "prompt": "Сохранить форму товара и ракурс с первого изображения, взять цветовую палитру со второго изображения, заменить фон на светлую студию и добавить мягкую тень под объектом",
            "image_urls": [
                "https://cdn.example.com/source-image-1.jpg",
                "https://cdn.example.com/source-image-2.png",
            ],
            "quality": "high",
            "size": "4:5",
            "resolution": "2k",
            "output_format": "webp",
            "background": "opaque",
            "output_compression": 80,
            "moderation": "low",
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания операции

{
  "id": "5f7d4d7f-0f2c-4a63-9d8e-7d9c6b2a1f10",
  "status": "queued",
  "tool": "gpt-image-2-5",
  "cost": 12,
  "balance_after": 488,
  "created_at": "2026-09-09T07:30:00.000Z"
}

Ответ после завершения операции

{
  "id": "5f7d4d7f-0f2c-4a63-9d8e-7d9c6b2a1f10",
  "status": "completed",
  "tool": "gpt-image-2-5",
  "cost": 12,
  "created_at": "2026-09-09T07:30:00.000Z",
  "completed_at": "2026-09-09T07:30:38.000Z",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/gpt-image-2-5/image-1.webp"
    ]
  },
  "error_message": null
}

Ответ при ошибке выполнения

{
  "id": "5f7d4d7f-0f2c-4a63-9d8e-7d9c6b2a1f10",
  "status": "failed",
  "tool": "gpt-image-2-5",
  "cost": 12,
  "created_at": "2026-09-09T07:30:00.000Z",
  "completed_at": "2026-09-09T07:30:12.000Z",
  "result": null,
  "error_message": "Не удалось выполнить операцию"
}

Проверка статуса

Проверяйте статус по id, который вернулся после создания операции. Сохраните этот id у себя: без него нельзя получить результат конкретного запуска.

cURL

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/5f7d4d7f-0f2c-4a63-9d8e-7d9c6b2a1f10

JavaScript / TypeScript

const operationId = '5f7d4d7f-0f2c-4a63-9d8e-7d9c6b2a1f10'

const response = await fetch(
  `https://bratuha.ru/api/v1/operations/${operationId}`,
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  },
)

const operation = await response.json()
console.log(operation)

Формат результата

После успешного выполнения в result возвращается объект изображения:

{
  "type": "image",
  "urls": [
    "https://storage.bratuha.ru/results/gpt-image-2-5/image-1.webp"
  ]
}

urls - массив ссылок на готовые изображения. Для текущей схемы один запуск создаёт одно изображение, поэтому в массиве обычно один URL. Формат файла зависит от output_format: png, jpeg или webp.

Ценообразование

Базовая цена начинается от 2 ₽ за одно изображение. Итоговая стоимость зависит от пары параметров quality и resolution; соотношение сторон, формат файла, фон, сжатие и режим модерации цену не меняют.

Качество	1k	2k	4k
low	2 ₽	2 ₽	4 ₽
medium	4 ₽	4 ₽	8 ₽
high	16 ₽	12 ₽	31 ₽
xhigh	29 ₽	22 ₽	54 ₽
max	64 ₽	48 ₽	121 ₽

Примеры:

• quality = low, resolution = 1k или 2k - 2 ₽;
• quality = high, resolution = 2k - 12 ₽;
• quality = max, resolution = 4k - 121 ₽.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: повторный запрос создаёт новую операцию и повторно списывает стоимость.
• Операция выполняется асинхронно. Не ждите готовую картинку в ответе на POST; используйте GET /api/v1/operations/{id}.
• Для image_urls нужны внешние http/https URL, доступные серверу. Локальные пути, localhost, private IP, blob: и data: не подходят.
• Для Public API используйте изображения .jpg, .jpeg, .png или .webp.
• Если передаёте несколько референсов, ставьте главный исходник первым в массиве image_urls и явно объясняйте в prompt, что нужно взять с каждого изображения.
• Для прозрачного фона выбирайте output_format = png или webp и background = transparent.
• Для jpeg и webp используйте output_compression от 0 до 100; для png этот параметр можно оставить со стандартным значением.