«Transparent background is not supported for this model»: три решения

Ошибка честная, а лечится сменой одного слова в имени модели. background: "transparent" — превью-возможность, которая есть у одних развёртываний модели и отсутствует у других, и та, что используется в cookbook самой OpenAI, здесь как раз из вторых.

Ошибка:       400, "Transparent background is not supported for this model."
Тип:          image_generation_user_error
Срабатывает:  openai/gpt-image-2  (1.1 с, до всякой генерации)
Работает:     openai/gpt-image-1.5  (200, RGBA PNG, 67.3% пикселей с альфой 0)
Тихий отказ:  gemini-3-pro-image, qwen-image-3.0, mai-image-2.5-flash
              все 200, все тип цвета 2, альфа-канала нет
Формат:       только PNG. jpeg — 400, webp — 400.
Промпт:       промпт сильнее параметра. Слова про сцену вернут сцену.
Измерено:     2026-08-24, POST /v1/images/generations, 1024x1024, n=1

Три решения в том порядке, в каком они кусаются:

• Первое: смените модель. Возможность привязана к развёртыванию, а не к запросу. Один ID в сторону — и это 200 с настоящим альфа-каналом.
• Второе: оставьте вывод в PNG. jpeg и webp здесь оба дают 400, и по разным причинам.
• Третье: перепишите промпт. Промпт сильнее параметра, и промпт со сценой вернёт вам сцену.

Обновлено 2026-08-24. OpenAI описывает прозрачные ассеты как превью, поэтому набор моделей с этой возможностью может меняться. Перед тем как верить любому списку моделей, включая наш, повторите проверку из этой статьи.

Почему gpt-image-2 говорит, что модель не поддерживает прозрачность

Потому что у развёртывания за этим ID превью прозрачности не включено. Это не вежливая формулировка «параметр неверный».

Вот весь ответ:

{
  "error": {
    "code": null,
    "message": "Transparent background is not supported for this model.",
    "param": null,
    "type": "image_generation_user_error"
  }
}

Две детали отсекают скучные объяснения. Ответ приходит за 1.1 секунды, значит ничего не генерировалось и не выбрасывалось. И идентичный запрос с background: "opaque" возвращает 200 с нормальной картинкой на той же модели и через тот же ключ. Шлюз, который фильтрует поле, не смог бы выдать разные результаты для двух его значений.

Люди попадают сюда, делая всё по инструкции, потому что cookbook OpenAI про прозрачные ассеты написан под gpt-image-2. Но перечитайте вводную строку: там сказано, что нужен доступ к модели с поддержкой прозрачности, и что функция находится в превью. Имя модели и возможность — разные вещи, когда функция живёт за флагом доступа.

Какие модели действительно возвращают прозрачный PNG

Одна из пяти проверенных. Тот же промпт, тот же размер, тот же эндпоинт, тот же день.

Опасны именно три двухсотых в нижней половине. Ошибка 400 ничего не стоит и говорит, что менять. А 200, который тихо отдаёт непрозрачный PNG, стоит одной генерации, проходит все ваши проверки response.ok и всплывает белым прямоугольником в презентации через неделю.

Потерю поля мы проверили, а не предположили. Отправьте background: "bogus" в gpt-image-1.5 — и получите 400 с перечислением допустимых значений:

Invalid value: 'bogus'. Supported values are: 'transparent', 'opaque', and 'auto'.

Та же бессмыслица в gemini-3-pro-image даёт 200 и картинку. Маршрут, который валидирует поле, отвергает мусор. Маршрут, который принимает мусор, и не собирался соблюдать transparent.

Четыре отказа — живые вызовы; последний блок читает заголовки PNG у файлов, которые модели действительно вернули.

Решение 1: на какую модель переходить

openai/gpt-image-1.5, и больше в запросе ничего не меняется. Тело, которое падает на gpt-image-2, проходит без правок:

from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key="YOUR_OFOX_API_KEY")

resp = client.images.generate(
    model="openai/gpt-image-1.5",   # с gpt-image-2 здесь будет 400
    prompt=(
        "A single glossy red ceramic coffee mug, isolated product cutout, "
        "no backdrop, no scene, no shadow, no reflection, transparent background, "
        "no text, no letters, no logos, no watermarks"
    ),
    size="1024x1024",
    background="transparent",
)

Если это идёт в каталожный пайплайн, зафиксируйте ID модели явно и падайте громко, когда в ответе нет альфы, вместо того чтобы позволить запасной модели за ночь наделать тысячу непрозрачных «вырезов». Остальные ошибки, встречающиеся в том же пайплайне, разобраны в заметках про сбои gpt-image-2.

Решение 2: какие форматы держат альфу

PNG, и только PNG. JPEG не умеет хранить альфа-канал, и API сообщает об этом до генерации, а WebP, который в принципе альфу хранит, здесь просто не предлагается.

