curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "уютный уголок для чтения у дождливого окна, теплый свет лампы",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Некорректные параметры запроса",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Ошибка аутентификации. Проверьте ключ API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Недостаточно средств на счете",
    "type": "payment_required"
  }
}

GPT-Image-2.5

Генерация изображений GPT-Image-2.5

Модели gpt-image-2.5-flare и gpt-image-2.5-sunburst
Асинхронная обработка с task_id для получения результата
Генерация по тексту и редактирование с 16 референсами
Локальная перерисовка с прозрачной PNG-маской
15 соотношений сторон, точные размеры и разрешения 1K / 2K / 4K
Качество low / medium / high / xhigh / max

POST

images

generations

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "уютный уголок для чтения у дождливого окна, теплый свет лампы",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Некорректные параметры запроса",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Ошибка аутентификации. Проверьте ключ API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Недостаточно средств на счете",
    "type": "payment_required"
  }
}

Выбор модели: gpt-image-2.5-flare работает быстрее и подходит для повседневной генерации, больших серий и прототипов. gpt-image-2.5-sunburst ставит на первое место точность редактирования и подходит для готовых товарных изображений, рекламы и детальных многоэтапных правок. Тарифы обеих моделей одинаковы.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "уютный уголок для чтения у дождливого окна, теплый свет лампы",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Некорректные параметры запроса",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Ошибка аутентификации. Проверьте ключ API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Недостаточно средств на счете",
    "type": "payment_required"
  }
}

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

string

обязательно

Все методы используют Bearer Token. Получите ключ на странице ключей API.

Authorization: Bearer YOUR_API_KEY

Выбор модели

Модель	Особенность	Рекомендуемые задачи
`gpt-image-2.5-flare`	Быстрая модель по умолчанию	Соцсети, товары, визуальный поиск, прототипы и пакетная генерация
`gpt-image-2.5-sunburst`	Точное редактирование	Финальные товарные изображения, реклама и многоэтапная правка

При одинаковых параметрах расход токенов и цена совпадают. По сравнению с gpt-image-2 добавлены уровни xhigh и max, а уровни medium и high требуют примерно в четыре раза меньше выходных токенов, чем одноименные уровни предыдущего поколения.

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

string

обязательно

gpt-image-2.5-flare или gpt-image-2.5-sunburst.

string

обязательно

Текстовое описание создаваемого или редактируемого изображения. Укажите объект, сцену, композицию, стиль, освещение и необходимые изменения.

string

по умолчанию:"auto"

Соотношение сторон или точные размеры в пикселях.

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
Точные размеры, например 1600x1200

При редактировании изображения можно не передавать size: размеры будут рассчитаны по референсу и resolution.

string

по умолчанию:"1k"

Уровень разрешения: 1k, 2k или 4k. Игнорируется при точных размерах.

string

по умолчанию:"auto"

Качество: low, medium, high, xhigh, max или auto.

xhigh и max доступны только в GPT-Image-2.5. Для gpt-image-2 запрос завершится HTTP 400 без автоматического снижения качества.

integer

по умолчанию:"1"

Количество изображений: от 1 до 4. Передавайте число, а не строку.

string

по умолчанию:"png"

Формат: png, jpeg или webp.

integer

Сжатие от 0 до 100, только для jpeg и webp.

string

Фон: transparent, opaque или auto.

Для transparent требуется png или webp; JPEG не поддерживает альфа-канал.

string

по умолчанию:"low"

Уровень модерации: auto или low. Если параметр не задан, APIMart явно отправляет low; явно указанное auto передается без изменений.

string[]

URL референсов для генерации или редактирования, не более 16. Наличие поля включает режим редактирования.Принимаются только общедоступные HTTP(S)-URL. Локальный файл сначала загрузите через POST /v1/uploads/images, затем используйте полученный url.

string

Маска для локальной перерисовки. Действует только вместе с image_urls. Параметр поддерживают обе модели: gpt-image-2.5-flare и gpt-image-2.5-sunburst.Передайте одну строку в одном из форматов:

HTTP(S)-URL изображения, которое сервер может скачать напрямую
PNG Data URL вида data:image/png;base64,...

Требования к маске:

Используйте PNG с прозрачным альфа-каналом; исходное изображение также рекомендуется хранить в PNG
Размер в пикселях должен точно совпадать с image_urls[0]. Сопоставляется первое входное изображение, а не выходной size
Полностью прозрачные пиксели (alpha=0) обозначают область изменения; остальные области используются для сохранения
В одном запросе передается одна маска. При нескольких референсах она применяется только к первому входному изображению
В общем руководстве указан размер менее 50 MB, а в описании параметра mask — менее 4 MB. До проверки используйте более строгое ограничение 4 MB

Обычное черно-белое изображение без альфа-канала нельзя использовать как маску напрямую. APIMart не добавляет альфа-канал и сейчас не проверяет заранее совпадение размеров маски с исходным изображением; это должен обеспечить вызывающий клиент.

