Como usar chaves da API Gemini

Para usar a API Gemini, é necessário autenticar suas solicitações. É possível autenticar usando uma chave de API padrão ou de autorização.

Criar ou visualizar uma chave da API Gemini

Tipos de chaves de API: padrão x autorização

As chaves de API fornecem acesso à API Gemini, mas as características de segurança delas são diferentes. A API Gemini está fazendo a transição de chaves de API padrão para chaves de autorização para melhorar a segurança:

• Chaves de API padrão: associam solicitações a um projeto do Google Cloud para fins de faturamento e cota. As chaves padrão não identificam um chamador, o que limita a granularidade das permissões e do controle de acesso que elas podem oferecer.
• Chaves de autorização (auth): vinculadas diretamente a uma conta de serviço do Google Cloud. Quando você usa uma chave de autorização, suas solicitações são processadas na identidade dessa conta de serviço vinculada, permitindo o controle de acesso granular. As chaves de autorização são restritas à API Generative Language (API Gemini) por padrão e oferecem uma aplicação rápida de chaves vazadas que interrompe rapidamente o uso de chaves vazadas detectadas pelos nossos sistemas.

Para garantir o uso seguro, a API Gemini vai migrar das chaves padrão para as chaves de autenticação:

• Chaves de autenticação padrão: todas as novas chaves de API criadas no Google AI Studio são criadas automaticamente como chaves de autenticação.
• Em 19 de junho de 2026: a API Gemini vai rejeitar solicitações de chaves padrão irrestritas. As chaves de API padrão com restrições explícitas aplicadas vão continuar funcionando. Essa restrição impede o uso não autorizado de chaves que podem ser compartilhadas publicamente ou vinculadas a outros serviços.
• Em setembro de 2026: a API Gemini vai rejeitar solicitações de chaves padrão. É necessário migrar para chaves de autenticação antes dessa data para evitar interrupções no serviço. Migre para chaves de autenticação antes de setembro de 2026.

Como gerenciar chaves de API no Google AI Studio

Você pode gerenciar seus projetos e chaves diretamente no Google AI Studio.

Projetos do Google Cloud

Cada chave de API do Gemini está associada a um projeto do Google Cloud. Os projetos do Google Cloud gerenciam o faturamento, os colaboradores e as permissões. O Google AI Studio oferece uma interface leve para acessar esses projetos.

• Projeto padrão: se você for um novo usuário, o Google AI Studio vai criar automaticamente um projeto padrão do Google Cloud e uma chave de API depois que você aceitar os Termos de Serviço. Para renomear o projeto, acesse a visualização Projetos no painel.
• Projetos atuais: se você já tiver uma conta do Google Cloud, o AI Studio não vai criar um projeto padrão. Em vez disso, importe seus projetos atuais.

Importar projetos

Por padrão, o Google AI Studio não mostra todos os seus projetos do Google Cloud. Importe os projetos que você quer usar:

1. Acesse o Google AI Studio.
2. Abra o Painel no painel à esquerda e selecione Projetos.
3. Clique no botão Importar projetos.
4. Pesquise e selecione o projeto do Google Cloud que você quer importar e clique em Importar.
5. Depois de importar, acesse a página Chaves de API no painel para criar uma chave nesse projeto.

Resolver problemas de permissões de criação de chaves

Se o botão Criar chave de API estiver indisponível e mostrar a mensagem: "Você não tem permissão para criar uma chave neste projeto", significa que você não tem as permissões necessárias do IAM.

Peça ao administrador do projeto ou da organização do Google Cloud para conceder a você um papel que contenha as seguintes permissões (como Editor de projetos):

• resourcemanager.projects.get: permite que o AI Studio verifique o projeto.
• apikeys.keys.create: permite a geração de chaves.
• serviceusage.services.enable: garante que a API Generative Language esteja ativada.
• iam.serviceAccounts.create: obrigatório para criar a conta de serviço vinculada.
• iam.serviceAccountApiKeyBindings.create: vincula a conta de serviço à chave de API.

Se não for possível conseguir acesso administrativo, crie um projeto do Google Cloud que não esteja associado a uma organização para gerar suas chaves.

Como configurar o ambiente

Depois de ter uma chave, configure seu ambiente para usá-la com segurança nos seus aplicativos.

Opção 1: usar variáveis de ambiente (recomendado)

Defina a variável de ambiente GEMINI_API_KEY ou GOOGLE_API_KEY. As bibliotecas de cliente da API Gemini detectam e usam essas variáveis automaticamente. Se ambos forem definidos, GOOGLE_API_KEY terá precedência.

Selecione seu sistema operacional para definir a variável:

~/.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

Opção 2: fornecer a chave de API explicitamente no código

Você pode transmitir a chave de API explicitamente ao inicializar o cliente. Faça isso apenas se não for possível usar variáveis de ambiente.

from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.5-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.5-flash",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

main();

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    "google.golang.org/genai/interactions"
)

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

    interaction, err := client.Interactions.NewModel(ctx, interactions.NewModelParams{
        Model: "gemini-3.5-flash",
        Input: interactions.Input{
            String: "Explain how AI works in a few words",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range interaction.Steps {
        if step.ModelOutput != nil {
            for _, content := range step.ModelOutput.Content {
                if content.Text != nil {
                    fmt.Println(content.Text.Text)
                }
            }
        }
    }
}

package com.example;

import com.google.genai.Client;
import com.google.genai.interactions.models.interactions.CreateModelInteractionParams;
import com.google.genai.interactions.models.interactions.Interaction;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    CreateModelInteractionParams params =
        CreateModelInteractionParams.builder()
            .input("Explain how AI works in a few words")
            .model("gemini-3.5-flash")
            .build();

    Interaction interaction = client.interactions.create(params);

    interaction.steps().forEach(step -> {
      if (step.isModelOutput()) {
        step.asModelOutput().content().ifPresent(contents -> {
          contents.forEach(content -> {
            content.text().ifPresent(text -> System.out.println(text.text()));
          });
        });
      }
    });
  }
}

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.5-flash",
    "input": "Explain how AI works in a few words"
  }'