output_format: "jpeg"  ->  400  Transparent background is not supported for JPEG output format
output_format: "webp"  ->  400  Invalid value: 'webp'. Supported values are: 'png' and 'jpeg'.

Два отказа стоит различать. Про JPEG — это про возможности формата. Про WebP — про то, что этот эндпоинт принимает более короткий список. Для витрин это важно: инстинкт просит сразу WebP, чтобы пропустить конвертацию, а здесь вы генерируете PNG и конвертируете ниже по потоку.

Решение 3: почему на прозрачной картинке столько фона

Потому что промпт сильнее параметра, причём с большим отрывом. В cookbook OpenAI это примечание. Мы измерили, во что оно обходится.

Та же модель, тот же background: "transparent", два промпта:

Вторая картинка — не провал функции прозрачности. Альфа получилась. Она получилась вокруг сцены, которую попросили нарисовать, и это бесполезно для каталога, а если файл никто не смотрит перед отгрузкой, то и хуже, чем бесполезно.

Практическое правило: описывайте объект и ничего больше, затем добавьте отрицания. Слова counter, studio, gradient, table, sunset и shadow приглашают фон обратно. Просьба про отражение — тоже.

Как проверить, что в PNG действительно есть прозрачность

Прочитайте один байт. PNG хранит тип цвета в чанке IHDR, по смещению 25:

python3 -c "print('colour type', open('out.png','rb').read(26)[25])"
# 6 = truecolour + альфа    4 = серый + альфа
# 2 = truecolour без альфы  3 = индексный (прозрачность может быть в tRNS)

Тип цвета — условие необходимое, но не достаточное. RGBA-файл, у которого альфа везде 255, — непрозрачная картинка с лишним каналом, и именно это возвращает плохо сформулированный промпт. Считайте пиксели:

from PIL import Image

im = Image.open("out.png")
print(im.mode)                                     # RGBA, если альфа-канал есть
if im.mode == "RGBA":
    hist = im.getchannel("A").histogram()
    px = im.width * im.height
    print(f"{100 * hist[0] / px:.1f}% fully transparent")
    print(f"{100 * hist[255] / px:.1f}% fully opaque")

Все числа этой статьи получены этими двумя проверками. Остальная часть API каналов — в справочнике Pillow, а таблица типов цвета — в спецификации PNG, если удобнее разобрать заголовок самостоятельно.

Поставьте проверку альфы в CI. Сервис генерации, который тихо сменит развёртывание за ID модели, вам об этом не сообщит, а тест «более 30% пикселей полностью прозрачны» — сообщит.

Сколько стоит одна прозрачная картинка

Успешная генерация обошлась в 46 входных и 4 415 выходных токенов, из которых 4 160 — токены изображения и 255 — текстовые. По ставкам с карточки модели ($5 за миллион входных, $32 за миллион выходных токенов изображения, $10 за миллион выходных текстовых) это примерно $0.136 за вырез 1024x1024.

Одну вещь мы не стали докапывать: тот же размер на gpt-image-2 с background: "opaque" отчитался всего о 196 выходных токенах изображения. Если две модели отчитываются о токенах изображения в принципиально разных масштабах, считайте цену каждой модели по её собственному измеренному usage, а не исходя из того, что токены на мегапиксель — константа. Тот же аргумент для текстовых моделей мы разбирали в материале о том, что реально попадает в счёт.

Что делать, если у нужной модели прозрачности нет

Если вы привязаны к модели, которая теряет это поле, есть два честных варианта и один плохой.

• Генерируйте на однотонном фоне и вырезайте. Плоский неестественный цвет, которого нет в объекте, сильно упрощает последующую матировку. Медленнее и грязнее по краям, зато предсказуемо.
• Сгенерируйте ассет один раз на способной модели и переиспользуйте. Прозрачность — свойство файла, а не пайплайна. Один хороший вырез лучше сотни перерисовок.
• Не отгружайте 200, который вернулся непрозрачным. Он проявится белым прямоугольником на цветном слайде, а к тому моменту в партии будет уже тысяча файлов.

Про сами эндпоинты изображений: разбор Qwen Image 3.0 Pro покрывает ещё одно семейство из таблицы, а документация Google по генерации изображений перечисляет, что модели Gemini действительно выставляют наружу, — это стоит прочитать до того, как считать отсутствие функции проблемой маршрутизации.

Источники

• OpenAI cookbook: прозрачные изображения
• OpenAI: руководство по генерации изображений
• W3C: спецификация PNG, типы цвета IHDR
• Pillow: справочник Image
• Google: генерация изображений в Gemini API
• ofox, карточка модели: GPT Image 1.5
• ofox, карточка модели: GPT Image 2