Руководство по устранению неполадок

Это руководство поможет вам диагностировать и устранять распространенные проблемы, возникающие при вызове API Gemini. Проблемы могут возникать как в бэкэнде API Gemini, так и в клиентских SDK. Наши клиентские SDK находятся в открытом доступе в следующих репозиториях:

Если у вас возникли проблемы с ключом API, убедитесь, что вы правильно настроили свой ключ API в соответствии с руководством по настройке ключа API .

коды ошибок

Полный список всех кодов ошибок, включая коды состояния HTTP, коды блокировки генерации и коды ошибок содержимого, см. на странице ошибок API .

Стратегия повторной попытки

Если вы получили ошибку, указывающую на необходимость повторной попытки запроса (например, 429 RESOURCE_EXHAUSTED или 503 UNAVAILABLE ), мы рекомендуем использовать стратегию экспоненциальной задержки. Это означает, что вы ждете короткое время перед первой повторной попыткой, а затем постепенно увеличиваете время ожидания между последующими попытками.

Официальные клиентские SDK для API Gemini, такие как Python SDK , включают в себя логику автоматического повтора попыток с экспоненциальной задержкой по умолчанию для обработки временных ошибок, таких как тайм-ауты, проблемы с сетью и ограничения скорости (коды состояния 429 и 5xx ). Например, Python SDK автоматически повторяет попытки при временных ошибках до четырех раз с начальной задержкой примерно в 1 секунду и максимальной задержкой в ​​60 секунд.

Если вы отправляете прямые запросы к REST API или настраиваете логику повторных попыток, следуйте этим рекомендациям, чтобы повысить вероятность успешного запроса и предотвратить перегрузку сервиса:

  • Используйте экспоненциальную задержку: подождите немного времени перед первой попыткой (например, 1 секунду), затем увеличивайте задержку экспоненциально (например, 2 с, 4 с, 8 с).
  • Добавить дрожание: Добавьте случайное «дрожание» к задержке, чтобы предотвратить одновременную повторную попытку подключения всех клиентов.
  • Повторная попытка при определенных ошибках: Повторяйте попытку только при временных ошибках (например, 429 , 408 или 5xx ). Не повторяйте попытку при ошибках клиента (например, 400 , 402 или 403 ), поскольку они указывают на такие проблемы, как недействительные ключи API, исчерпанные предоплаченные средства или некорректный синтаксис.
  • Установите максимальное количество попыток: задайте максимальное число попыток повторного выполнения, чтобы предотвратить бесконечные циклы.

Проверьте вызовы API на наличие ошибок, связанных с параметрами модели.

Убедитесь, что параметры вашей модели находятся в пределах следующих значений:

Параметр модели Значения (диапазон)
Количество кандидатов 1-8 (целое число)
Температура 0.0-1.0
Максимальное количество выходных токенов Используйте страницу моделей , чтобы определить максимальное количество токенов для используемой вами модели.
ТопП 0.0-1.0

Помимо проверки значений параметров, убедитесь, что вы используете правильную версию API (например, /v1 или /v1beta ) и модель, поддерживающую необходимые вам функции. Например, если функция находится в бета-версии, она будет доступна только в версии API /v1beta .

Проверьте, подходит ли вам данная модель.

Убедитесь, что вы используете поддерживаемую модель, указанную на нашей странице моделей .

Более высокая задержка или использование токенов при работе с моделями мышления.

Более высокая задержка или расход токенов часто возникают из-за того, что в моделях Gemini 3.x функция "мышления" включена по умолчанию. В устаревших моделях Gemini 2.5 также используется функция "мышления" по умолчанию.

Мышление, основанное на моделях, генерирует внутренние токены рассуждений для повышения качества. Этот процесс рассуждений увеличивает как время отклика, так и общее потребление токенов.

Если для вас приоритетом является снижение задержки или необходимость минимизации затрат, вы можете снизить уровень мышления или отключить его.

Подробную информацию о настройке и примеры кода см. в руководстве по планированию .

Вопросы безопасности

Если вы видите, что запрос был заблокирован из-за настроек безопасности в вашем вызове API, проверьте запрос на соответствие фильтрам, которые вы установили в вызове API.

Если вы видите BlockedReason.OTHER , это означает, что запрос или ответ могут нарушать условия предоставления услуг или быть неподдерживаемыми по другим причинам.

Вопрос о декламации

Если вы видите, что модель перестает генерировать выходные данные по причине RECITATION, это означает, что выходные данные модели могут быть похожи на определенные данные. Чтобы исправить это, попробуйте сделать подсказку/контекст максимально уникальными и используйте более высокую температуру.

Повторная выдача токенов

Если вы видите повторяющиеся выходные токены, попробуйте следующие рекомендации, чтобы уменьшить или устранить их.

Описание Причина Предложенное решение
Повторяющиеся дефисы в таблицах Markdown Это может произойти, когда содержимое таблицы слишком длинное, поскольку модель пытается создать визуально выровненную таблицу в формате Markdown. Однако выравнивание в Markdown не является обязательным для корректного отображения.

