Как использовать GPT Image: 1K, 2K, 4K, Quality и Mask — руководство по тестам BetterToken

• Почему вызовы одной и той же модели с одинаковыми параметрами в разное время дают разные результаты?
• Почему при запросе 4K или определенного размера иногда возвращается уменьшенное изображение 1K?
• Действительно ли срабатывают локальное редактирование с Mask или quality=high? По какому критерию в итоге списывается плата?

Примечание: В этом руководстве рассматриваются gpt-image-2, gpt-image-2.5-flare и gpt-image-2.5-sunburst. У моделей серии Nano Banana другие параметры и система тарификации; мы подробно расскажем о них отдельно, чтобы не смешивать данные.

​

1. Почему одна и та же модель с одинаковыми параметрами может давать разные результаты?

​

2. Как проводилось тестирование: что считается «поддержкой»?

1. Декодирование пикселей исходного файла: мы не полагаемся на заявление API. Для каждого переданного изображения декодируем исходный файл, считываем ширину и высоту, а затем сверяем тарифный уровень в ответе с фактическим списанием со счета.
2. Проверка соответствия размера: фактические ширину и высоту сравниваем с явно указанными в запросе. Если фактический размер больше, результат проходит проверку; если хотя бы одна сторона меньше целевого размера более чем на 5%, результат считается не прошедшим проверку (Примечание: этот критерий используется для строгой оценки результатов тестирования. Он не означает, что API автоматически отбрасывает корректные изображения, размер которых не совпал с запросом.) Если размер не указан или передано auto, фиксированный размер холста не задается.
3. Раздельный учет принятия параметра и результата: ответ без ошибки означает лишь, что «параметр принят». Строгую изоляцию области Mask и заметное улучшение от quality=high нужно оценивать по итоговому изображению.

​

3. Что показали тесты: какие параметры чаще всего понимают неправильно?

• Допустимость параметров по умолчанию: генерация работает, если quality и size опущены, переданы как null или явно заданы как "auto".
• Как правильно запросить 4K: «4K» — понятие тарифного уровня, а не утверждение о поддержке квадратного изображения 4096x4096. Для изображения высокого разрешения уровня 4K используйте альбомный размер 3840x2160.
• Отказ от недопустимых параметров без списания: запросы с 4096x4096, stream=true, пустым quality="", пустым size="" и n=0 получили ошибку HTTP 400 и не повлекли никаких списаний.

​

4. Что предоставляет 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. Поддержка трех моделей: какую модель вызвать и какое значение передать?

​

6. Два примера реальных изображений: каков фактический результат?

​

Пример A: предметная съемка товара для электронной коммерции — размер и детали 1K / 2K / 4K

Создать реалистичную студийную фотографию для интернет-магазина: кораллово-красная керамическая кружка (ручка справа) стоит на светло-серой каменной столешнице, слева лежит сложенная бежевая льняная ткань. На кружке отчетливо видна белая надпись “BETTER DAY”. Мягкий боковой свет сверху слева; сохранить легкие блики глазури, волокна льна и естественные контактные тени. Кружка целиком в кадре и расположена по центру; фон простой, нейтральный, без других предметов, водяных знаков и дополнительного текста.

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.

• Высокая завершенность изображения: на всех трех изображениях видны блики кораллово-красной глазури, ручка справа, светло-серая каменная столешница, волокна бежевого льна и четкая белая надпись “BETTER DAY”.
• Различия независимой генерации: каждый результат — отдельная случайная выборка, поэтому пропорции кружки, толщина шрифта и складки ткани естественно различаются (например, на горизонтальном изображении 4K надпись разбита на две строки). Обрезанные изображения показывают фактические детали каждого результата и не являются оптическим тестом резкости с одинаковой композицией.
• Наглядная граница тарификации: хотя в первом запросе был указан 1024x1024, система передала квадратное изображение высокого разрешения 1254×1254, поэтому его тарифицировали на том же уровне 2K (¥0.11), что и второе изображение 2048×2048.

​

Пример B: локальная смена цвета товара — фактический эффект и ограничения Mask

Изменить только кораллово-красный корпус кружки внутри прозрачной маски на темно-синий, сохранив керамическую текстуру, освещение и блики. Оставить белую надпись “BETTER DAY”, красную ручку, льняную ткань, столешницу, фон и общую композицию без изменений. Не добавлять и не удалять предметы.

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.

• Основная задача смены цвета выполнена: внешняя сторона корпуса кружки стала темно-синей, при этом сохранились керамические блики. Красная ручка за пределами маски, льняная ткань слева и фон в целом сохранены; надпись “BETTER DAY” внутри маски осталась читаемой.
• Строгая граница Mask не соблюдена (изменения вышли за пределы маски): при внимательном рассмотрении ободка и внутренней стенки видно, что кораллово-красные области, изначально находившиеся внутри непрозрачной защищенной зоны, также стали темно-синими. В более экстремальном геометрическом тесте «два круга изменили цвет» поменял цвет и незамаскированный правый круг.
• Рекомендация по использованию: при загрузке референса и Mask проверьте, что размеры их холстов совпадают (прозрачность в местах для изменения, непрозрачность в местах, которые нужно сохранить), и укажите в промпте как «что изменить», так и «что сохранить». Для промышленной и коммерческой графики с логотипами, мелким текстом на упаковке или строгими требованиями к краям после генерации обязательно увеличьте изображение и проверьте границы защищенных областей.

​

7. Цены и фактическая стоимость использования: сколько списывается в итоге?

💡 Главное при планировании бюджета: рассчитывайте затраты по «фактическому тарифному уровню результата», а не по «параметру запроса»! Как показали приведенные выше тесты, некоторые сегодняшние запросы к 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 в теле ответа.

​

Почему нельзя смотреть только на формальную «низкую цену за изображение»?

1. Сравнивать цены можно, только если фактический результат достиг целевого размера: запрос с заявленной «поддержкой 4K по очень низкой цене», который фактически возвращает уменьшенное изображение 1024, нельзя использовать в рабочей среде, где требуются изображения высокого разрешения. Его нельзя считать сопоставимой ценой за 4K.
2. Учитывайте стоимость ошибок и повторной работы: тесты недопустимых параметров в этом раунде не тарифицировались. Если корректно переданное изображение не устроило по качеству, повторная генерация считается новым запросом и должна планироваться отдельно. 4 изображения для примеров товара и Mask в этом руководстве (3 генерации + 1 редактирование) получены каждое за один запрос. В образце с Mask были изменения за пределами маски, описанные выше. Цены составили ¥0.11, ¥0.11, ¥0.13 и ¥0.11; фактическая сумма за все 4 изображения — всего ¥0.46, что в точности совпало со счетом и списанием со счета. Если нестабильность маршрутов или несовместимые параметры вынуждают многократно запускать генерацию, фактическая совокупная стоимость одного пригодного материала может увеличиться, даже если цена за изображение выглядит низкой.
3. Снижение скрытых затрат на инженерную адаптацию: единые правила параметров BetterToken, интеллектуальная маршрутизация по возможностям и поля с реальными пикселями и тарификацией в реальном времени сокращают объем разработки для адаптации каждого сервиса и самостоятельного сбора данных о размерах и расходах.

​

8. Примеры запросов, которые можно сразу скопировать

​

Пример 1: JSON-запрос для генерации товарного изображения высокого разрешения (POST /v1/images/generations)

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)

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: чтение фактических пикселей и сведений о тарификации (структура ответа и код разбора)

{
  "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"
      }
    ]
  }
}

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)
• OpenAI Cookbook: примеры генерации и редактирования изображений с высокой точностью входных данных