Как использовать ключи Gemini API

Чтобы использовать Gemini API, необходимо выполнять аутентификацию запросов. Для аутентификации можно использовать стандартный или авторизационный ключ API.

Как создать или посмотреть ключ Gemini API

Типы ключей API: стандартные и ключи авторизации

Ключи API предоставляют доступ к Gemini API, но их характеристики безопасности различаются. Gemini API переходит со стандартных ключей API на ключи авторизации, чтобы повысить безопасность.

• Стандартные ключи API. Связывают запросы с проектом Google Cloud для выставления счетов и учета квот. Стандартные ключи не идентифицируют вызывающего абонента, что ограничивает детализацию разрешений и контроля доступа, которые они могут поддерживать.
• Ключи авторизации. Напрямую связаны с сервисным аккаунтом Google Cloud. При использовании ключа авторизации ваши запросы обрабатываются от имени связанного сервисного аккаунта, что позволяет детально контролировать доступ. По умолчанию ключи авторизации ограничены Generative Language API (Gemini API). Если наши системы обнаружат утечку ключа, он будет быстро заблокирован.

Чтобы обеспечить безопасность, в Gemini API вместо стандартных ключей будут использоваться ключи аутентификации.

• Ключи аутентификации по умолчанию. С 28 мая 2026 г. все новые ключи API, созданные в Google AI Studio, автоматически создаются как ключи аутентификации.
• Отклонение ключей без ограничений. Gemini API отклоняет запросы от стандартных ключей без ограничений. Стандартные ключи API, для которых заданы явные ограничения, продолжат работать. Это позволяет предотвратить несанкционированное использование ключей, которые могут быть опубликованы или связаны с другими сервисами.

Управление ключами API в Google AI Studio

Управлять проектами и ключами можно непосредственно в Google AI Studio.

Проекты Google Cloud

Каждый ключ Gemini API связан с проектом Google Cloud. Проекты Google Cloud позволяют управлять платежами, соавторами и разрешениями. Google AI Studio предоставляет простой интерфейс для доступа к этим проектам.

• Проект по умолчанию. Если вы новый пользователь, Google AI Studio автоматически создаст проект Google Cloud по умолчанию и ключ API после того, как вы примете Условия использования. Чтобы переименовать проект, перейдите в раздел Проекты на панели управления.
• Существующие проекты. Если у вас уже есть аккаунт Google Cloud, AI Studio не создает проект по умолчанию. Вместо этого вам нужно импортировать существующие проекты.

Импорт проектов

По умолчанию в Google AI Studio показываются не все ваши проекты Google Cloud. Импортируйте нужные проекты:

1. Перейдите в Google AI Studio.
2. Откройте Панель управления на панели слева и выберите Проекты.
3. Нажмите кнопку Импортировать проекты.
4. Найдите и выберите проект Google Cloud, который нужно импортировать, и нажмите Импортировать.
5. После импорта перейдите на страницу API Keys (Ключи API) на панели управления, чтобы создать ключ в этом проекте.

Устранение неполадок с разрешениями на создание ключей

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

Попросите администратора проекта или организации Google Cloud назначить вам роль, которая включает следующие разрешения (например, роль редактора проекта):

• resourcemanager.projects.get – позволяет AI Studio проверять проект.
• apikeys.keys.create: позволяет генерировать ключи.
• serviceusage.services.enable – проверяет, включен ли Generative Language API.
• iam.serviceAccounts.create – требуется для создания связанного сервисного аккаунта.
• iam.serviceAccountApiKeyBindings.create – связывает сервисный аккаунт с ключом API.

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

Неизвестные ключи на странице "Использование"

На странице использования в Google AI Studio запросы, которые не удается сопоставить с именованным ключом API в проекте, группируются в разделе (unknown keys). Сюда входят ключи, удаленные более 30 дней назад, ключи без отображаемого названия и запросы, выполненные с другими учетными данными, например OAuth.

Как создать ключи в консоли Google Cloud

В Google AI Studio показываются только ключи, которые не имеют ограничений или ограничены Gemini API. Если вы не можете использовать AI Studio или хотите управлять всеми ключами API в одном месте, следуйте инструкциям в документации Google Cloud по созданию ключа API. Чтобы создать ключ API Gemini, его нужно связать с сервисным аккаунтом.

Настройка среды

Получив ключ, настройте среду для его безопасного использования в приложениях.

Вариант 1. Использование переменных среды (рекомендуется)

Задайте переменную среды GEMINI_API_KEY или GOOGLE_API_KEY. Клиентские библиотеки Gemini API автоматически обнаруживают и используют эти переменные. Если заданы оба, приоритет имеет GOOGLE_API_KEY.

Выберите операционную систему, чтобы задать переменную:

~/.bashrc

touch ~/.bashrc && open ~/.bashrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

touch ~/.zshrc && open ~/.zshrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

Вариант 2. Укажите ключ API в коде

Вы можете явно передать ключ API при инициализации клиента. Делайте это, только если вы не можете использовать переменные среды.

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