Добавьте в запрос инструкции, чтобы указать модели конкретные рекомендации по генерации таблиц Markdown. Приведите примеры, соответствующие этим рекомендациям. Вы также можете попробовать отрегулировать температуру. Для генерации кода или очень структурированного вывода, такого как таблицы Markdown, более высокая температура (>= 0,8) показала лучшие результаты.

Ниже приведён пример набора рекомендаций, которые вы можете добавить в своё сообщение, чтобы предотвратить эту проблему:

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
Повторяющиеся токены в таблицах Markdown Подобно повторяющимся дефисам, это происходит, когда модель пытается визуально выровнять содержимое таблицы. Выравнивание в Markdown не требуется для корректного отображения.
  • Попробуйте добавить в командную строку системы следующие инструкции: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Попробуйте отрегулировать температуру. Более высокие температуры (>= 0,8) обычно помогают устранить повторения или дублирование в выходных данных.
Повторяющиеся символы новой строки ( \n ) в структурированном выводе Когда входные данные модели содержат символы Юникода или управляющие последовательности, такие как \u или \t , это может привести к повторению символов новой строки.
  • Проверьте и замените запрещенные escape-последовательности символами UTF-8 в вашем приглашении ввода. Например, escape-последовательность \u в ваших примерах JSON может привести к тому, что модель будет использовать ее и в своих выходных данных.
  • Укажите модели, какие выходы допустимы. Добавьте системную инструкцию следующего вида: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
Повторяющийся текст при использовании структурированного вывода Если порядок полей в выходных данных модели отличается от заданной структурированной схемы, это может привести к повторению текста.
  • В подсказке не указывайте порядок полей.
  • Сделайте все поля вывода обязательными.
Повторяющиеся вызовы инструментов Это может произойти, если модель теряет контекст предыдущих мыслей и/или вызывает недоступную конечную точку, к которой она вынуждена обращаться. Дайте модели указание поддерживать состояние в процессе мышления. Добавьте это в конец инструкций вашей системы: 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
Повторяющийся текст, не являющийся частью структурированного вывода. Это может произойти, если модель зависнет на запросе, который она не может обработать.
  • Если вы настроены на размышление, избегайте давать явные указания о том, как решать задачу. Просто попросите показать конечный результат.
  • Попробуйте более высокую температуру >= 0,8.
  • Добавьте указания типа «Будьте краткими», «Не повторяйтесь» или «Дайте ответ один раз».

Заблокированные или неработающие ключи API

В этом разделе описано, как проверить, заблокирован ли ваш API-ключ Gemini, и что с этим делать.

Разберитесь, почему ключи заблокированы.

Мы выявили уязвимость, из-за которой некоторые ключи API могли быть публично доступны. Для защиты ваших данных и предотвращения несанкционированного доступа мы заблаговременно заблокировали доступ к API Gemini для этих известных утечек ключей.

Уточните, затронуты ли ваши ключи.

Если известно, что ваш ключ был скомпрометирован, вы больше не сможете использовать его с API Gemini. Вы можете использовать Google AI Studio, чтобы проверить, заблокированы ли какие-либо из ваших ключей API для вызова API Gemini, и сгенерировать новые ключи. При попытке использования этих ключей вы также можете увидеть следующую ошибку:

Your API key was reported as leaked. Please use another API key.

Действия в случае блокировки ключей API

Для интеграции с Gemini API следует генерировать новые ключи API с помощью Google AI Studio . Мы настоятельно рекомендуем пересмотреть ваши методы управления ключами API, чтобы убедиться в безопасности новых ключей и предотвратить их публичное раскрытие.

Непредвиденные расходы из-за уязвимости

Отправьте запрос в службу поддержки по вопросам выставления счетов . Наша команда по вопросам выставления счетов работает над этим, и мы сообщим вам о результатах как можно скорее.

Меры безопасности Google в отношении утечек ключей

Как Google собирается защитить мой аккаунт от перерасхода средств и злоупотреблений, если мои API-ключи будут скомпрометированы?

  • Мы переходим к выдаче API-ключей при запросе нового ключа через Google AI Studio. По умолчанию эти ключи будут доступны только через Google AI Studio и не будут приниматься от других сервисов. Это поможет предотвратить непреднамеренное использование ключей разных сервисов.
  • По умолчанию мы блокируем ключи API, которые были скомпрометированы и использованы с API Gemini, что помогает предотвратить злоупотребления в отношении стоимости и данных вашего приложения.
  • Вы сможете отслеживать статус своих API-ключей в Google AI Studio , и мы будем заблаговременно сообщать вам о случаях утечки ваших API-ключей для принятия незамедлительных мер.

Улучшить результаты работы модели.

Для получения более качественных результатов моделирования изучите возможность написания более структурированных запросов. На странице руководства по разработке запросов представлены основные понятия, стратегии и лучшие практики, которые помогут вам начать работу.

Ознакомьтесь с ограничениями по токенам.