Segurança e gerenciamento de secrets

Trate sua chave da API Gemini como uma senha. Se comprometida, outras pessoas podem consumir a cota do seu projeto, gerar cobranças inesperadas e acessar recursos particulares.

Regras de segurança críticas

• Mantenha as chaves confidenciais: nunca verifique as chaves de API em sistemas de controle de origem, como o Git.
• Nunca exponha chaves do lado do cliente em produção: não codifique chaves de API diretamente em apps da Web ou para dispositivos móveis. As chaves compiladas no código do lado do cliente podem ser extraídas pelos usuários. Para proteger apps do lado do cliente, execute um servidor proxy de back-end para fazer as chamadas de API reais.

Práticas recomendadas de gerenciamento de secrets

• Variáveis de ambiente: leia chaves de variáveis de ambiente em vez de arquivos de configuração.
• Secret Manager: para produção, armazene suas chaves em um armazenamento de secrets seguro, como o Secret Manager do Google Cloud.
• Alertas de faturamento: configure alertas de faturamento no console do Google Cloud para receber notificações se houver um aumento no uso ou nos custos.

Lista de verificação de resposta a vazamentos

Se você suspeitar que sua chave de API foi vazada:

1. Gere uma nova chave: crie uma chave substituta no Google AI Studio ou no console do Cloud.
2. Atualize o aplicativo: implante o código usando a nova chave.
3. Desative ou exclua a chave comprometida: desative a chave vazada no Console do Cloud assim que a nova chave for verificada. Não exclua a chave antiga até que a nova esteja totalmente ativa para evitar tempo de inatividade do aplicativo.
4. Auditoria de uso: verifique os registros de faturamento e o uso da API no console do Google Cloud para identificar atividades não autorizadas.

Restringir e proteger suas chaves

Adicionar restrições às chaves de API minimiza o dano potencial se uma chave for comprometida.

Aplicar restrições de origem da solicitação

As restrições de origem limitam quais endereços IP, sites ou aplicativos podem usar sua chave.

1. Acesse a página "Credenciais" do console do Google Cloud.
2. Selecione seu projeto e clique no nome da chave de API que você quer restringir.
3. Em Restrições de aplicativo, selecione Endereços IP ou o tipo de restrição adequado para seu ambiente.
4. Especifique os endereços ou intervalos de IP permitidos e clique em Salvar.

Como proteger chaves de API padrão irrestritas

Para continuar usando a API Gemini após 19 de junho de 2026, proteja todas as chaves irrestritas.

Método A: restringir a chave apenas à API Gemini (AI Studio)

Se você usar a chave apenas para a API Gemini, proteja-a diretamente no AI Studio:

1. Na página Chaves de API do Google AI Studio, localize as chaves marcadas com o rótulo Sem restrições.
2. Passe o cursor sobre o marcador e clique em Adicionar restrições na caixa de diálogo.
3. Selecione Restringir apenas à API Gemini.
4. Clique em Restringir chave para confirmar.

Método B: restringir a chave para outros serviços (console do Google Cloud)

Se a chave for compartilhada com outras APIs do Google (não recomendado), restrinja-a no console do Cloud. Observação: as solicitações da API Gemini que usam essa chave vão falhar depois que essas restrições forem aplicadas.

1. Acesse a página "Credenciais" do console do Google Cloud.
2. Selecione o projeto e a chave de API.
3. Em Restrições da API, selecione Restringir chave.
4. No menu suspenso, selecione as APIs que você quer que essa chave acesse. Não selecione a API Generative Language.
5. Clique em Salvar. Crie uma chave separada e restrita no AI Studio para continuar usando a API Gemini.

Chaves inativas bloqueadas

A partir de 7 de maio de 2026, a API Gemini vai bloquear chaves de API irrestritas que ficaram inativas por um longo período. Essas chaves mostram uma tag Bloqueado no AI Studio. Você precisa gerar uma nova chave ou usar uma chave restrita para continuar.

Migrar para uma chave de autenticação

Siga estas etapas para criar uma chave de API de autenticação e atualizar seus aplicativos:

1. Acesse a página de chaves de API do AI Studio.
2. Verifique a coluna Tipo de chave para identificar as chaves listadas como Padrão.
3. Clique em Criar chave de API para gerar uma nova chave. Todas as novas chaves criadas no AI Studio são criadas automaticamente como chaves de autenticação.
4. Copie a nova chave de API de autenticação.
5. Atualize o código do aplicativo, as variáveis de ambiente e as configurações de implantação para usar a nova chave de API de autenticação.
6. Teste o aplicativo para confirmar se ele funciona corretamente com a nova chave.
7. Depois da verificação, exclua ou revogue a chave de tráfego antiga para evitar uso indevido.

Limitações

O Google AI Studio impõe as seguintes limitações de gerenciamento de projetos e chaves:

• É possível criar no máximo 10 projetos por vez na página Projetos do Google AI Studio.
• As páginas Chaves de API e Projetos mostram um máximo de 100 chaves e 50 projetos.
• Somente as chaves de API irrestritas ou restritas especificamente à API Generative Language (API Gemini) são mostradas.

Para gerenciamento avançado de projetos ou para modificar chaves com outras restrições, use a página de credenciais do console do Google Cloud.