> ## Documentation Index > Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt > Use this file to discover all available pages before exploring further. # Как использовать GPT Image: 1K, 2K, 4K, Quality и Mask — руководство по тестам BetterToken > Практическое руководство по размерам GPT Image, качеству, редактированию с Mask, фактическим пикселям, тарифам и примерам API по результатам тестов BetterToken. export const GptImageComparison = ({kind, labels, caption, label}) => { const comparisonPanels = { crops: [["comparison-crop-1k.png", 480, 480], ["comparison-crop-2k.png", 480, 480], ["comparison-crop-4k.png", 480, 480]], mask: [["comparison-mask-original.png", 476, 476], ["comparison-mask-overlay.png", 476, 476], ["comparison-mask-result.png", 476, 476]], boundary: [["comparison-boundary-original.png", 576, 256], ["comparison-boundary-result.png", 576, 256]], circles: [["comparison-circles-original.png", 416, 416], ["comparison-circles-overlay.png", 416, 416], ["comparison-circles-result.png", 416, 416]] }; const panels = comparisonPanels[kind]; return
{labels.map((title, index) =>

{title}

)} {panels.map(([file, width, height], index) => {labels[index]} )}

{caption}

; }; При создании изображений товаров, рекламных материалов или дизайн-макетов через `gpt-image-2`, `gpt-image-2.5-flare` и `gpt-image-2.5-sunburst` разработчики часто сталкиваются с рядом непростых вопросов: * **Почему вызовы одной и той же модели с одинаковыми параметрами в разное время дают разные результаты?** * **Почему при запросе 4K или определенного размера иногда возвращается уменьшенное изображение 1K?** * **Действительно ли срабатывают локальное редактирование с `Mask` или `quality=high`? По какому критерию в итоге списывается плата?** В обычных вызовах API недостаточно проверить только, равен ли HTTP-статус `200 OK`. Необходимо одновременно выполнить три условия: **изображение сгенерировано, подходит для целевого макета, а расходы прозрачны и предсказуемы**. Чтобы помочь разработчикам разобраться в реальном поведении этих 3 моделей, BetterToken реализовал на уровне шлюза **интеллектуальную маршрутизацию по возможностям, нормализацию параметров по умолчанию, предварительную блокировку недопустимых параметров и прозрачную тарификацию по фактически переданным пикселям**. Это руководство основано на последних результатах тестов и снимке цен на 2026-10-19. На реальных изображениях и счетах мы покажем, как отправлять запросы, какого результата ожидать и какие объективные ограничения сохраняются у самих моделей. > **Примечание**: В этом руководстве рассматриваются `gpt-image-2`, `gpt-image-2.5-flare` и `gpt-image-2.5-sunburst`. У моделей серии Nano Banana другие параметры и система тарификации; мы подробно расскажем о них отдельно, чтобы не смешивать данные. *** ## 1. Почему одна и та же модель с одинаковыми параметрами может давать разные результаты? На практике реальные возможности и стабильность различных сервисных узлов за одним и тем же названием модели нередко отличаются. Некоторые маршруты поддерживают только базовую генерацию 1K, другие выдают изображения высокого разрешения `2048×2048` или даже `3840×2160`. Узлы также по-разному поддерживают значения `quality`, редактирование по референсу и маски `Mask`. Если платформа просто вслепую пересылает запросы по названию модели, разработчики будут регулярно сталкиваться с ситуациями вроде «запросили 4K, получили маленькое изображение 1K», «передали Mask и сразу получили ошибку» или «приходится снова и снова корректировать параметры». Поэтому нужен строгий стандарт тестирования, который отдельно проверяет «API принимает параметр» и «каков фактически переданный результат». *** ## 2. Как проводилось тестирование: что считается «поддержкой»? Чтобы выводы были объективными и надежными, в регрессионное тестирование выпуска вошли **22 стандартных сценария** (17 корректных запросов успешно передали 18 изображений; 5 сценариев с недопустимыми параметрами ожидаемо завершились отказом без списания средств). Дополнительно мы создали примеры товарных изображений и редактирования с Mask для распространенных задач электронной коммерции. Критерии проверки просты: 1. **Декодирование пикселей исходного файла**: мы не полагаемся на заявление API. Для каждого переданного изображения декодируем исходный файл, считываем ширину и высоту, а затем сверяем тарифный уровень в ответе с фактическим списанием со счета. 2. **Проверка соответствия размера**: фактические ширину и высоту сравниваем с явно указанными в запросе. Если фактический размер больше, результат проходит проверку; **если хотя бы одна сторона меньше целевого размера более чем на 5%, результат считается не прошедшим проверку** (Примечание: этот критерий используется для строгой оценки результатов тестирования. Он не означает, что API автоматически отбрасывает корректные изображения, размер которых не совпал с запросом.) Если размер не указан или передано `auto`, фиксированный размер холста не задается. 3. **Раздельный учет принятия параметра и результата**: ответ без ошибки означает лишь, что «параметр принят». Строгую изоляцию области `Mask` и заметное улучшение от `quality=high` нужно оценивать по итоговому изображению. *** ## 3. Что показали тесты: какие параметры чаще всего понимают неправильно? Сопоставив параметры запросов, фактически переданные пиксели и итоговые счета, мы выявили несколько фактов, которые разработчики чаще всего понимают неверно: | Сценарий запроса | Фактический размер | Тарифный уровень и цена за единицу в CNY | Результат теста и значение для использования | | :- | :- | :- | :- | | `gpt-image-2`, `2048x2048`, `quality` не указан | 2048×2048 | 2K, ¥0.11 | В этом запросе изображение 2K успешно создано без передачи `quality` (использовалось качество по умолчанию). | | `flare`, `2048x2048`, `quality` не указан | 2048×2048 | 2K, ¥0.15 | Передача изображения размером `2048×2048` подтверждена тестом. | | `sunburst`, `2048x2048`, `quality` не указан | 2048×2048 | 2K, ¥0.15 | Передача изображения размером `2048×2048` подтверждена тестом. | | `gpt-image-2`, `1024x1024` | **1024×936** | 1K, ¥0.035 | Передано корректное изображение, но его высота оказалась примерно на 8.6% меньше, поэтому оно не прошло строгий стандарт размера этого раунда. | | `flare` / `sunburst`, `1024x1024` | **Обе модели: 1254×1254** | **2K, обе по ¥0.15** | **Запрос 1K не гарантирует оплату по тарифу 1K**: было передано квадратное изображение сверх запрошенного размера, поэтому тарификация прошла по 2K. | | `gpt-image-2`, `1536x1024` | 1536×1024 | 1K, ¥0.035 | Горизонтальное изображение с обычным соотношением сторон также относится к тарифному уровню 1K. | | `gpt-image-2`, `3840x2160` | **3840×2159** | 4K, ¥0.13 | Высота меньше всего на 1 пиксель (отклонение \< 0.05%); размер соответствует критерию приемки 4K. | | `gpt-image-2`, корректная Mask + `2048x2048` + `high` | 2048×2048 | 2K, ¥0.11 | Цепочка редактирования с Mask сработала, но точность изоляции локальной области необходимо оценивать по изображению. | Кроме того, в ходе тестов выявилось следующее поведение при работе с совместимостью параметров и ошибками: * **Допустимость параметров по умолчанию**: генерация работает, если `quality` и `size` опущены, переданы как `null` или явно заданы как `"auto"`. * **Как правильно запросить 4K**: **«4K» — понятие тарифного уровня, а не утверждение о поддержке квадратного изображения `4096x4096`.** Для изображения высокого разрешения уровня 4K используйте альбомный размер `3840x2160`. * **Отказ от недопустимых параметров без списания**: запросы с `4096x4096`, `stream=true`, пустым `quality=""`, пустым `size=""` и `n=0` получили ошибку `HTTP 400` и **не повлекли никаких списаний**. *** ## 4. Что предоставляет BetterToken: не нужно самостоятельно адаптировать каждый маршрут Чтобы справиться со сложным дрейфом размеров и различиями между нижележащими узлами, BetterToken выполняет на уровне шлюза четыре задачи. Вам не придется писать отдельный адаптационный код для каждого маршрута: 1. **Интеллектуальная маршрутизация по возможностям**: система автоматически подбирает доступный сервис с нужными возможностями с учетом модели, целевого размера (например, 2K/4K) и наличия в запросе параметров редактирования изображения/`Mask`. 2. **Единый интерфейс и обработка параметров по умолчанию**: стандартизированные интерфейсы `POST /v1/images/generations` (генерация изображений) и `POST /v1/images/edits` (редактирование по референсу/Mask) автоматически обрабатывают `null`, `auto` и отсутствующие параметры и блокируют недопустимые данные прямо на уровне шлюза. 3. **Прозрачный отчет о фактических размерах и тарификации**: вместе с данными изображения поле `bettertoken_image_billing` в теле ответа сообщает **фактическую декодированную ширину и высоту (`width`/`height`), тарифный уровень (`billing_resolution`), валюту и сумму расчета (`settled_amount`)**. 4. **Четкое разграничение двух основных понятий**: * **Поддержка параметра `Mask` ≠ попиксельное точное редактирование области**: API поддерживает загрузку референса и Mask для редактирования, но в некоторых тестах изменялись и защищенные области за пределами маски. Например, в геометрическом тесте с двумя кругами левый круг был прозрачным и должен был изменить цвет, а правый — непрозрачным и защищенным; в результате поменяли цвет обоих кругов. Поэтому **мы явно поддерживаем передачу параметра Mask, но не гарантируем строгую попиксельную изоляцию области при каждом запросе**. * **Поддержка параметра `quality` ≠ гарантированный фиксированный прирост качества изображения**: API корректно принимает параметры вроде `"auto"` или `"high"` и маршрутизирует запрос. Однако каждая генерация случайна, поэтому мы не делаем чрезмерных обещаний, будто `high` всегда улучшает качество на определенный процент, основываясь на одном примере. > ⚠️ **Перед интеграцией необходимо знать о двух реальных ограничениях**: > > 1. **Маршрутизация по возможностям не означает строгой фиксации пикселей при каждом запросе**: из-за различий в выходных данных нижележащих сервисов пиксели результата могут колебаться, даже если запрос направлен на подходящий узел. Например, сегодня среди образцов все еще есть запрос `1024x1024`, вернувший `1024×936`, и запрос `3840x2160`, вернувший `3840×2161`. Если пропорции холста критичны для вашего процесса, обрежьте изображение или обработайте его после получения фактических размеров. > 2. **Запрос 1K не обязательно будет оплачен по тарифу 1K**: система назначает тарифный уровень исходя из **характеристик фактически переданного корректного изображения**. Сегодня две модели 2.5 (а в некоторых случаях и `gpt-image-2`) при запросе `1024x1024` вернули `1254×1254`, то есть изображения с большим числом пикселей. Система отнесла их к **уровню 2K** и выставила соответствующую плату. *** ## 5. Поддержка трех моделей: какую модель вызвать и какое значение передать? Конфигурация возможностей и охват тестами для `gpt-image-2`, `gpt-image-2.5-flare` и `gpt-image-2.5-sunburst`: | Возможность | `gpt-image-2` | `gpt-image-2.5-flare` | `gpt-image-2.5-sunburst` | | :- | :- | :- | :- | | **Запрос генерации 1K** | Поддерживается (проверено; фактический размер может отличаться от целевого, например `1024×936` или `1254×1254`) | Поддерживается (проверено; в этом раунде возвращено большее изображение `1254×1254` с тарификацией 2K) | Поддерживается (проверено; в этом раунде возвращено большее изображение `1254×1254` с тарификацией 2K) | | **Генерация 2K (`2048x2048`)** | **Передано в этом раунде тестов** | **Передано в этом раунде тестов** | **Передано в этом раунде тестов** | | **Генерация 4K (`3840x2160`)** | **Горизонтальное изображение передано в этом раунде тестов** | Конфигурация маршрутизации приведена в соответствие для поддержки | Конфигурация маршрутизации приведена в соответствие для поддержки | | **Обычное редактирование по референсу (без Mask)** | **Проверено в этом раунде тестов** (при отсутствии Mask или передаче пустой Mask используется обычное редактирование) | Пока не подтверждено отдельно (поддержка Mask не доказывает доступность обычного редактирования) | Пока не подтверждено отдельно (поддержка Mask не доказывает доступность обычного редактирования) | | **Локальное редактирование с Mask** | **Передача 2K проверена в этом раунде** | Настроена поддержка редактирования с Mask в 4K (другие уровни не подтверждены) | Настроена поддержка редактирования с Mask в 4K (другие уровни не подтверждены) | | **Параметр качества изображения (`quality`)** | Значения по умолчанию/`auto`/`high` **проверены в тестах** | Значения по умолчанию/`auto` протестированы; маршрутизация `high` настроена | Значения по умолчанию/`auto` протестированы; маршрутизация `high` настроена | *Примечание: «Передано в этом раунде тестов» означает, что в сегодняшних регрессионных тестах и генерации примеров были напрямую получены изображения и примеры счетов. «Конфигурация маршрутизации приведена в соответствие для поддержки» означает, что платформа настроила соответствующий канал возможностей, но в сегодняшних регрессионных тестах не повторяла запросы для всех возможных комбинаций.* *** ## 6. Два примера реальных изображений: каков фактический результат? Чтобы показать реальное качество генерации, мы следовали подходу из [официального руководства OpenAI по составлению промптов для изображений](https://developers.openai.com/api/docs/guides/image-prompting): **«конкретный объект + текстура материала + направление света + композиция и соотношение сторон + исключения»**. Через реальный интерфейс BetterToken созданы два примера для электронной коммерции (сохранены исходные результаты без постобработки). ### Пример A: предметная съемка товара для электронной коммерции — размер и детали 1K / 2K / 4K **Описание сцены (концепция на китайском)**: > Создать реалистичную студийную фотографию для интернет-магазина: кораллово-красная керамическая кружка (ручка справа) стоит на светло-серой каменной столешнице, слева лежит сложенная бежевая льняная ткань. На кружке отчетливо видна белая надпись “BETTER DAY”. Мягкий боковой свет сверху слева; сохранить легкие блики глазури, волокна льна и естественные контактные тени. Кружка целиком в кадре и расположена по центру; фон простой, нейтральный, без других предметов, водяных знаков и дополнительного текста. **Фактически использованный промпт на английском**: ```text theme={null} Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads "BETTER DAY" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text. ``` Мы использовали `gpt-image-2` (`quality="high"`, 1 изображение за запрос) и не меняли приведенный выше промпт. Вместо попытки получить повышенное разрешение, добавив в промпт слово «4K», мы запросили три уровня размера, изменяя только параметр `size`: | Запрошенный размер (`size`) | Фактический размер | Фактический тариф / стоимость | Время одного запроса | | :- | :- | :- | :- | | `1024x1024` | **1254×1254** | **2K / ¥0.11** | 34.35 секунды | | `2048x2048` | **2048×2048** | **2K / ¥0.11** | 31.97 секунды | | `3840x2160` | **3840×2161** | **4K / ¥0.13** | 24.36 секунды | **1. Исходное изображение по запросу `1024x1024` (фактически передано `1254×1254`):** Изображение товара GPT Image 2: запрошено 1024×1024, возвращено 1254×1254 **2. Исходное изображение по запросу `2048x2048` (фактически передано `2048×2048`):** Изображение товара GPT Image 2: запрошенный и фактический размер 2048×2048 **3. Исходное изображение по запросу `3840x2160` (фактически передано `3840×2161`):** Горизонтальное изображение товара GPT Image 2: запрошено 3840×2160, возвращено 3840×2161 **4. Сравнение исходных обрезанных фрагментов соответствующих областей трех изображений (надпись на кружке и детали материала):** **Наблюдения по результатам теста**: * **Высокая завершенность изображения**: на всех трех изображениях видны блики кораллово-красной глазури, ручка справа, светло-серая каменная столешница, волокна бежевого льна и четкая белая надпись “BETTER DAY”. * **Различия независимой генерации**: каждый результат — отдельная случайная выборка, поэтому пропорции кружки, толщина шрифта и складки ткани естественно различаются (например, на горизонтальном изображении 4K надпись разбита на две строки). Обрезанные изображения показывают фактические детали каждого результата и не являются оптическим тестом резкости с одинаковой композицией. * **Наглядная граница тарификации**: хотя в первом запросе был указан `1024x1024`, система передала квадратное изображение высокого разрешения `1254×1254`, поэтому его тарифицировали на том же **уровне 2K (¥0.11)**, что и второе изображение `2048×2048`. *** ### Пример B: локальная смена цвета товара — фактический эффект и ограничения Mask В качестве входного изображения взят первый товарный снимок из примера A (`1254×1254`). Мы подготовили маску с альфа-каналом того же размера [mask-mug.png](/images/gpt-image-guide/mask-mug.png): **прозрачной оставлена только многоугольная область корпуса кружки (ее можно перерисовать), а ручка, внутренняя поверхность ободка и фон непрозрачны (должны сохраниться). Надпись на кружке расположена в прозрачной области; в промпте указано сохранить ее.** Схема области Mask: черный цвет — прозрачная редактируемая область, белый — непрозрачная защищенная область *(Примечание: изображение выше — черно-белая визуализация. Черный обозначает область для изменений, белый — защищенную область. Фактически через API загружается `mask-mug.png` с альфа-каналом.)* **Описание сцены (концепция на китайском)**: > Изменить только кораллово-красный корпус кружки внутри прозрачной маски на темно-синий, сохранив керамическую текстуру, освещение и блики. Оставить белую надпись “BETTER DAY”, красную ручку, льняную ткань, столешницу, фон и общую композицию без изменений. Не добавлять и не удалять предметы. **Фактически использованный промпт на английском (модель: `gpt-image-2`, `size="2048x2048"`, `quality="high"`)**: ```text theme={null} Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask. ``` **Фактический результат редактирования (`2048×2048`, 38.51 секунды, стоимость ¥0.11):** Редактирование GPT Image 2 с Mask: корпус стал темно-синим, ручка осталась красной, но внутренняя поверхность ободка тоже изменила цвет **Сравнение деталей, изменившихся за пределами защищенной области:** **Контрпример: образец «2 круга изменили цвет» из регрессионного теста (Mask принята ≠ точная изоляция)** **Наблюдения по тесту (ограничения раскрыты прямо)**: * **Основная задача смены цвета выполнена**: внешняя сторона корпуса кружки стала темно-синей, при этом сохранились керамические блики. **Красная ручка за пределами маски, льняная ткань слева и фон в целом сохранены; надпись “BETTER DAY” внутри маски осталась читаемой.** * **Строгая граница Mask не соблюдена (изменения вышли за пределы маски)**: при внимательном рассмотрении ободка и внутренней стенки видно, что кораллово-красные области, изначально находившиеся внутри непрозрачной защищенной зоны, также стали темно-синими. В более экстремальном геометрическом тесте «два круга изменили цвет» поменял цвет и незамаскированный правый круг. * **Рекомендация по использованию**: при загрузке референса и Mask проверьте, что размеры их холстов совпадают (прозрачность в местах для изменения, непрозрачность в местах, которые нужно сохранить), и укажите в промпте как «что изменить», так и «что сохранить». Для промышленной и коммерческой графики с логотипами, мелким текстом на упаковке или строгими требованиями к краям **после генерации обязательно увеличьте изображение и проверьте границы защищенных областей**. *** ## 7. Цены и фактическая стоимость использования: сколько списывается в итоге? BetterToken придерживается прозрачного ценообразования. Ниже приведен снимок публичных цен на **2026-10-19** (CNY применяется для корпоративных счетов в юанях; USD — для обычных счетов в долларах США. Цены устанавливаются независимо и не пересчитываются по текущему обменному курсу): | Модель | Цена 1K / изображение | Цена 2K / изображение | Цена 4K / изображение | | :- | :- | :- | :- | | **`gpt-image-2`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.11 / \$0.0194 | ¥0.13 / \$0.0229 | | **`gpt-image-2.5-flare`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.15 / \$0.0265 | ¥0.18 / \$0.0318 | | **`gpt-image-2.5-sunburst`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.15 / \$0.0265 | ¥0.18 / \$0.0318 | При указанных публичных ценах, если все 100 созданных изображений фактически относятся к соответствующему тарифному уровню, ориентировочная стоимость 100 вызовов будет следующей (арифметическая оценка): | Модель | Стоимость 100 изображений 1K | Стоимость 100 изображений 2K | Стоимость 100 изображений 4K | | :- | :- | :- | :- | | **`gpt-image-2`** (CNY / USD) | ¥3.50 / \$0.62 | ¥11.00 / \$1.94 | ¥13.00 / \$2.29 | | **`flare` или `sunburst`** (CNY / USD) | ¥3.50 / \$0.62 | ¥15.00 / \$2.65 | ¥18.00 / \$3.18 | > 💡 **Главное при планировании бюджета: рассчитывайте затраты по «фактическому тарифному уровню результата», а не по «параметру запроса»!** > > Как показали приведенные выше тесты, некоторые сегодняшние запросы к `flare`, `sunburst` или `gpt-image-2` на `1024x1024` (1K) вернули изображения `1254×1254`. В этом случае система относит результат к **2K** (списывается ¥0.15 или ¥0.11, а не ¥0.035 по тарифу 1K). Если все 100 запросов `1024x1024` к `flare` вернут `1254×1254`, стоимость этих 100 изображений по текущим ценам составит **¥15.00 (арифметическая оценка)**. > > Кроме того, при назначении тарифа система учитывает целевой размер и допустимый порог отклонения (например, `3840×2159` обычно относится к 4K, а `1536×1024` — к 1K). Не зашивайте в бизнес-логику самостоятельный пересчет, основанный только на том, «превышает ли длинная сторона 1024». **Для тарификации всегда используйте поле `bettertoken_image_billing` в теле ответа.** ### Почему нельзя смотреть только на формальную «низкую цену за изображение»? Сравнивая стоимость API для изображений на разных платформах, разработчикам следует учитывать три вида затрат: 1. **Сравнивать цены можно, только если фактический результат достиг целевого размера**: запрос с заявленной «поддержкой 4K по очень низкой цене», который фактически возвращает уменьшенное изображение 1024, нельзя использовать в рабочей среде, где требуются изображения высокого разрешения. Его нельзя считать сопоставимой ценой за 4K. 2. **Учитывайте стоимость ошибок и повторной работы**: тесты недопустимых параметров в этом раунде не тарифицировались. Если корректно переданное изображение не устроило по качеству, повторная генерация считается новым запросом и должна планироваться отдельно. 4 изображения для примеров товара и Mask в этом руководстве (3 генерации + 1 редактирование) получены каждое за один запрос. В образце с Mask были изменения за пределами маски, описанные выше. Цены составили ¥0.11, ¥0.11, ¥0.13 и ¥0.11; **фактическая сумма за все 4 изображения — всего ¥0.46**, что в точности совпало со счетом и списанием со счета. Если нестабильность маршрутов или несовместимые параметры вынуждают многократно запускать генерацию, фактическая совокупная стоимость одного пригодного материала может увеличиться, даже если цена за изображение выглядит низкой. 3. **Снижение скрытых затрат на инженерную адаптацию**: единые правила параметров BetterToken, интеллектуальная маршрутизация по возможностям и поля с реальными пикселями и тарификацией в реальном времени сокращают объем разработки для адаптации каждого сервиса и самостоятельного сбора данных о размерах и расходах. *** ## 8. Примеры запросов, которые можно сразу скопировать Сохраните ключ API BetterToken в переменной окружения `BETTERTOKEN_API_KEY`, чтобы сразу скопировать приведенные ниже команды и начать работу. ### Пример 1: JSON-запрос для генерации товарного изображения высокого разрешения (`POST /v1/images/generations`) В этом примере вызывается `gpt-image-2` для генерации одного товарного изображения высокого разрешения `2048x2048` (`model` можно заменить на `gpt-image-2.5-flare` или `gpt-image-2.5-sunburst`): ```bash theme={null} curl https://bettertoken.ai/v1/images/generations -o response.json \ -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "model": "gpt-image-2", "prompt": "Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads \"BETTER DAY\" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.", "size": "2048x2048", "quality": "high", "n": 1, "response_format": "b64_json", "output_format": "png" } JSON ``` * **Требования к размеру**: для горизонтального изображения 4K измените `"size"` на `"3840x2160"` (не используйте `"4096x4096"`). Допустимый размер должен одновременно соответствовать условиям: ширина и высота кратны 16, длинная сторона не превышает 3840, соотношение длинной и короткой сторон не более 3:1, общее число пикселей — от `655,360` до `8,294,400`. * **Определение формата файла**: даже если в запросе указано `"output_format": "png"`, некоторые нижележащие узлы могут вернуть бинарные данные JPEG. При сохранении или обработке изображения определяйте реальный формат по заголовку (Magic Bytes), не фиксируйте расширение заранее. ### Пример 2: локальное редактирование Multipart с референсом и Mask (`POST /v1/images/edits`) Подготовьте исходное изображение `product-1k-0.png` и прозрачную маску `mask-mug.png` того же размера (если нужно только обычное редактирование по референсу, удалите строку `-F "mask=..."`): ```bash theme={null} curl https://bettertoken.ai/v1/images/edits -o response.json \ -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \ -F "model=gpt-image-2" \ -F "image=@product-1k-0.png;type=image/png" \ -F "mask=@mask-mug.png;type=image/png" \ -F 'prompt=Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.' \ -F "size=2048x2048" \ -F "quality=high" \ -F "n=1" \ -F "response_format=b64_json" ``` ### Пример 3: чтение фактических пикселей и сведений о тарификации (структура ответа и код разбора) Помимо стандартного `data[].b64_json`, тело ответа BetterToken содержит дополнительное поле `bettertoken_image_billing`: ```json theme={null} { "created": 1792398084, "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." } ], "bettertoken_image_billing": { "currency": "CNY", "settled_amount": "0.11", "outputs": [ { "index": 0, "width": 2048, "height": 2048, "billing_resolution": "2K", "currency": "CNY", "amount": "0.11" } ] } } ``` Следующий фрагмент кода Python за один проход **декодирует изображение, определяет фактический формат, считывает размер и сверяет счет**: ```python theme={null} import base64 import io import json from pathlib import Path from PIL import Image # 需要 Pillow # 将 API 的 JSON 响应保存为 response.json 后执行。 resp_json = json.loads(Path("response.json").read_text()) if "error" in resp_json: raise RuntimeError(resp_json["error"]) billing = resp_json["bettertoken_image_billing"] outputs = {item["index"]: item for item in billing["outputs"]} for index, item in enumerate(resp_json["data"]): img_bytes = base64.b64decode(item["b64_json"], validate=True) with Image.open(io.BytesIO(img_bytes)) as image: image.load() width, height = image.size ext = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}.get(image.format) if ext is None: raise ValueError(f"未处理的图片格式：{image.format}") Path(f"output_{index}.{ext}").write_bytes(img_bytes) info = outputs[index] print(f"图片 {index}：原图 {width}×{height}；计费档位 {info['billing_resolution']}") print(f"单张费用：{info['amount']} {info['currency']}") if (width, height) != (info["width"], info["height"]): print("图片像素与响应尺寸不一致，请保留结果并联系支持。") print(f"本次结算：{billing['settled_amount']} {billing['currency']}") ``` *** **Справочные материалы**: * [Официальная документация OpenAI: руководство по промптам для изображений (Image Prompting Guide)](https://developers.openai.com/api/docs/guides/image-prompting) * [OpenAI Cookbook: примеры генерации и редактирования изображений с высокой точностью входных данных](https://developers.openai.com/cookbook/examples/generate_images_with_high_input_fidelity) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.