Ознакомьтесь с нашим руководством по токенам , чтобы лучше понять, как подсчитывать токены и каковы их лимиты.

Известные проблемы

  • API поддерживает только ряд ограниченного числа языков. Отправка запросов на неподдерживаемых языках может привести к неожиданным или даже заблокированным ответам. Для получения информации об обновлениях смотрите раздел «Доступные языки» .

Сообщить об ошибке

Если у вас есть вопросы, присоединяйтесь к обсуждению на форуме разработчиков Google AI .

,

Это руководство поможет вам диагностировать и устранять распространенные проблемы, возникающие при вызове API Gemini. Проблемы могут возникать как в бэкэнде API Gemini, так и в клиентских SDK. Наши клиентские SDK находятся в открытом доступе в следующих репозиториях:

Если у вас возникли проблемы с ключом API, убедитесь, что вы правильно настроили свой ключ API в соответствии с руководством по настройке ключа API .

коды ошибок

Полный список всех кодов ошибок, включая коды состояния HTTP, коды блокировки генерации и коды ошибок содержимого, см. на странице ошибок API .

Стратегия повторной попытки

Если вы получили ошибку, указывающую на необходимость повторной попытки запроса (например, 429 RESOURCE_EXHAUSTED или 503 UNAVAILABLE ), мы рекомендуем использовать стратегию экспоненциальной задержки. Это означает, что вы ждете короткое время перед первой повторной попыткой, а затем постепенно увеличиваете время ожидания между последующими попытками.

Официальные клиентские SDK для API Gemini, такие как Python SDK , включают в себя логику автоматического повтора попыток с экспоненциальной задержкой по умолчанию для обработки временных ошибок, таких как тайм-ауты, проблемы с сетью и ограничения скорости (коды состояния 429 и 5xx ). Например, Python SDK автоматически повторяет попытки при временных ошибках до четырех раз с начальной задержкой примерно в 1 секунду и максимальной задержкой в ​​60 секунд.

Если вы отправляете прямые запросы к REST API или настраиваете логику повторных попыток, следуйте этим рекомендациям, чтобы повысить вероятность успешного запроса и предотвратить перегрузку сервиса:

  • Используйте экспоненциальную задержку: подождите немного времени перед первой попыткой (например, 1 секунду), затем увеличивайте задержку экспоненциально (например, 2 с, 4 с, 8 с).
  • Добавить дрожание: Добавьте случайное «дрожание» к задержке, чтобы предотвратить одновременную повторную попытку подключения всех клиентов.
  • Повторная попытка при определенных ошибках: Повторяйте попытку только при временных ошибках (например, 429 , 408 или 5xx ). Не повторяйте попытку при ошибках клиента (например, 400 , 402 или 403 ), поскольку они указывают на такие проблемы, как недействительные ключи API, исчерпанные предоплаченные средства или некорректный синтаксис.
  • Установите максимальное количество попыток: задайте максимальное число попыток повторного выполнения, чтобы предотвратить бесконечные циклы.

Проверьте вызовы API на наличие ошибок, связанных с параметрами модели.

Убедитесь, что параметры вашей модели находятся в пределах следующих значений:

Параметр модели Значения (диапазон)
Количество кандидатов 1-8 (целое число)
Температура 0.0-1.0
Максимальное количество выходных токенов Используйте страницу моделей , чтобы определить максимальное количество токенов для используемой вами модели.
ТопП 0.0-1.0

Помимо проверки значений параметров, убедитесь, что вы используете правильную версию API (например, /v1 или /v1beta ) и модель, поддерживающую необходимые вам функции. Например, если функция находится в бета-версии, она будет доступна только в версии API /v1beta .

Проверьте, подходит ли вам данная модель.

Убедитесь, что вы используете поддерживаемую модель, указанную на нашей странице моделей .

Более высокая задержка или использование токенов при работе с моделями мышления.

Более высокая задержка или расход токенов часто возникают из-за того, что в моделях Gemini 3.x функция "мышления" включена по умолчанию. В устаревших моделях Gemini 2.5 также используется функция "мышления" по умолчанию.

Мышление, основанное на моделях, генерирует внутренние токены рассуждений для повышения качества. Этот процесс рассуждений увеличивает как время отклика, так и общее потребление токенов.

Если для вас приоритетом является снижение задержки или необходимость минимизации затрат, вы можете снизить уровень мышления или отключить его.

Подробную информацию о настройке и примеры кода см. в руководстве по планированию .

Вопросы безопасности

Если вы видите, что запрос был заблокирован из-за настроек безопасности в вашем вызове API, проверьте запрос на соответствие фильтрам, которые вы установили в вызове API.

Если вы видите BlockedReason.OTHER , это означает, что запрос или ответ могут нарушать условия предоставления услуг или быть неподдерживаемыми по другим причинам.

Вопрос о декламации

Если вы видите, что модель перестает генерировать выходные данные по причине RECITATION, это означает, что выходные данные модели могут быть похожи на определенные данные. Чтобы исправить это, попробуйте сделать подсказку/контекст максимально уникальными и используйте более высокую температуру.