main();

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = Client.builder().apiKey("YOUR_API_KEY").build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works in a few sentences."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey: "YOUR_API_KEY",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain how AI works in a few sentences."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works in a few words"
  }'

Безопасность и управление секретами

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

Критические правила безопасности

• Храните ключи в тайне. Никогда не добавляйте ключи API в системы контроля версий, такие как Git.
• Никогда не открывайте доступ к ключам на стороне клиента в рабочей версии. Не задавайте ключи API в коде веб- или мобильных приложений. Ключи, скомпилированные в клиентском коде, могут быть извлечены пользователями. Чтобы защитить клиентские приложения, используйте прокси-сервер для вызовов API.

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

• Переменные среды. Ключи считываются из переменных среды, а не из файлов конфигурации.
• Secret Manager. Для рабочей среды храните ключи в безопасном хранилище секретов, например Google Cloud Secret Manager.
• Оповещения о платежах. Настройте оповещения о платежах в консоли Google Cloud, чтобы получать уведомления о резком росте использования или расходов.

Контрольный список действий при утечке

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

1. Сгенерируйте новый ключ. Создайте ключ для замены в Google AI Studio или Cloud Console.
2. Обновите приложение. Разверните код с новым ключом.
3. Отключите или удалите скомпрометированный ключ. После проверки нового ключа отключите скомпрометированный ключ в Cloud Console. Чтобы избежать простоя приложения, не удаляйте старый ключ, пока новый не станет полностью активным.
4. Проверьте использование. Проверьте журналы платежей и использование API в консоли Google Cloud, чтобы выявить несанкционированные действия.

Как ограничить и защитить ключи

Ограничения для ключей API позволяют минимизировать потенциальный ущерб в случае компрометации ключа.

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

Ограничения по источнику определяют, какие IP-адреса, сайты или приложения могут использовать ваш ключ.

1. Перейдите на страницу учетных данных в консоли Google Cloud.
2. Выберите проект и нажмите на название ключа API, для которого нужно настроить ограничения.
3. В разделе Application restrictions (Ограничения для приложений) выберите IP addresses (IP-адреса) или другой тип ограничений, подходящий для вашей среды.
4. Укажите разрешенные IP-адреса или диапазоны и нажмите Сохранить.

Как защитить стандартные ключи API без ограничений

Чтобы продолжить использовать Gemini API, необходимо защитить все ключи без ограничений.

Способ А. Ограничить ключ только Gemini API (AI Studio)

Если вы используете ключ только для Gemini API, защитите его непосредственно в AI Studio:

1. На странице API Keys (Ключи API) в Google AI Studio найдите ключи с пометкой Unrestricted (Без ограничений).
2. Наведите указатель мыши на ярлык и в диалоговом окне нажмите Добавить ограничения.
3. Выберите Ограничить только Gemini API.
4. Нажмите Restrict key (Применить ограничения для ключа), чтобы подтвердить действие.

Способ Б. Ограничьте ключ для других сервисов (консоль Google Cloud)

Если ключ используется в других API Google (не рекомендуется), ограничьте его в Cloud Console. Примечание. После применения этих ограничений запросы к Gemini API с использованием этого ключа будут завершаться ошибкой.

1. Перейдите на страницу учетных данных в консоли Google Cloud.
2. Выберите проект и ключ API.
3. В разделе API restrictions (Ограничения API) в раскрывающемся списке Select API restrictions (Выбрать ограничения API) выберите API, к которым должен иметь доступ этот ключ. Не выбирайте Generative Language API.
4. Нажмите Сохранить. Чтобы продолжить использовать Gemini API, создайте в AI Studio отдельный ключ с ограничениями.

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

С 7 мая 2026 г. Gemini API блокирует ключи API без ограничений, которые не использовались в течение длительного времени. В AI Studio у таких ключей есть тег Blocked (Заблокировано). Чтобы продолжить, сгенерируйте новый ключ или используйте существующий ключ с ограничениями.

Как перейти на ключ аутентификации

Чтобы создать новый ключ API аутентификации и обновить приложения, выполните следующие действия:

1. Перейдите на страницу ключей API в AI Studio.
2. Проверьте столбец Тип ключа и найдите ключи, помеченные как Стандартный.
3. Нажмите Создать ключ API. Все новые ключи, созданные в AI Studio, автоматически создаются как ключи аутентификации.
4. Скопируйте новый ключ API аутентификации.
5. Обновите код приложения, переменные среды и конфигурации развертывания, чтобы использовать новый ключ API для аутентификации.
6. Протестируйте приложение, чтобы убедиться, что оно правильно работает с новым ключом.
7. После проверки удалите или отзовите старый ключ трафика, чтобы предотвратить его неправомерное использование.

Ограничения

В Google AI Studio действуют следующие ограничения на управление проектами и ключами:

• На странице Проекты в Google AI Studio можно создать не более 10 проектов одновременно.
• На страницах Ключи API и Проекты показывается не более 100 ключей и 50 проектов.
• Отображаются только ключи API, которые не имеют ограничений или ограничены специально для Generative Language API (Gemini API).

Для расширенного управления проектами или изменения ключей с другими ограничениями используйте страницу учетных данных консоли Google Cloud.