Ошибки Image API: диагностика GPT Image, Gemini и Qwen
Диагностика ошибок API генерации изображений по слоям: авторизация, доступ к модели, параметры, квоты, фильтры, тайм-ауты и разбор ответа.
Ofox 
Ошибка Image API — не одна проблема. Сначала определите слой сбоя: авторизация, доступ к модели, параметры запроса, квота, модерация, мощность провайдера, тайм-аут клиента или разбор ответа.
Какие данные сохранить
время и часовой пояс:
хост и endpoint:
точный model ID:
HTTP-статус и полный текст ошибки:
request ID и retry headers:
SDK и версия:
генерация или редактирование:
есть ли reference image:
размер, качество, формат, фон:
длительность:
воспроизводится минимальным запросом: yes/noПеред публикацией удалите API-ключ, подписанные URL, конфиденциальные промпты и исходные изображения.
Определите слой сбоя по коду
| Симптом | Вероятная причина | Первое действие |
|---|---|---|
400 / INVALID_ARGUMENT | Схема запроса или неподдерживаемая функция | Проверить endpoint, поля, значения и версию API |
401 | Нет ключа или неверный формат | Проверить реально отправленные учётные данные |
403 / PERMISSION_DENIED | Доступ проекта или модели, ограничения ключа | Проверить аккаунт и полный ответ |
404 / model_not_found | Model ID, endpoint или права | Проверить ресурс, названный в ошибке |
429 / RESOURCE_EXHAUSTED | RPM/IPM, дневная квота, лимит расходов, баланс | Прочитать показатель квоты; повторять запрос только при временном ограничении |
| Safety-код, изображения нет | Заблокирован ввод или результат | Прочитать причину блокировки и изменить ввод |
500 / 503 | Сбой или нехватка мощности у провайдера | Сохранить request ID и ограниченно повторить |
504 / reset соединения | Тайм-аут модели, gateway или клиента | Найти компонент, который закрыл соединение первым |
HTTP 200, но результата нет | Ошибка парсинга или несовпадение возможностей | Проверить url, b64_json, MIME и альфа-канал |
Ошибки GPT Image
Запишите, используется ли Direct Images API или image generation tool внутри Responses. Тела их запросов не взаимозаменяемы. Сверьте запрос с документацией OpenAI.
При model_not_found проверьте полный model ID, хост, endpoint и проект, которому принадлежит ключ. Наличие модели в каталоге не доказывает доступ через любой API-интерфейс. Используйте инструкцию по model_not_found.
Параметры size, quality, background и output_format проверяйте для конкретной модели. Для прозрачности нужен png или webp; jpeg не сохраняет альфа-канал. См. руководство GPT Image 2.5 и диагностику прозрачного фона.
При задержке или 504 разделяйте тайм-аут клиента и ошибку upstream-модели. Запишите длительность и компонент, который вернул статус. Разбор сбоев GPT Image 2 помогает сопоставить симптом.
Ошибки Gemini / Nano Banana
GenerateContent может возвращать HTTP-код вместе с gRPC-подобными полями status и details. Таблица ошибок GenerateContent различает 400, 402, 403, 404, 429, 503 и 504.
У Interactions API есть отдельный формат ошибок: rate_limit_exceeded, image_safety, image_prohibited_content, image_recitation и no_image. Не ожидайте эти поля в ответе GenerateContent.
При 429 проверьте фактический проект ключа и названный показатель квоты. RPM, input tokens per minute, requests per day и images per minute — разные ограничения. Нулевая бесплатная квота не исправляется повтором. Для временных 429, 408 и 5xx следуйте официальной инструкции.
Ошибки Qwen Image
В таблице ниже приведены наблюдения теста маршрута Qwen Image, проведённого Ofox 23 июля 2026 года.
| Симптом | Диагноз | Действие |
|---|---|---|
429 Requests rate limit exceeded | Лимит тестового маршрута или скорости | Последовательные запросы, увеличение задержки, проверка текущего маршрута |
b64_json равен None | URL-ответ разбирается как base64 | Поддержать оба документированных формата |
HTTP 200, но объект с исходного изображения отсутствует | Исходное изображение могло быть проигнорировано | Проверять соответствие в результате |
model_not_found | Устаревший, недоступный или неверный ID | Проверить текущий каталог и доступ |
Это наблюдения конкретного маршрута на определённую дату, а не постоянная спецификация всех endpoint Alibaba или gateway.
Grok Imagine, Seedream и FLUX
После удаления или переназначения alias Grok запрос может остаться валидным, а поведение измениться. Записывайте в журнал модель, которая обработала запрос, и используйте руководство Grok Imagine и инструкцию по миграции.
Для других моделей начните с минимального документированного запроса и точного model ID. Определите, возвращается URL, base64 или асинхронный task. Затем по одному добавляйте size, quality, reference image, edit и transparency. Начальная схема есть в документации Ofox Image API.
Когда повторять запрос
Используйте ограниченное число повторных попыток с экспоненциальным увеличением задержки и случайным разбросом при сетевом сбое или временном ответе 408, 429, 500 либо 503. Некорректные параметры, ключ, права, нулевая квота, исчерпанный баланс, safety-блок и ошибка парсера требуют исправления причины.
Проверьте, не выполняет ли SDK повтор автоматически. После обрыва или тайм-аута завершение задачи может быть неизвестно. Если API возвращает task ID, запросите существующую задачу перед новой отправкой. Idempotency используйте только там, где endpoint явно её документирует. Слепой retry может создать дубликат или вторую оплачиваемую задачу.
Связанные инструкции
| Симптом | Узкая инструкция |
|---|---|
| GPT Image работает медленно или возвращает 504 | Диагностика GPT Image 2 |
| Прозрачный фон не поддерживается | Ошибка прозрачного фона |
OpenAI model_not_found | Model ID, права и endpoint |
| Qwen 429 или несовпадение URL/base64 | Тест маршрута Qwen Image |
| 429 у любого провайдера | Решение о повторе 429 |
Источники
Часто задаваемые вопросы
- Что сохранять при ошибке Image API?
- Сохраните время и часовой пояс, хост, endpoint, точный model ID, HTTP-статус, полный очищенный от секретов текст ошибки, request ID, важные заголовки ответа, SDK и версию, параметры ввода и вывода, длительность и результат минимального воспроизводимого запроса.
- Нужно ли повторять любой запрос с ошибкой 429?
- Нет. Используйте ограниченное число повторных попыток с экспоненциальным увеличением задержки и случайным разбросом только при временном лимите или нехватке мощности. Нулевая квота, исчерпанный баланс и отключённый биллинг требуют изменения настроек или состояния аккаунта.
- Почему API вернул HTTP 200, но изображение нельзя использовать?
- API мог вернуть URL вместо b64_json, проигнорировать неподдерживаемое поле исходного изображения или создать файл без альфа-канала. Проверяйте поля ответа и сам файл, а не только статус.
- Исправит ли ошибку смена модели?
- Только если причина связана с возможностями, доступом или мощностью модели. Смена модели не исправит отсутствующий ключ, неверный endpoint, некорректный payload или ошибку парсера.