Повторная выдача токенов

Если вы видите повторяющиеся выходные токены, попробуйте следующие рекомендации, чтобы уменьшить или устранить их.

Описание Причина Предложенное решение
Повторяющиеся дефисы в таблицах Markdown Это может произойти, когда содержимое таблицы слишком длинное, поскольку модель пытается создать визуально выровненную таблицу в формате Markdown. Однако выравнивание в Markdown не является обязательным для корректного отображения.

Добавьте в запрос инструкции, чтобы указать модели конкретные рекомендации по генерации таблиц Markdown. Приведите примеры, соответствующие этим рекомендациям. Вы также можете попробовать отрегулировать температуру. Для генерации кода или очень структурированного вывода, такого как таблицы Markdown, более высокая температура (>= 0,8) показала лучшие результаты.

Ниже приведён пример набора рекомендаций, которые вы можете добавить в своё сообщение, чтобы предотвратить эту проблему:

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
Повторяющиеся токены в таблицах Markdown Подобно повторяющимся дефисам, это происходит, когда модель пытается визуально выровнять содержимое таблицы. Выравнивание в Markdown не требуется для корректного отображения.
  • Попробуйте добавить в командную строку системы следующие инструкции: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Попробуйте отрегулировать температуру. Более высокие температуры (>= 0,8) обычно помогают устранить повторения или дублирование в выходных данных.
Повторяющиеся символы новой строки ( \n ) в структурированном выводе Когда входные данные модели содержат символы Юникода или управляющие последовательности, такие как \u или \t , это может привести к повторению символов новой строки.
  • Проверьте и замените запрещенные escape-последовательности символами UTF-8 в вашем приглашении ввода. Например, escape-последовательность \u в ваших примерах JSON может привести к тому, что модель будет использовать ее и в своих выходных данных.
  • Укажите модели, какие выходы допустимы. Добавьте системную инструкцию следующего вида: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
Повторяющийся текст при использовании структурированного вывода Если порядок полей в выходных данных модели отличается от заданной структурированной схемы, это может привести к повторению текста.
  • В подсказке не указывайте порядок полей.
  • Сделайте все поля вывода обязательными.
Повторяющиеся вызовы инструментов Это может произойти, если модель теряет контекст предыдущих мыслей и/или вызывает недоступную конечную точку, к которой она вынуждена обращаться. Дайте модели указание поддерживать состояние в процессе мышления. Добавьте это в конец инструкций вашей системы: 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
Повторяющийся текст, не являющийся частью структурированного вывода. Это может произойти, если модель зависнет на запросе, который она не может обработать.
  • Если вы настроены на размышление, избегайте давать явные указания о том, как решать задачу. Просто попросите показать конечный результат.
  • Попробуйте более высокую температуру >= 0,8.
  • Добавьте указания типа «Будьте краткими», «Не повторяйтесь» или «Дайте ответ один раз».

Заблокированные или неработающие ключи API

В этом разделе описано, как проверить, заблокирован ли ваш API-ключ Gemini, и что с этим делать.

Разберитесь, почему ключи заблокированы.

Мы выявили уязвимость, из-за которой некоторые ключи API могли быть публично доступны. Для защиты ваших данных и предотвращения несанкционированного доступа мы заблаговременно заблокировали доступ к API Gemini для этих известных утечек ключей.

Уточните, затронуты ли ваши ключи.

Если известно, что ваш ключ был скомпрометирован, вы больше не сможете использовать его с API Gemini. Вы можете использовать Google AI Studio, чтобы проверить, заблокированы ли какие-либо из ваших ключей API для вызова API Gemini, и сгенерировать новые ключи. При попытке использования этих ключей вы также можете увидеть следующую ошибку:

Your API key was reported as leaked. Please use another API key.

Действия в случае блокировки ключей API

Для интеграции с Gemini API следует генерировать новые ключи API с помощью Google AI Studio . Мы настоятельно рекомендуем пересмотреть ваши методы управления ключами API, чтобы убедиться в безопасности новых ключей и предотвратить их публичное раскрытие.

Непредвиденные расходы из-за уязвимости

Отправьте запрос в службу поддержки по вопросам выставления счетов . Наша команда по вопросам выставления счетов работает над этим, и мы сообщим вам о результатах как можно скорее.

Меры безопасности Google в отношении утечек ключей

Как Google собирается защитить мой аккаунт от перерасхода средств и злоупотреблений, если мои API-ключи будут скомпрометированы?

  • Мы переходим к выдаче API-ключей при запросе нового ключа через Google AI Studio. По умолчанию эти ключи будут доступны только через Google AI Studio и не будут приниматься от других сервисов. Это поможет предотвратить непреднамеренное использование ключей разных сервисов.
  • По умолчанию мы блокируем ключи API, которые были скомпрометированы и использованы с API Gemini, что помогает предотвратить злоупотребления в отношении стоимости и данных вашего приложения.
  • Вы сможете отслеживать статус своих API-ключей в Google AI Studio , и мы будем заблаговременно сообщать вам о случаях утечки ваших API-ключей для принятия незамедлительных мер.

