На этой странице представлена информация по устранению распространенных ошибок, связанных с API Gemini и SDK Firebase AI Logic .
Если вы получаете ошибку 400 с сообщением API key not valid. Please pass a valid API key. , это обычно означает, что ключ API в вашем файле/объекте конфигурации Firebase не существует или не настроен для использования с вашим приложением и/или проектом Firebase.
Убедитесь, что ключ API, указанный в вашем файле/объекте конфигурации Firebase, совпадает с ключом API вашего приложения. Вы можете просмотреть все свои ключи API на панели «API и сервисы» > «Учетные данные» в консоли Google Cloud .
Если вы обнаружите, что они не совпадают, получите новый конфигурационный файл/объект Firebase и замените им тот, что находится в вашем приложении. Новый конфигурационный файл/объект должен содержать действительный ключ API для вашего приложения и проекта Firebase.
При попытке отправить многомодальный запрос с использованием URL-адреса Cloud Storage for Firebase вы можете столкнуться со следующей ошибкой 400:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Эта ошибка вызвана тем, что в проекте не были корректно настроены необходимые агенты службы при включении API платформы агентов . Это известная проблема в некоторых проектах, и мы работаем над ее глобальным исправлением.
Вот обходное решение для исправления вашего проекта и корректной настройки этих сервисных агентов, чтобы вы могли начать включать URL-адреса Cloud Storage for Firebase в ваши многомодальные запросы. Вы должны быть владельцем проекта, и вам нужно выполнить этот набор задач только один раз для вашего проекта.
Получите доступ и пройдите аутентификацию с помощью gcloud CLI .
Проще всего это сделать через Cloud Shell . Подробнее см. в документации Google Cloud .Если появится запрос, следуйте инструкциям, отображаемым в терминале, чтобы запустить gcloud CLI для вашего проекта Firebase.
Вам понадобится идентификатор вашего проекта Firebase, который можно найти в верхней части проекта в консоли Firebase .
Для создания необходимых сервисных агентов в вашем проекте выполните следующую команду:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
Подождите несколько минут, чтобы убедиться в готовности сервисных агентов, а затем повторите попытку отправки многомодального запроса, включающего URL-адрес Cloud Storage for Firebase .
Если ошибка сохраняется после нескольких минут ожидания, обратитесь в службу поддержки Firebase .
Если вы получаете ошибку 403 - PERMISSION_DENIED которая гласит: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check », это означает, что ваш запрос не имеет действительного токена App Check , и вы пытаетесь получить доступ к модели, которая часто используется не по назначению.
Было установлено, что некоторые генеративные модели часто используются злоумышленниками в своих целях.
Поскольку в вашем проекте не включена App Check для Firebase AI Logic , он уязвим для злоупотреблений этими моделями. Чтобы защитить наших разработчиков, Firebase блокирует доступ к этим моделям, если запрос не содержит действительный токен App Check (это означает, что App Check включена для Firebase AI Logic ).
Чтобы получить доступ к модели, вызвавшей ошибку, выполните следующие действия:
Настройте App Check для Firebase AI Logic . Для локальной разработки убедитесь, что вы настроили отладочный провайдер App Check .
Включение App Check имеет решающее значение для защиты API Gemini и моделей Gemini от злоупотреблений, и её принудительное включение необходимо для устранения этой ошибки.
Повторно отправьте запрос из вашего приложения в Firebase AI Logic .
Этот запрос отправит действительный токен App Check , и вы больше не будете получать ошибку
403 - PERMISSION_DENIED.Прежде чем выпустить приложение для конечных пользователей, необходимо настроить поставщика аттестации для производственной среды (например, App Attest, Play Integrity или reCAPTCHA Enterprise ), чтобы конечные пользователи могли получить доступ к функциям искусственного интеллекта при включении App Check ).
Если вы получаете ошибку 403 - PERMISSION_DENIED указывающую на то, что Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check , это означает, что ваш проект Firebase был идентифицирован как неактивный, и App Check Firebase AI Logic не включена.
«Неактивные проекты» — это проекты, в которых включена функция Firebase AI Logic , но которые в последнее время не использовались.
Поскольку в вашем проекте не включена App Check для Firebase AI Logic , он уязвим для злоупотреблений API Gemini . Для защиты вашего проекта Firebase отключил использование Firebase AI Logic до тех пор, пока вы не включите App Check для Firebase AI Logic .
Когда вы будете готовы снова начать использовать Firebase AI Logic , выполните следующие действия:
Настройте App Check для Firebase AI Logic . Для локальной разработки убедитесь, что вы настроили отладочный провайдер App Check .
Включение App Check имеет решающее значение для защиты API Gemini и моделей Gemini от злоупотреблений, и её принудительное включение необходимо для устранения этой ошибки.
Повторно отправьте запрос из вашего приложения в Firebase AI Logic .
Этот запрос отправит действительный токен App Check , и вы больше не будете получать ошибку
403 - PERMISSION_DENIED.Прежде чем выпустить приложение для конечных пользователей, необходимо настроить поставщика аттестации для производственной среды (например, App Attest, Play Integrity или reCAPTCHA Enterprise ), чтобы конечные пользователи могли получить доступ к функциям искусственного интеллекта при включении App Check ).
Если вы получаете ошибку 403 с сообщением PERMISSION_DENIED: The caller does not have permission. это обычно означает, что ключ API в вашем файле/объекте конфигурации Firebase принадлежит другому проекту Firebase.
Убедитесь, что ключ API, указанный в вашем файле/объекте конфигурации Firebase, совпадает с ключом API вашего приложения. Вы можете просмотреть все свои ключи API на панели «API и сервисы» > «Учетные данные» в консоли Google Cloud .
Если вы обнаружите, что они не совпадают, получите новый конфигурационный файл/объект Firebase и замените им тот, что находится в вашем приложении. Новый конфигурационный файл/объект должен содержать действительный ключ API для вашего приложения и проекта Firebase.
Если вы получаете ошибку 403 с сообщением « Requests to this API firebasevertexai.googleapis.com ... are blocked. , это обычно означает, что ключ API в конфигурации Firebase вашего приложения имеет ограничения, которые препятствуют вызову необходимого API.
Для решения этой проблемы необходимо обновить ограничения вашего API-ключа в консоли Google Cloud , добавив в них требуемый API. Для Firebase AI Logic необходимо убедиться, что API Firebase AI Logic ( firebasevertexai.googleapis.com ) включен в список API, которые можно вызывать с помощью данного API-ключа.
Выполните следующие шаги:
В консоли Google Cloud откройте панель «API и сервисы» > «Учетные данные» .
Выберите ключ API, который настроен для использования вашим приложением (например, «ключ iOS» для приложения iOS).
На странице редактирования ключа API найдите раздел «Ограничения API» .
Убедитесь, что выбран параметр «Ограничить доступ к ключу» . Если он не выбран, ваш ключ не имеет ограничений, и это, вероятно, не является причиной ошибки.
В раскрывающемся меню «Выбранные API» найдите и выберите Firebase AI Logic API , чтобы добавить его в список API, которые можно вызывать с помощью ключа API.
Нажмите « Сохранить ».
Для вступления изменений в силу может потребоваться до пяти минут.
Если вы получаете ошибку 404 с сообщением Firebase AI Logic genai config not found , это обычно означает, что какой-либо параметр Firebase AI Logic настроен неправильно или отсутствует.
Вот наиболее вероятные причины этой ошибки:
Вы еще не настроили свой проект Firebase для работы с API-провайдером Gemini .
Что делать:
В консоли Firebase перейдите в раздел AI Services > AI Logic . Нажмите «Начать» , а затем выберите поставщика API Gemini . Включите API, и Firebase настроит ваш проект для этого поставщика. После завершения процесса повторите запрос.Если вы совсем недавно выполняли настройку Firebase AI Logic в консоли Firebase , то конфигурация Firebase AI Logic может быть еще недоступна для всех необходимых серверных служб во всех соответствующих регионах.
Что делать:
Подождите несколько минут, а затем повторите запрос.
Например: " Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3.1-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version. "
Существует несколько причин, по которым может возникнуть подобная ошибка.
Недопустимое название модели
Причина : Указанное вами название модели не является допустимым.
Решение : Сравните название и версию вашей модели со списком всех поддерживаемых и доступных моделей . Убедитесь, что вы проверили сегменты и их порядок в названии модели. Например:
- Название последней модели Gemini 3.x Pro :
gemini-3.1-pro-preview(доступна только в режиме предварительного просмотра) - Название модели последней прошивки Gemini 3.x :
gemini-3.7-flash - Название последней модели Gemini 3.x Flash‑Lite :
gemini-3.5-flash-lite - Новейшая версия Gemini 3.x Pro Image (также известная как "Nano Banana Pro"), название модели:
gemini-3-pro-image - Последняя версия прошивки Gemini 3.x (также известная как "Nano Banana 2"), название модели:
gemini-3.1-flash-image - Новейшая модель Gemini 3.x Flash‑Lite Image (также известная как "Nano Banana 2 Lite"):
gemini-3.1-flash-lite-image - Новейшая модель вспышки Gemini 2.5 Flash Image (также известная как "Nano Banana"):
gemini-2.5-flash-image
- Название последней модели Gemini 3.x Pro :
Неверное местоположение (применимо только при использовании поставщика Agent Platform Gemini API (ранее Vertex AI) ).
Причина : Ваш запрос, возможно, пытается получить доступ к модели, которая находится в месте, где она недоступна.
Исправление : Убедитесь, что ваш запрос пытается получить доступ к модели, если она доступна.
При использовании API Agent Platform Gemini (ранее Vertex AI) вы можете дополнительно указать местоположение для доступа к модели во время инициализации. Если вы не укажете местоположение, Firebase AI Logic по умолчанию будет использовать следующие местоположения:
- При использовании синтаксиса инициализации "Агентской платформы":
global - При использовании устаревшего синтаксиса инициализации "Vertex AI":
us-central1
Однако не все модели поддерживаются в этих стандартных местах расположения. Это означает, что в зависимости от модели может потребоваться явное указание конкретного местоположения во время инициализации.
Предварительные и экспериментальные модели Gemini : доступны только в
globalкаталоге (за исключением моделей Live API — см. ниже).Модели Gemini 3.x : Доступно только в
globalрасположении при использовании Firebase AI Logic . Firebase AI Logic пока не поддерживает расположения вusиeu.Модели Gemini 2.5 : доступны во многих местах .
Модели Gemini Live API : доступны только в регионе
us-central1.globalрегион не поддерживается.
- При использовании синтаксиса инициализации "Агентской платформы":
Узнайте больше о том, как указать место для доступа к модели (включая фрагменты кода).
Существует несколько причин, по которым может возникнуть подобная ошибка.
Вы превышаете свою квоту или модель, к которой вы обращаетесь, перегружена запросами от других пользователей.
Дальнейшие действия зависят от того, используете ли вы API разработчика Gemini или API платформы агента Gemini (ранее Vertex AI) . Для получения дополнительной информации о квотах и о том, как запросить дополнительные квоты, см. раздел «Ограничения скорости и квоты» .
Если вы используете API Agent Platform Gemini (ранее Vertex AI) , в документации Google Cloud вы найдете дополнительную информацию и рекомендации по ошибке с кодом 429 .
Вы пытаетесь использовать модель или функцию, требующую оплаты, но ваш проект Firebase работает по тарифному плану Spark.
Если вы используете Gemini Developer API , вы можете получить ограниченный доступ к определенным моделям и многим базовым функциям на бесплатном уровне Gemini Developer API . Этот уровень позволяет начать работу без необходимости указывать способ оплаты, а это значит, что вам не нужно переходить на тарифный план Blaze с оплатой по мере использования.
Некоторые модели недоступны в «бесплатном» тарифе Gemini Developer API и требуют «платного» тарифа, то есть ваш проект должен быть подключен к тарифному плану Blaze с оплатой по мере использования. Например, следующие модели почти всегда требуют выставления счетов:
- Большинство предварительных и экспериментальных моделей
- Модели генерации изображений (модели «Нано-банан»)
Некоторые модели предлагают базовые функции в рамках «бесплатного» уровня Gemini Developer API , но для использования более продвинутых функций требуется «платный» уровень. Например:
- При использовании большинства моделей Gemini 3.x функция Grounding с
Google Search илиGoogle Maps требует оплаты.
- При использовании большинства моделей Gemini 3.x функция Grounding с
Узнайте о тарифных планах Firebase и API для разработчиков Gemini .
Для получения более подробной информации см. документацию по ценам на Gemini Developer API и раздел часто задаваемых вопросов о выставлении счетов .