Byesu API

Русский

简体中文
English
日本語
Français
Tiếng Việt

Русский

简体中文
English
日本語
Français
Tiếng Việt

Оформление

Gemini API 400 INVALID_ARGUMENT, FAILED_PRECONDITION и «API key not valid» ​

Вызов Gemini возвращает HTTP 400 до того, как что-либо будет сгенерировано. В теле ответа указан тип ошибки: неверный ключ (Gemini сообщает об этом как 400, а не 401), невыполненное предварительное условие или неприемлемый для API запрос. Ниже приведены способы устранения каждой из них, а также различия в совместимости с OpenAI, которые вызывают ошибки 400.

Краткий ответ

Прочитайте error.status и error.message. API key not valid. Please pass a valid API key. (причина API_KEY_INVALID) означает, что ключ неверен, содержит лишние пробелы или устаревший GOOGLE_API_KEY переопределяет GEMINI_API_KEY. FAILED_PRECONDITION означает отсутствие предварительного условия, обычно это отсутствие биллинга в регионе, где нет бесплатного уровня. Любая другая ошибка INVALID_ARGUMENT — это проблема со структурой запроса: опечатка, использование функции v1beta в эндпоинте /v1 или параметр, который новые модели отклоняют. Ошибка 400 не исчезнет при повторном запросе, поэтому сначала исправьте сам запрос.

Симптомы и значение ошибки ​

Пример ошибки с неверным ключом, в точности соответствующий справочнику ошибок generateContent от Google:

json
{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": { "service": "generativelanguage.googleapis.com" }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}

В этом же справочнике перечислены две другие ошибки 400:

СтатусЗадокументированное сообщение / причинаЧто делать
INVALID_ARGUMENT"The request body is malformed": опечатка, пропущено обязательное поле или используется функция новой версии в старом эндпоинтеСверьте тело запроса со справочником API; в message обычно указано конкретное поле
FAILED_PRECONDITION"Gemini API free tier is not available in your country. Please enable billing on your project in Google AI Studio."Привяжите аккаунт Cloud Billing к проекту

В более новом Interactions API те же проблемы отображаются как значения code: invalid_request (некорректная полезная нагрузка), parameter_unknown (удалите нераспознанный параметр) и failed_precondition (например, биллинг отключен). Все три возвращают HTTP 400.

Смежные ошибки, требующие иного исправления:

  • 403 PERMISSION_DENIED: ключ заблокирован или скомпрометирован (Your API key was reported as leaked. Please use another API key.), либо проект требует верификации, ограничен или имеет проблемы с биллингом. См. руководство по устранению неполадок Google.
  • 429 RESOURCE_EXHAUSTED: запрос составлен верно, но проект превысил квоту. См. Gemini API 429 RESOURCE_EXHAUSTED.

Почему это происходит ​

  1. Проверка ключа выполняется прежде всего остального, и неверный ключ возвращает INVALID_ARGUMENT. Поэтому клиенты, которые обрабатывают 401 только как ошибку авторизации, пропустят ее.
  2. Приоритет переменных окружения. Согласно руководству по API-ключам Google, клиентские библиотеки считывают GEMINI_API_KEY или GOOGLE_API_KEY, и если установлены оба, GOOGLE_API_KEY имеет приоритет. Старый GOOGLE_API_KEY, оставшийся от другого проекта Google, незаметно заменит ключ, который вы только что установили.
  3. Типы ключей меняются. Новые ключи AI Studio, созданные после 28 мая 2026 года, являются ключами авторизации, и Gemini API отклоняет неограниченные (unrestricted) стандартные ключи; ограниченные стандартные ключи продолжают работать.
  4. Новые модели отклоняют параметры, которые принимали старые. Начиная с Gemini 3.6 Flash, изменения API от Google применяются ко всем последующим моделям, что делает требования к валидности запроса более строгими.

Исправление 1: Проверка ключа в изоляции ​

bash
# 1. Какие ключи увидит SDK? GOOGLE_API_KEY побеждает, если установлены оба.
env | grep -E 'GOOGLE_API_KEY|GEMINI_API_KEY'

# 2. Проверьте на наличие невидимых символов: последние байты не должны содержать \n или пробелы
printf '%s' "$GEMINI_API_KEY" | tail -c 3 | od -c

# 3. Быстрая проверка ключа: список моделей
curl -sS "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY" | head -20

Если шаг 3 возвращает API_KEY_INVALID, проблема именно в ключе: создайте новый на странице API-ключей AI Studio и замените его везде. Если шаг 3 прошел успешно, но генерация все равно не работает, продолжайте. Google отмечает, что models.list "лишь проверяет наличие ключа" и не проверяет доступ к уровню (tier) или биллинг, поэтому протестируйте реальный запрос:

bash
curl -sS "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "Reply with: ok"}]}]}'

Другие ошибки с ключами, которые стоит исключить:

  • Ключ от другого сервиса. Токен шлюза или ключ OpenAI, отправленный в generativelanguage.googleapis.com, "не является действительным". То же самое в обратную сторону: ключ Google не будет работать на шлюзе.
  • Старый стандартный ключ внезапно перестал работать. В консоли Cloud проверьте, что он ограничен (например, только для API Generative Language); неограниченные стандартные ключи отклоняются.

Исправление 2: Исправление структуры запроса ​

Для общей ошибки INVALID_ARGUMENT в message обычно указывается проблемное поле. Распространенные причины:

  • Опечатки и неправильная вложенность. contents → parts → text — это минимальная структура. Настройки генерации должны находиться в generationConfig, а не на верхнем уровне.
  • Несоответствие версии API. Google заявляет, что бета-функции "будут доступны только в версии API /v1beta", и что использование функций новой версии в старом эндпоинте вызывает ошибки. Если поле задокументировано, но отклоняется, проверьте, указано ли в URL /v1/ там, где должно быть /v1beta/.
  • Длина вывода. maxOutputTokens должен быть в пределах лимита модели. Проверьте страницу моделей для определения максимума каждой модели.
  • Структурированный вывод. Google документирует, что схемы ответов, "слишком сложные для принудительного выполнения (например, большой maxItems во вложенных массивах), возвращают ошибку 400 INVALID_ARGUMENT". Упростите (сделайте плоской) схему или проверьте ограничения в коде.

Исправление 3: Обновление параметров для Gemini 3.6+ и Gemini 4 ​

Если вы обновили ID модели, но оставили старый запрос, эти правила являются наиболее частой причиной ошибок:

ПараметрПравило для текущих моделейДействие
Предзаполненный ход model (последний непустой ход — model)Возвращает 400, начиная с Gemini 3.6 FlashЗавершайте запрос ходом user
candidateCountНе поддерживается в Gemini 3 и 4Удалите его; отправляйте отдельные запросы для получения нескольких вариантов
temperature, topP, topKУстарели и игнорируются в Gemini 3.6+ и 4; Google заявляет, что в будущих поколениях моделей они будут возвращать 400Удалите их сейчас
Сигнатуры мышления (Thought signatures)В Gemini 3 и 4 вы должны передавать их обратно во время вызова функций, иначе получите ошибку валидации 4xxДобавляйте полный ответ модели, включая сигнатуры, в историю; официальные SDK делают это автоматически

Самописные циклы агентов, которые восстанавливают историю только по имени функции и аргументам, теряют сигнатуру. В руководстве Google по сигнатурам мышления есть точные форматы пошагового взаимодействия, включая вариант, совместимый с OpenAI.

Исправление 4: Решение ошибки FAILED_PRECONDITION ​

Задокументированный случай — недоступность бесплатного уровня (free tier) в вашем регионе. Решение: настройте биллинг и привяжите аккаунт Cloud Billing к проекту. Создание новых ключей или повторная отправка запросов не помогут, так как Google определяет право на бесплатный уровень для каждого проекта отдельно. Некоторые модели требуют биллинг в любом случае: Google заявляет, что Gemini 4 Argon "недоступна на бесплатном уровне".

Исправление 5: Различия в слое совместимости с OpenAI ​

Эндпоинт Google с совместимостью с OpenAI позволяет SDK OpenAI вызывать Gemini, но это не полная копия API OpenAI. Google помечает его как бета-версию. Эти различия вызывают большинство ошибок 400 в этом режиме:

python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",  # ключ Gemini, отправляемый как Authorization: Bearer
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

resp = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "Explain how AI works"}],
    # Либо reasoning_effort ...
    reasoning_effort="low",
    # ... ИЛИ собственный thinking_config Gemini, но никогда не оба сразу:
    # extra_body={"extra_body": {"google": {"thinking_config": {"thinking_level": "high"}}}},
)
  • reasoning_effort и thinking_config нельзя комбинировать. Google: они "дублируют функциональность, поэтому их нельзя использовать одновременно".
  • Reasoning effort отображается (мапится), а не передается напрямую. Для Gemini 4, minimal мапится в low, а xhigh указан только для gemini-4-hydrogen. Рассуждения (reasoning) нельзя отключить для моделей Gemini 3 или Gemini 4; "none" работает только с моделями 2.5.
  • Функции, присущие только Gemini, помещаются в extra_body. В Python SDK примеры Google вкладывают это дважды: extra_body={"extra_body": {"google": {...}}}, с cached_content или thinking_config внутри. Python SDK OpenAI отклоняет ключевые аргументы, которые он не распознает, поэтому поля Gemini должны передаваться именно так.
  • Генерация изображений отбрасывает неизвестные параметры. В эндпоинте изображений параметры, выходящие за рамки задокументированного набора, "тихо игнорируются", поэтому отсутствие эффекта там не вызовет 400.
  • Логируйте сырое тело ответа, а не только класс исключения SDK: в message указано поле, из-за которого произошла ошибка.