Улучшить результаты работы модели.

Для получения более качественных результатов моделирования изучите возможность написания более структурированных запросов. На странице руководства по разработке запросов представлены основные понятия, стратегии и лучшие практики, которые помогут вам начать работу.

Ознакомьтесь с ограничениями по токенам.

Ознакомьтесь с нашим руководством по токенам , чтобы лучше понять, как подсчитывать токены и каковы их лимиты.

Известные проблемы

  • API поддерживает только ряд ограниченного числа языков. Отправка запросов на неподдерживаемых языках может привести к неожиданным или даже заблокированным ответам. Для получения информации об обновлениях смотрите раздел «Доступные языки» .

Сообщить об ошибке

Если у вас есть вопросы, присоединяйтесь к обсуждению на форуме разработчиков Google AI .

,

Это руководство поможет вам диагностировать и устранять распространенные проблемы, возникающие при вызове API Gemini. Проблемы могут возникать как в бэкэнде API Gemini, так и в клиентских SDK. Наши клиентские SDK находятся в открытом доступе в следующих репозиториях:

Если у вас возникли проблемы с ключом API, убедитесь, что вы правильно настроили свой ключ API в соответствии с руководством по настройке ключа API .

коды ошибок

Полный список всех кодов ошибок, включая коды состояния HTTP, коды блокировки генерации и коды ошибок содержимого, см. на странице ошибок API .

Стратегия повторной попытки

Если вы получили ошибку, указывающую на необходимость повторной попытки запроса (например, 429 RESOURCE_EXHAUSTED или 503 UNAVAILABLE ), мы рекомендуем использовать стратегию экспоненциальной задержки. Это означает, что вы ждете короткое время перед первой повторной попыткой, а затем постепенно увеличиваете время ожидания между последующими попытками.

Официальные клиентские SDK для API Gemini, такие как Python SDK , включают в себя логику автоматического повтора попыток с экспоненциальной задержкой по умолчанию для обработки временных ошибок, таких как тайм-ауты, проблемы с сетью и ограничения скорости (коды состояния 429 и 5xx ). Например, Python SDK автоматически повторяет попытки при временных ошибках до четырех раз с начальной задержкой примерно в 1 секунду и максимальной задержкой в ​​60 секунд.

Если вы отправляете прямые запросы к REST API или настраиваете логику повторных попыток, следуйте этим рекомендациям, чтобы повысить вероятность успешного запроса и предотвратить перегрузку сервиса:

  • Используйте экспоненциальную задержку: подождите немного времени перед первой попыткой (например, 1 секунду), затем увеличивайте задержку экспоненциально (например, 2 с, 4 с, 8 с).
  • Добавить дрожание: Добавьте случайное «дрожание» к задержке, чтобы предотвратить одновременную повторную попытку подключения всех клиентов.
  • Повторная попытка при определенных ошибках: Повторяйте попытку только при временных ошибках (например, 429 , 408 или 5xx ). Не повторяйте попытку при ошибках клиента (например, 400 , 402 или 403 ), поскольку они указывают на такие проблемы, как недействительные ключи API, исчерпанные предоплаченные средства или некорректный синтаксис.
  • Установите максимальное количество попыток: задайте максимальное число попыток повторного выполнения, чтобы предотвратить бесконечные циклы.

Проверьте вызовы API на наличие ошибок, связанных с параметрами модели.

Убедитесь, что параметры вашей модели находятся в пределах следующих значений:

Параметр модели Значения (диапазон)
Количество кандидатов 1-8 (целое число)
Температура 0.0-1.0
Максимальное количество выходных токенов Используйте страницу моделей , чтобы определить максимальное количество токенов для используемой вами модели.
ТопП 0.0-1.0

Помимо проверки значений параметров, убедитесь, что вы используете правильную версию API (например, /v1 или /v1beta ) и модель, поддерживающую необходимые вам функции. Например, если функция находится в бета-версии, она будет доступна только в версии API /v1beta .

Проверьте, подходит ли вам данная модель.

Убедитесь, что вы используете поддерживаемую модель, указанную на нашей странице моделей .

Более высокая задержка или использование токенов при работе с моделями мышления.

Более высокая задержка или расход токенов часто возникают из-за того, что в моделях Gemini 3.x функция "мышления" включена по умолчанию. В устаревших моделях Gemini 2.5 также используется функция "мышления" по умолчанию.

Мышление, основанное на моделях, генерирует внутренние токены рассуждений для повышения качества. Этот процесс рассуждений увеличивает как время отклика, так и общее потребление токенов.

Если для вас приоритетом является снижение задержки или необходимость минимизации затрат, вы можете снизить уровень мышления или отключить его.

Подробную информацию о настройке и примеры кода см. в руководстве по планированию .

Вопросы безопасности

