Параметры GPT Image 2 API: размер, разрешение, соотношение сторон и качество
Параметры GPT Image 2 API, которые определяют изображение: имя модели, размер и разрешение, соотношения сторон, лимиты 4K, качество, форматы и ошибки.
Читать в MarkdownGPT Image 2 API принимает имя модели в model, размеры результата в size в виде WIDTHxHEIGHT в пикселях и качество в quality (low, medium, high или auto). Поля resolution или aspect_ratio нет. Чтобы получить изображение 16:9 в 4K, отправьте "size": "3840x2160". Стороны должны быть кратны 16, каждая не больше 3840 пикселей, соотношение — в пределах от 1:3 до 3:1, а общее число пикселей — от 655 360 до 8 294 400.
В этом руководстве разобран каждый параметр, который меняет картинку: какое именно значение отправлять и какую ошибку возвращает неверное значение. Каждая ошибка ниже проверена на работающем API.
Какое имя модели GPT Image 2 указывать в API?
Используйте gpt-image-2 или gpt-image-2-official. Это одна и та же модель с одинаковыми полями; gpt-image-2 берёт одну фиксированную цену за каждое доставленное изображение, а gpt-image-2-official списывает за токены, о которых сообщает каждый рендер.
Названия из заголовков не работают как ID модели. gpt-image-2.0, GPT Image 2 или chatgpt-images-2 возвращают HTTP 400 с кодом ошибки 20002.
Как задать разрешение и соотношение сторон?
Через size, в пикселях. Выберите нужное соотношение сторон и объём пикселей, затем отправьте получившиеся ширину и высоту:
| Соотношение сторон | Около 1K | Около 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:2 | 1248x832 | 2496x1664 | 3504x2336 |
| 2:3 | 832x1248 | 1664x2496 | 2336x3504 |
| 4:3 | 1152x864 | 2304x1728 | 3264x2448 |
| 3:4 | 864x1152 | 1728x2304 | 2448x3264 |
| 16:9 | 1280x720 | 2560x1440 | 3840x2160 |
| 9:16 | 720x1280 | 1440x2560 | 2160x3840 |
| 21:9 | 1456x624 | 3024x1296 | 3808x1632 |
| 3:1 | 1728x576 | 3504x1168 | 3840x1280 |
Это те же пересчёты, которые использует Playground, когда вы выбираете соотношение и пресет 1K, 2K или 4K. Квадрат в 4K ограничен 2880x2880, потому что квадрат со стороной 3840 пикселей превысил бы лимит общего числа пикселей.
size: "auto" оставляет размеры на усмотрение модели. Это значение по умолчанию, и оно удобно, но задавайте явный размер, когда результаты должны соответствовать макету или друг другу.
OpenAI называет вывод больше 2560×1440 экспериментальным. В пределах указанных здесь лимитов он принимается, но больший холст не гарантирует больше деталей.
Какие значения size отклоняются?
| Отправленное значение | Почему не работает | Ответ |
|---|---|---|
"size": "16:9" | Соотношение — не размер | 400 20001, сообщение называет size |
"size": "4096x2304" | Сторона больше 3840 | 400 20001, сообщение называет size |
"size": "1000x1000" | Не кратно 16 | 400 20001, сообщение называет size |
"size": "3840x1024" | Шире, чем 3:1 | 400 20001, сообщение называет size |
"resolution": "4k" | Неизвестное поле | 400 20001, поле не названо |
"aspect_ratio": "16:9" | Неизвестное поле | 400 20001, поле не названо |
Обратите внимание на две последние строки. Неизвестное поле отклоняется, но ошибка его не называет. Если вы получили 20001 с общим сообщением «Check the parameters against the API documentation», ищите поле, которое API не принимает, например resolution, aspect_ratio или response_format.
Какое качество выбрать?
quality принимает low, medium, high и auto. Более высокие уровни дольше рендерятся и передают более тонкие детали. xhigh и max есть только у GPT Image 2.5; если отправить их в GPT Image 2, вернётся 20001 с сообщением, которое называет quality.
Практичный порядок: делайте черновики на low, пока композиция ещё меняется, проверяйте текстуру и мелкий текст на medium, а финальные версии выпускайте на high. У gpt-image-2 цена на всех уровнях одинакова. У gpt-image-2-official более высокие уровни сообщают больше выходных токенов, поэтому стоят дороже. Цифры приведены в руководстве по ценам.
auto оставляет выбор уровня модели. Задавайте явное значение, когда сравниваете запуски, иначе два «одинаковых» запроса могут отрендериться на разных уровнях.
Что управляет форматом и фоном?
output_format:png(по умолчанию) илиjpeg. Вывод в WebP не предусмотрен;webpвозвращает20001с сообщением, которое называетoutput_format.output_compression: от 0 до 100, только сjpeg.background:auto,opaqueилиtransparent. Для прозрачности нуженpng;transparentсjpegвозвращает20001с сообщением, которое называетbackground.n: от 1 до 10 изображений на запрос. Оплачиваются доставленные изображения.moderation:autoилиlow.
Как передавать референсные изображения и маски?
Как URL, а не как файлы или base64. images принимает от 1 до 16 объектов вида {"image_url": "https://..."}, и его передача превращает запрос в правку. mask принимает один объект того же вида: PNG размером с первое референсное изображение, где прозрачная область отмечает, что нужно изменить. Ограничения на файлы перечислены в справочнике.
Часто задаваемые вопросы
Поддерживает ли GPT Image 2 разрешение 4K?
Да, в пределах указанных выше лимитов. 3840x2160 для 16:9 и 2160x3840 для 9:16 — самые большие кадры, а 2880x2880 — самый большой квадрат.
Можно ли отправить соотношение сторон вместо пикселей?
В API — нет. Сначала переведите соотношение в размер WIDTHxHEIGHT по таблице выше или в Playground, который показывает точный размер перед отправкой.
Какие размер и качество используются по умолчанию?
Оба параметра по умолчанию равны auto, то есть выбор остаётся за моделью. Отправляйте явные значения, когда нужен предсказуемый результат.
Отправляйте пиксели, задавайте качество, читайте сообщение об ошибке
Почти любая проблема с параметрами сводится к одному из трёх: соотношение отправлено как размер, API не принимает поле или значение выходит за пределы лимитов. В первом и третьем случаях сообщение об ошибке называет поле; общее сообщение без названия поля указывает на второй. Держите эту страницу рядом со справочником GPT Image 2 API, пока делаете интеграцию.