Информацию об ошибках с ID моделей в любом эндпоинте, совместимом с OpenAI, см. в разделе Model not found 404. То же правило "скопируйте ID из списка моделей" применимо и к Gemini.

Если вы используете byesu ​

byesu — это AI API-шлюз с OpenAI-совместимым эндпоинтом: один ключ для Gemini, Claude, GPT и Grok, с оплатой по факту использования без подписки. Два примечания:

  • Gemini через https://byesu.com/v1. Используйте OpenAI SDK с вашим токеном sk- и ID моделей gemini-4-argon или gemini-3.8-flash. Ваш ключ Google там не используется, поэтому ошибки API_KEY_INVALID и FAILED_PRECONDITION (связанные с бесплатным уровнем) не применимы. Правила на уровне модели, например запрет на предзаполненный финальный ход ассистента, по-прежнему действуют.
  • Ошибки возвращаются в формате OpenAI. Отклоненный запрос возвращает тело в стиле OpenAI {"error": {"message": ..., "type": ..., "code": ...}} вместо status и details от Google, поэтому читайте error.message для поиска поля, вызвавшего сбой.

Для начала создайте токен в консоли и следуйте руководству Quick Start.

FAQ ​

Почему Gemini возвращает API key not valid. Please pass a valid API key? ​

Ключ в вашем запросе не принимается Gemini API. Возвращается HTTP 400 со статусом INVALID_ARGUMENT и причиной API_KEY_INVALID. Распространенные причины: опечатка или лишний пробел, устаревший GOOGLE_API_KEY, который переопределяет GEMINI_API_KEY (при наличии обоих GOOGLE_API_KEY имеет приоритет), или использование ключа от другого сервиса.

Что означает 400 FAILED_PRECONDITION в Gemini API? ​

Не выполнено предварительное условие для запроса. Задокументированный случай — "Gemini API free tier is not available in your country. Please enable billing on your project in Google AI Studio." Привязка аккаунта Cloud Billing к проекту в AI Studio решает проблему; повторная отправка запроса не поможет.

Что вызывает общую ошибку Gemini 400 INVALID_ARGUMENT? ​

Некорректное тело запроса: опечатка, отсутствие обязательного поля, использование функции, не поддерживаемой в текущей версии API (v1 вместо v1beta), или использование параметра, который модель больше не принимает. В Gemini 3.6 и более новых версиях предзаполненный ход модели возвращает 400, параметр candidate_count не поддерживается, а temperature, top_p и top_k устарели. Сообщение об ошибке обычно указывает на проблемное поле.

Можно ли использовать reasoning_effort и thinking_config вместе в режиме совместимости с OpenAI для Gemini? ​

Нет. Google указывает, что reasoning_effort и thinking_level или thinking_budget дублируют друг друга, поэтому их нельзя использовать одновременно. Отправляйте либо reasoning_effort, либо thinking_config внутри extra_body, но не оба сразу. Рассуждения (reasoning) нельзя отключить для моделей Gemini 3 или Gemini 4.

Означает ли код 200 от models.list, что мой ключ Gemini работает? ​

Лишь отчасти. Google отмечает, что models.list проверяет только существование ключа, но не проверяет статус уровня доступа (tier) или биллинг, поэтому generateContent все равно может выдать ошибку. Это все еще полезный первичный тест: если сам models.list возвращает API_KEY_INVALID, значит проблема в ключе.

Возникла проблема? Напишите в поддержку или в наш чат.

© Byesu API · 半页酥