Если вы видите, что запрос был заблокирован из-за настроек безопасности в вашем вызове API, проверьте запрос на соответствие фильтрам, которые вы установили в вызове API.

Если вы видите BlockedReason.OTHER , это означает, что запрос или ответ могут нарушать условия предоставления услуг или быть неподдерживаемыми по другим причинам.

Вопрос о декламации

Если вы видите, что модель перестает генерировать выходные данные по причине RECITATION, это означает, что выходные данные модели могут быть похожи на определенные данные. Чтобы исправить это, попробуйте сделать подсказку/контекст максимально уникальными и используйте более высокую температуру.

Повторная выдача токенов

Если вы видите повторяющиеся выходные токены, попробуйте следующие рекомендации, чтобы уменьшить или устранить их.

Описание Причина Предложенное решение
Повторяющиеся дефисы в таблицах Markdown Это может произойти, когда содержимое таблицы слишком длинное, поскольку модель пытается создать визуально выровненную таблицу в формате Markdown. Однако выравнивание в Markdown не является обязательным для корректного отображения.

Добавьте в запрос инструкции, чтобы указать модели конкретные рекомендации по генерации таблиц Markdown. Приведите примеры, соответствующие этим рекомендациям. Вы также можете попробовать отрегулировать температуру. Для генерации кода или очень структурированного вывода, такого как таблицы Markdown, более высокая температура (>= 0,8) показала лучшие результаты.

Ниже приведён пример набора рекомендаций, которые вы можете добавить в своё сообщение, чтобы предотвратить эту проблему:

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
Повторяющиеся токены в таблицах Markdown Подобно повторяющимся дефисам, это происходит, когда модель пытается визуально выровнять содержимое таблицы. Выравнивание в Markdown не требуется для корректного отображения.
  • Попробуйте добавить в командную строку системы следующие инструкции: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Попробуйте отрегулировать температуру. Более высокие температуры (>= 0,8) обычно помогают устранить повторения или дублирование в выходных данных.
Повторяющиеся символы новой строки ( \n ) в структурированном выводе Когда входные данные модели содержат символы Юникода или управляющие последовательности, такие как \u или \t , это может привести к повторению символов новой строки.
  • Проверьте и замените запрещенные escape-последовательности символами UTF-8 в вашем приглашении ввода. Например, escape-последовательность \u в ваших примерах JSON может привести к тому, что модель будет использовать ее и в своих выходных данных.
  • Укажите модели, какие выходы допустимы. Добавьте системную инструкцию следующего вида: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
Повторяющийся текст при использовании структурированного вывода Если порядок полей в выходных данных модели отличается от заданной структурированной схемы, это может привести к повторению текста.
  • В подсказке не указывайте порядок полей.
  • Сделайте все поля вывода обязательными.
Повторяющиеся вызовы инструментов Это может произойти, если модель теряет контекст предыдущих мыслей и/или вызывает недоступную конечную точку, к которой она вынуждена обращаться. Дайте модели указание поддерживать состояние в процессе мышления. Добавьте это в конец инструкций вашей системы: 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
Повторяющийся текст, не являющийся частью структурированного вывода. Это может произойти, если модель зависнет на запросе, который она не может обработать.
  • Если вы настроены на размышление, избегайте давать явные указания о том, как решать задачу. Просто попросите показать конечный результат.
  • Попробуйте более высокую температуру >= 0,8.
  • Добавьте указания типа «Будьте краткими», «Не повторяйтесь» или «Дайте ответ один раз».

Заблокированные или неработающие ключи API

В этом разделе описано, как проверить, заблокирован ли ваш API-ключ Gemini, и что с этим делать.

Разберитесь, почему ключи заблокированы.

Мы выявили уязвимость, из-за которой некоторые ключи API могли быть публично доступны. Для защиты ваших данных и предотвращения несанкционированного доступа мы заблаговременно заблокировали доступ к API Gemini для этих известных утечек ключей.

Уточните, затронуты ли ваши ключи.

Если известно, что ваш ключ был скомпрометирован, вы больше не сможете использовать его с API Gemini. Вы можете использовать Google AI Studio, чтобы проверить, заблокированы ли какие-либо из ваших ключей API для вызова API Gemini, и сгенерировать новые ключи. При попытке использования этих ключей вы также можете увидеть следующую ошибку:

Your API key was reported as leaked. Please use another API key.

Действия в случае блокировки ключей API

Для интеграции с Gemini API следует генерировать новые ключи API с помощью Google AI Studio . Мы настоятельно рекомендуем пересмотреть ваши методы управления ключами API, чтобы убедиться в безопасности новых ключей и предотвратить их публичное раскрытие.

Непредвиденные расходы из-за уязвимости

Отправьте запрос в службу поддержки по вопросам выставления счетов . Наша команда по вопросам выставления счетов работает над этим, и мы сообщим вам о результатах как можно скорее.

Меры безопасности Google в отношении утечек ключей

