Многие разработчики при интеграции API для редактирования изображений gpt-image-2 сталкиваются с одной и той же проблемой: в справочнике API Reference для images/edit указано лишь то, что «модели GPT image поддерживают до 16 изображений», но нет ни слова о лимитах размера для каждого файла. Есть ли ограничения? Или документация неполная?
Ответ прост: ограничения существуют, и они вполне конкретны — размер каждого изображения должен быть менее 50 МБ, поддерживаются форматы PNG, WebP и JPG. Просто это правило вынесено не в таблицу параметров API Reference, а в отдельное руководство по использованию Image Generation. Из-за того, что информация разбросана по разным документам, многие разработчики заходят в тупик.
В этой статье мы разберем ограничения на загрузку изображений в API gpt-image-2: количество, размер, форматы, правила работы с масками, требования к разрешению, а также обсудим практический вопрос, который важнее самого лимита в 50 МБ — почему мы настоятельно не рекомендуем загружать изображения такого веса.
Ограничения API gpt-image-2: полные официальные спецификации
Сначала приведем основные выводы. API gpt-image-2 принимает входные изображения через эндпоинт v1/images/edits. Полные официальные ограничения приведены в таблице ниже.
Таблица ограничений на загрузку изображений в gpt-image-2
| Ограничение | Официальная спецификация | Источник |
|---|---|---|
| Макс. кол-во изображений | 16 шт. (серия моделей GPT image) | API Reference: images/edit |
| Размер одного изображения | < 50 МБ | Руководство по Image Generation |
| Поддерживаемые форматы | PNG, WebP, JPG | Руководство по Image Generation |
| Способ передачи | image_url или file_id (на выбор) |
API Reference: images/edit |
| Маска (mask) | Тот же формат и размер, что у оригинала, < 50 МБ, обязателен альфа-канал | Руководство по Image Generation |
| Кол-во генераций (n) | 1–10 шт. | API Reference: images/edit |
Таким образом, теоретически один запрос edit может содержать до 16 изображений весом почти по 50 МБ каждое. Однако «теоретический предел» и «инженерная практика» — это разные вещи, о чем мы поговорим подробнее ниже.
Здесь есть важный нюанс: в новой версии API параметр images принимает массив объектов, где каждый объект содержит либо image_url, либо file_id. file_id получается через предварительную загрузку в Files API — это удобно для часто используемых материалов. image_url поддерживает публичные ссылки или base64 data URL, что подходит для разовых запросов. Лимит в 50 МБ одинаков для обоих способов.
🎯 Совет для быстрой проверки: если вы не уверены, не превышает ли ваше изображение лимиты, самый простой способ — отправить реальный запрос и посмотреть на сообщение об ошибке. Мы рекомендуем проводить такие граничные тесты через совместимый с OpenAI интерфейс APIYI (apiyi.com). Панель логов платформы позволяет детально увидеть размер тела запроса и подробности ошибки, что гораздо нагляднее, чем отладка при прямом обращении к официальному API.
Почему в документации к gpt-image-2 «не найти» информацию о размере загружаемых файлов
Вернемся к вопросу, с которого мы начали: почему на странице Reference указано ограничение в 16 изображений, но ничего не сказано про их размер? На самом деле, это особенность структуры документации OpenAI. Страница Reference для images/edit организована на основе «схемы параметров» (Parameter Schema). Параметр images на уровне схемы — это просто массив объектов, поэтому ограничение на количество элементов в массиве там прописано. А вот размер файла и его формат относятся к «валидации во время выполнения» (runtime validation) и вынесены в описательную часть руководства по генерации изображений.
Есть еще несколько подобных правил, «спрятанных» в руководствах. Перед тем как приступать к разработке функций редактирования изображений, лучше учесть их все:
- Три требования к маске (mask): она должна быть того же формата и размера, что и редактируемое изображение, весить менее 50 МБ и обязательно содержать альфа-канал. Использование JPG в качестве маски — самая частая причина ошибок, так как в JPG нет альфа-канала.
- Разрешение не произвольное: параметр
sizeв gpt-image-2 поддерживает пользовательское разрешение, но есть жесткие ограничения: длинная сторона не более 3840px, ширина и высота должны быть кратны 16px, соотношение сторон не более 3:1, а общее количество пикселей должно быть в диапазоне от 655 360 до 8 294 400. - Входные изображения тарифицируются: эталонное изображение в запросе
editоплачивается по количеству токенов на входе. При использованииinput_fidelity: highрасход входных токенов заметно возрастает.
Ограничения разрешения и параметра size для gpt-image-2
| Параметр ограничения | Правило | Пример |
|---|---|---|
| Длинная сторона | ≤ 3840px | 3840×2160 (4K горизонтальный) допустимо |
| Кратность сторон | Кратны 16px | 1024, 1536, 2048 — все корректны |
| Соотношение сторон | ≤ 3:1 | 2048×1152 допустимо, 3072×1024 допустимо |
| Общее кол-во пикселей | 655 360 — 8 294 400 | Меньше 768×854 будет отклонено |
| Популярные пресеты | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | Для вертикальных — аналогично |
Если вашему приложению часто приходится переключаться между разными разрешениями, рекомендую реализовать эту таблицу ограничений для локальной проверки перед отправкой запроса. Это позволит перехватывать некорректные размеры на стороне клиента, что сэкономит лишний сетевой запрос, вместо того чтобы ждать ответа 400 от API. В центре документации APIYI (apiyi.com) мы также подготовили список параметров для проверки gpt-image-2, вы можете использовать его в качестве руководства при реализации.
Практика работы с gpt-image-2: 50 МБ — это предел, 1,5 МБ — идеальный выбор
Зная о жестком ограничении в 50 МБ, возникает более важный вопрос: изображения какого размера стоит передавать в реальных проектах? Мы рекомендуем придерживаться размера около 1,5 МБ на одно изображение и по возможности не превышать 5 МБ. Это не просто догадки, и вот три причины, почему это важно.
Во-первых, это увеличение размера при использовании base64. Если вы встраиваете изображения через data URL, кодировка base64 увеличивает объем примерно на 33% — исходный файл весом 40 МБ после кодирования превращается в 53 МБ, а при добавлении структуры JSON запрос может легко выйти за рамки лимита. Если вы встраиваете 16 изображений через base64, эта проблема умножается на 16, поэтому для больших файлов обязательно используйте канал предварительной загрузки file_id.
Во-вторых, время передачи и декодирования. При размере более 5 МБ время загрузки и серверного декодирования растет нелинейно. При нестабильном интернет-соединении это часто приводит к таймаутам и повторным попыткам, что только замедляет общую скорость генерации. Изображения весом около 1,5 МБ загружаются за 1–2 секунды при обычном домашнем интернете, что является оптимальным балансом между стабильностью и качеством.
В-третьих, снижение отдачи от качества изображения. gpt-image-2 выполняет внутреннюю предобработку входных данных. Если входное разрешение значительно превышает выходное, лишние пиксели просто тратятся впустую. Изображение в формате JPG с длинной стороной 3840px, сжатое до 2 МБ, практически не отличается по результатам редактирования от 40-мегабайтного PNG без потерь, но при этом экономит ресурсы и время на порядок.
Рекомендации по размеру изображений для gpt-image-2
| Состояние исходника | Рекомендуемое действие | Ожидаемый результат |
|---|---|---|
| < 1.5 МБ | Загружать напрямую | Максимальная скорость и стабильность |
| 1.5 МБ — 5 МБ | Можно передавать напрямую, лучше в JPG/WebP | Приемлемая скорость |
| 5 МБ — 20 МБ | Сжать до длинной стороны ≤ 3840px + качество 85 | Качество почти без потерь, резкое ускорение |
| 20 МБ — 50 МБ | Обязательное сжатие, использовать file_id |
Избежание лимитов из-за base64 |
| > 50 МБ | Превышает лимит, обязательно сжать | Иначе возникнет ошибка |
💡 Совет для пакетной обработки: В сценариях с высокой нагрузкой (например, удаление фона в e-commerce или массовая стилизация) рекомендуем перед загрузкой выполнять предварительное сжатие с помощью sharp или Pillow: "длинная сторона 3840px + качество JPG 85". Мы проверили это на кейсах корпоративных клиентов APIYI (apiyi.com), и этот шаг позволяет сократить сквозное время обработки одного запроса
editболее чем на 40%, при этом жалоб на качество не поступало.
Быстрый старт с API gpt-image-2: пример кода для редактирования нескольких изображений
gpt-image-2 работает по стандартному протоколу OpenAI. Ниже приведен простейший пример редактирования с использованием нескольких эталонных изображений. При использовании сервиса-прокси API APIYI достаточно заменить base_url:
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # Универсальный API-интерфейс APIYI
)
def to_data_url(path):
with open(path, "rb") as f:
b64 = base64.b64encode(f.read()).decode()
return f"data:image/jpeg;base64,{b64}"
result = client.images.edit(
model="gpt-image-2",
image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
prompt="Примени к изображению продукта неоновый кибер-стиль с эталона, сохранив основной объект",
input_fidelity="high", # Высокая точность сохранения деталей, потребляет больше токенов
size="2048x2048",
quality="high"
)
print(result.data[0].b64_json[:64]) # Вывод base64-кодированного результата
Несколько ключевых параметров: при установке input_fidelity в значение high детали (лица, логотипы и т.д.) сохраняются значительно лучше, но ценой увеличения расхода токенов на ввод изображения. Параметры quality и size — главные рычаги, определяющие стоимость вывода. Параметр n позволяет генерировать до 10 изображений за раз. Тарификация gpt-image-2 основана на токенах: текстовый ввод — $5/млн, ввод изображений — $8/млн (при попадании в кэш — $2/млн), вывод изображений — $30/млн. В пересчете на одно изображение: уровень low (1024×1024) стоит около $0.006, medium — $0.05, high — $0.21. Вывод всегда является основной статьей расходов.
Также обратите внимание, что официальные лимиты скорости зависят от уровня аккаунта: Tier 1 — всего 5 изображений в минуту, Tier 4 — 150, Tier 5 — 250. У новых аккаунтов уровень низкий, поэтому пакетные задачи легко упираются в ограничения. Использование таких агрегаторов, как APIYI (apiyi.com), позволяет обойти лимиты отдельных аккаунтов, что идеально подходит для производственных сред с высокой интенсивностью генерации.
Различия в ограничениях на загрузку между gpt-image-2 и предыдущими моделями
Если вы переносите свой проект с gpt-image-1 или DALL·E 2, стоит обратить внимание на несколько межпоколенческих различий. Самое значительное изменение произошло при переходе от DALL·E 2 к серии GPT image: интерфейс редактирования (edit) в DALL·E 2 принимал только квадратные PNG-файлы размером менее 4 МБ. В серии GPT image эти ограничения были смягчены: теперь можно загружать до 16 изображений размером до 50 МБ в трех форматах. Логику предварительной обработки «PNG + сжатие до 4 МБ», жестко прописанную во многих старых проектах, после миграции можно значительно упростить.
Обновление с gpt-image-1 до gpt-image-2 в основном коснулось разрешения и стоимости. gpt-image-1 поддерживала только три фиксированных формата вывода: 1024×1024, 1536×1024 и 1024×1536. В gpt-image-2 стало доступно произвольное разрешение с поддержкой 4K (длинная сторона до 3840 пикселей). Что касается цен, стоимость входных изображений для gpt-image-2 снизилась с $10/M до $8/M, а выходных — с $40/M до $30/M. Также добавился тариф $2/M для кэшированных данных, что заметно снижает расходы при использовании повторяющихся эталонных изображений.
Сравнение ограничений на загрузку в gpt-image-2 и предыдущих моделях
| Параметр | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| Кол-во входных изображений | 1 шт. | до 16 шт. | до 16 шт. |
| Макс. размер одного файла | < 4 МБ | < 50 МБ | < 50 МБ |
| Форматы ввода | Только квадратный PNG | PNG/WebP/JPG | PNG/WebP/JPG |
| Разрешение вывода | Фиксированный квадрат | 3 фиксированных размера | Произвольное, до 3840px |
| Цена генерации | Поштучно | $40/M токенов | $30/M токенов (кэш $2/M) |
| input_fidelity | Не поддерживается | Поддерживается | Поддерживается, выше детализация |
При переносе кода достаточно просто изменить параметр model, но рекомендуется обновить логику проверки разрешения и стратегии сжатия в соответствии с таблицей выше. Если вы хотите проверить результаты миграции перед внесением изменений в продакшн-код, воспользуйтесь APIYI (apiyi.com): загрузите один и тот же набор материалов и поочередно вызовите обе модели, чтобы наглядно сравнить качество редактирования и фактические затраты.
Часто задаваемые вопросы (FAQ) по загрузке изображений в gpt-image-2
Q1: Какой максимальный размер одного изображения для gpt-image-2?
Жесткий лимит составляет 50 МБ, поддерживаются форматы PNG, WebP и JPG. Это ограничение указано в руководстве по использованию OpenAI Image Generation, а не в справочнике параметров images/edit, поэтому на странице Reference его можно не найти. На практике рекомендуем придерживаться диапазона 1,5–5 МБ для оптимальной работы.
Q2: Как работает лимит в 16 изображений?
Параметр images принимает до 16 объектов изображений, каждый из которых задается через image_url или file_id. Модель использует их как совокупность эталонных изображений — это удобно для сценариев редактирования, где нужно объединить «фото продукта + стиль + композицию». Обратите внимание: 16 — это лимит на вход, а количество выходных изображений регулируется параметром n (максимум 10).
Q3: Почему возникает ошибка "invalid mask"?
В 90% случаев проблема в альфа-канале. Маска должна иметь тот же формат и размер, что и редактируемое изображение, а также обязательно содержать альфа-канал. Поскольку формат JPG не поддерживает прозрачность, для маски нужно использовать только PNG. Прозрачные области означают «разрешено перерисовывать», а непрозрачные — «оставить без изменений».
Q4: Что выбрать: загрузку через base64 или через file_id?
Для небольших файлов (< 5 МБ) и разовых запросов проще использовать base64 data URL. Для больших изображений или материалов, которые планируется использовать многократно, лучше загрузить их заранее через Files API и получить file_id. Это позволит избежать увеличения объема данных на 33% (характерного для base64) и повторно использовать файлы в разных запросах. Если сомневаетесь, протестируйте оба способа в консоли APIYI (apiyi.com) и сравните время отклика.
Итог: три ключевых числа для ограничений загрузки в gpt-image-2
Возвращаясь к исходному вопросу, ограничения API для редактирования изображений gpt-image-2 можно свести к трем цифрам: 16 (максимальное количество входных изображений, указанное в Reference), 50 МБ (лимит размера одного файла, указанный в руководстве пользователя) и 1,5 МБ (оптимальный размер для практической работы). Тот факт, что документация разделила информацию о количестве и размере на две разные страницы, и стал причиной путаницы, из-за которой многие видят только ограничение в «16 изображений».
Рекомендации по внедрению довольно просты: перед загрузкой приводите изображения к единому стандарту — сжимайте их так, чтобы длина большей стороны не превышала 3840 пикселей, а качество JPG было около 85. Для масок (mask) всегда используйте PNG с альфа-каналом, а для тяжелых материалов используйте канал file_id. Если сделать эти три шага обязательной предварительной обработкой перед отправкой запроса, можно практически полностью забыть об ошибках, связанных с загрузкой.
Если вам нужен стабильный доступ к gpt-image-2 из России или вы хотите поднять лимиты до промышленного уровня, вы можете подключиться через единый интерфейс APIYI (apiyi.com). Он полностью совместим с нативным SDK OpenAI, поэтому для миграции достаточно изменить всего одну строку base_url.
Справочные материалы: OpenAI API Reference: developers.openai.com/api/reference/resources/images/methods/edit
Автор: Команда APIYI
Мы специализируемся на агрегации API для больших языковых моделей и лучших практиках их использования. Больше обзоров моделей и руководств по подключению вы найдете на APIYI apiyi.com.