HTTP(S)-URL должен открываться без Cookie и дополнительных заголовков авторизации. Срок действия подписанного URL должен покрывать ожидание в очереди и выполнение. По умолчанию загрузка ограничена 20 MB, а тайм-аут составляет 60 секунд; настройки развертывания могут изменить эти значения.Маска направляет редактирование, но модель не гарантирует полного сохранения пикселей за ее границей.

Ограничения размера

Ширина и высота кратны 16
Каждая сторона не превышает 3840 пикселей
Отношение длинной стороны к короткой не превышает 3:1
Общее число пикселей — от 655 360 до 8 294 400

Разрешения выше 2560×1440 являются экспериментальными и могут быть менее стабильными.

Соотношения и разрешения

`size`	`1k`	`2k`	`4k`
`1:1`	1024×1024	2048×2048	2880×2880
`3:2`	1536×1024	2048×1360	3520×2336
`2:3`	1024×1536	1360×2048	2336×3520
`4:3`	1024×768	2048×1536	3312×2480
`3:4`	768×1024	1536×2048	2480×3312
`5:4`	1280×1024	2560×2048	3216×2576
`4:5`	1024×1280	2048×2560	2576×3216
`16:9`	1536×864	2048×1152	3840×2160
`9:16`	864×1536	1152×2048	2160×3840
`2:1`	2048×1024	2688×1344	3840×1920
`1:2`	1024×2048	1344×2688	1920×3840
`21:9`	2016×864	2688×1152	3840×1648
`9:21`	864×2016	1152×2688	1648×3840
`3:1`	1536×512	3072×1024	3840×1280
`1:3`	512×1536	1024×3072	1280×3840

Можно передать любые другие точные размеры, удовлетворяющие всем ограничениям.

Пример редактирования

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "сохранить товар и текст на упаковке, заменить фон на светлую студию и добавить естественную тень",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

Локальная перерисовка по маске

В этом примере изменяется только полностью прозрачная область маски. Размер маски должен совпадать с product.png.

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "заменить только область прозрачной маски на золотую ленту, сохранив товар и остальной фон",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "quality": "xhigh"
}

Отправка и проверка задачи

После успешной отправки ID находится в data[0].task_id. Проверяйте статус задачи каждые 2–5 секунд до completed или failed. Для нескольких задач используйте POST /v1/tasks/batch.

{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "result": {
      "images": [{
        "url": ["https://upload.apimart.ai/f/image/example.png"],
        "expires_at": 1789000000
      }]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}

URL изображений находятся в data.result.images[].url[]. Скачайте и сохраните файлы как можно скорее.

Статус	Значение
`submitted`	Задача отправлена
`processing`	Генерация выполняется
`completed`	Успех, доступен `result.images`
`failed`	Ошибка; проверьте `error.message`; резерв возвращается

Оплата

GPT-Image-2.5 тарифицируется по фактическим токенам. Текущую цену для аккаунта смотрите на странице тарифов или в /api/pricing.

Статья	Цена за 1 млн токенов
Выход изображения	$30.00
Вход изображения	$8.00
Кэшированный вход изображения	$2.00
Текстовый вход	$5.00
Кэшированный текстовый вход	$1.25

`quality` при 1024×1024	Выходные токены	Официальная стоимость
`low`	196	$0.00588
`medium`	439	$0.01317
`high`	1756	$0.05268
`xhigh`	3122	$0.09366
`max`	7024	$0.21072

При quality: "auto" сначала резервируется сумма по уровню max для выбранного размера. После завершения расчет выполняется по фактическому расходу, а разница освобождается.

При n > 1 резерв растет линейно. Неудачные задачи возвращают средства автоматически.

Лимиты и частые ошибки

Пункт	Ограничение или решение
Изображений в запросе	1–4
Референсов	Не более 16
Формат	PNG / JPEG / WebP
Прозрачный фон	Только PNG / WebP
Поток частичных изображений	Не поддерживается
Недопустимое качество	`xhigh` / `max` требуют GPT-Image-2.5
Недопустимый размер	Используйте кратные 16 размеры в допустимом диапазоне

Response

integer

Код ответа; 200 при успешной отправке.

array

Данные ответа на отправку.

Показать Элемент массива

string

Начальный статус — submitted.

string

Уникальный ID для проверки статуса и результата.

Обзор

Модели

Текстовая серия

Серия изображений

Видеосерия

Аудиосерия

Серия модерации

Управление загрузками

Управление задачами

Управление аккаунтом

Генерация изображений GPT-Image-2.5

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

Выбор модели

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

Ограничения размера

Соотношения и разрешения

Пример редактирования

Локальная перерисовка по маске

Отправка и проверка задачи

Оплата

Лимиты и частые ошибки

Response

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

​Выбор модели

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

​Ограничения размера

​Соотношения и разрешения

​Пример редактирования

​Локальная перерисовка по маске

​Отправка и проверка задачи

​Оплата

​Лимиты и частые ошибки

​Response

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

Выбор модели

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

Ограничения размера

Соотношения и разрешения

Пример редактирования

Локальная перерисовка по маске

Отправка и проверка задачи

Оплата

Лимиты и частые ошибки

Response