Как Google собирается защитить мой аккаунт от перерасхода средств и злоупотреблений, если мои API-ключи будут скомпрометированы?

  • Мы переходим к выдаче API-ключей при запросе нового ключа через Google AI Studio. По умолчанию эти ключи будут доступны только через Google AI Studio и не будут приниматься от других сервисов. Это поможет предотвратить непреднамеренное использование ключей разных сервисов.
  • По умолчанию мы блокируем ключи API, которые были скомпрометированы и использованы с API Gemini, что помогает предотвратить злоупотребления в отношении стоимости и данных вашего приложения.
  • Вы сможете отслеживать статус своих API-ключей в Google AI Studio , и мы будем заблаговременно сообщать вам о случаях утечки ваших API-ключей для принятия незамедлительных мер.

Улучшить результаты работы модели.

Для получения более качественных результатов моделирования изучите возможность написания более структурированных запросов. На странице руководства по разработке запросов представлены основные понятия, стратегии и лучшие практики, которые помогут вам начать работу.

Ознакомьтесь с ограничениями по токенам.

Ознакомьтесь с нашим руководством по токенам , чтобы лучше понять, как подсчитывать токены и каковы их лимиты.

Известные проблемы

  • API поддерживает только ряд ограниченного числа языков. Отправка запросов на неподдерживаемых языках может привести к неожиданным или даже заблокированным ответам. Для получения информации об обновлениях смотрите раздел «Доступные языки» .

Сообщить об ошибке

Если у вас есть вопросы, присоединяйтесь к обсуждению на форуме разработчиков Google AI .

,

Это руководство поможет вам диагностировать и устранять распространенные проблемы, возникающие при вызове API Gemini. Проблемы могут возникать как в бэкэнде API Gemini, так и в клиентских SDK. Наши клиентские SDK находятся в открытом доступе в следующих репозиториях:

Если у вас возникли проблемы с ключом API, убедитесь, что вы правильно настроили свой ключ API в соответствии с руководством по настройке ключа API .

коды ошибок

Полный список всех кодов ошибок, включая коды состояния HTTP, коды блокировки генерации и коды ошибок содержимого, см. на странице ошибок API .

Стратегия повторной попытки

Если вы получили ошибку, указывающую на необходимость повторной попытки запроса (например, 429 RESOURCE_EXHAUSTED или 503 UNAVAILABLE ), мы рекомендуем использовать стратегию экспоненциальной задержки. Это означает, что вы ждете короткое время перед первой повторной попыткой, а затем постепенно увеличиваете время ожидания между последующими попытками.

Официальные клиентские SDK для API Gemini, такие как Python SDK , включают в себя логику автоматического повтора попыток с экспоненциальной задержкой по умолчанию для обработки временных ошибок, таких как тайм-ауты, проблемы с сетью и ограничения скорости (коды состояния 429 и 5xx ). Например, Python SDK автоматически повторяет попытки при временных ошибках до четырех раз с начальной задержкой примерно в 1 секунду и максимальной задержкой в ​​60 секунд.

Если вы отправляете прямые запросы к REST API или настраиваете логику повторных попыток, следуйте этим рекомендациям, чтобы повысить вероятность успешного запроса и предотвратить перегрузку сервиса:

  • Используйте экспоненциальную задержку: подождите немного времени перед первой попыткой (например, 1 секунду), затем увеличивайте задержку экспоненциально (например, 2 с, 4 с, 8 с).
  • Добавить дрожание: Добавьте случайное «дрожание» к задержке, чтобы предотвратить одновременную повторную попытку подключения всех клиентов.
  • Повторная попытка при определенных ошибках: Повторяйте попытку только при временных ошибках (например, 429 , 408 или 5xx ). Не повторяйте попытку при ошибках клиента (например, 400 , 402 или 403 ), поскольку они указывают на такие проблемы, как недействительные ключи API, исчерпанные предоплаченные средства или некорректный синтаксис.
  • Установите максимальное количество попыток: задайте максимальное число попыток повторного выполнения, чтобы предотвратить бесконечные циклы.

Проверьте вызовы API на наличие ошибок, связанных с параметрами модели.

Убедитесь, что параметры вашей модели находятся в пределах следующих значений:

Параметр модели Значения (диапазон)
Количество кандидатов 1-8 (целое число)
Температура 0.0-1.0
Максимальное количество выходных токенов Используйте страницу моделей , чтобы определить максимальное количество токенов для используемой вами модели.
ТопП 0.0-1.0

Помимо проверки значений параметров, убедитесь, что вы используете правильную версию API (например, /v1 или /v1beta ) и модель, поддерживающую необходимые вам функции. Например, если функция находится в бета-версии, она будет доступна только в версии API /v1beta .

Проверьте, подходит ли вам данная модель.

Убедитесь, что вы используете поддерживаемую модель, указанную на нашей странице моделей .

Более высокая задержка или использование токенов при работе с моделями мышления.

Более высокая задержка или расход токенов часто возникают из-за того, что в моделях Gemini 3.x функция "мышления" включена по умолчанию. В устаревших моделях Gemini 2.5 также используется функция "мышления" по умолчанию.

Мышление, основанное на моделях, генерирует внутренние токены рассуждений для повышения качества. Этот процесс рассуждений увеличивает как время отклика, так и общее потребление токенов.

Если для вас приоритетом является снижение задержки или необходимость минимизации затрат, вы можете снизить уровень мышления или отключить его.

Подробную информацию о настройке и примеры кода см. в руководстве по планированию .

Вопросы безопасности

Если вы видите, что запрос был заблокирован из-за настроек безопасности в вашем вызове API, проверьте запрос на соответствие фильтрам, которые вы установили в вызове API.

Если вы видите BlockedReason.OTHER , это означает, что запрос или ответ могут нарушать условия предоставления услуг или быть неподдерживаемыми по другим причинам.

Вопрос о декламации

If you see the model stops generating output due to the RECITATION reason, this means the model output may resemble certain data. To fix this, try to make prompt / context as unique as possible and use a higher temperature.

Repetitive tokens issue

If you see repeated output tokens, try the following suggestions to help reduce or eliminate them.

Описание Причина Suggested workaround
Repeated hyphens in Markdown tables This can occur when the contents of the table are long as the model tries to create a visually aligned Markdown table. However, the alignment in Markdown is not necessary for correct rendering.

Add instructions in your prompt to give the model specific guidelines for generating Markdown tables. Provide examples that follow those guidelines. You can also try adjusting the temperature. For generating code or very structured output like Markdown tables, high temperature have shown to work better (>= 0.8).

The following is an example set of guidelines you can add to your prompt to prevent this issue:

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
Repeated tokens in Markdown tables Similar to the repeated hyphens, this occurs when the model tries to visually align the contents of the table. The alignment in Markdown is not required for correct rendering.
  • Try adding instructions like the following to your system prompt: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Try adjusting the temperature. Higher temperatures (>= 0.8) generally helps to eliminate repetitions or duplication in the output.
Repeated newlines ( \n ) in structured output When the model input contains unicode or escape sequences like \u or \t , it can lead to repeated newlines.
  • Check for and replace forbidden escape sequences with UTF-8 characters in your prompt. For example, \u escape sequence in your JSON examples can cause the model to use them in its output too.
  • Instruct the model on allowed escapes. Add a system instruction like this: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
Repeated text in using structured output When the model output has a different order for the fields than the defined structured schema, this can lead to repeating text.
  • Don't specify the order of fields in your prompt.
  • Make all output fields required.
Repetitive tool calling This can occur if the model loses the context of previous thoughts and/or call an unavailable endpoint that it's forced to. Instruct the model to maintain state within its thought process. Add this to the end of your system instructions: 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
Repetitive text that's not part of structured output This can occur if the model gets stuck on a request that it can't resolve.
  • If thinking is turned on, avoid giving explicit orders for how to think through a problem in the instructions. Just ask for the final output.
  • Try a higher temperature >= 0.8.
  • Add instructions like "Be concise", "Don't repeat yourself", or "Provide the answer once".

Blocked or non-working API keys

This section describes how to check whether your Gemini API key is blocked and what to do about it.

Understand why keys are blocked

We have identified a vulnerability where some API keys may have been publicly exposed. To protect your data and prevent unauthorized access, we have proactively blocked these known leaked keys from accessing the Gemini API.

Confirm if your keys are affected

If your key is known to be leaked, you can no longer use that key with the Gemini API. You can use Google AI Studio to see if any of your API keys are blocked from calling the Gemini API and generate new keys. You may also see the following error returned when attempting to use these keys:

Your API key was reported as leaked. Please use another API key.

Action for blocked API keys

You should generate new API keys for your Gemini API integrations using Google AI Studio . We strongly recommend reviewing your API key management practices to ensure that your new keys are kept secure and are not publicly exposed.

Unexpected charges due to vulnerability

Submit a billing support case . Our billing team is working on this, and we will communicate updates as soon as possible.

Google's security measures for leaked keys

How is Google going to help secure my account from cost overrun and abuse if my API keys are leaked?

  • We are moving towards issuing API keys when you request a new key using Google AI Studio that will by default be limited to only Google AI Studio and not accept keys from other services. This will help prevent any unintended cross-key usage.
  • We are defaulting to blocking API keys that are leaked and used with the Gemini API, helping prevent abuse of cost and your application data.
  • You will be able to find the status of your API keys within Google AI Studio and we will work on communicating proactively when we identify your API keys are leaked for immediate action.

Improve model output

For higher quality model outputs, explore writing more structured prompts. The prompt engineering guide page introduces some basic concepts, strategies, and best practices to get you started.

Understand token limits

Read through our Token guide to better understand how to count tokens and their limits.

Известные проблемы

  • The API supports only a number of select languages. Submitting prompts in unsupported languages can produce unexpected or even blocked responses. See available languages for updates.

Сообщить об ошибке

Join the discussion on the Google AI developer forum if you have questions.