Como usar chaves da API Gemini

Para usar a API Gemini, autentique suas solicitações. Você pode fazer a autenticação usando uma chave de API padrão ou de autorização.

Criar ou visualizar uma chave da API Gemini

Tipos de chave 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 autor da chamada, o que limita a granularidade das permissões e o 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, as 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 fornecem uma aplicação de chave vazada de ação rápida que interrompe rapidamente o uso de chaves vazadas detectadas pelos nossos sistemas.

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

• Chaves de autorização padrão: todas as novas chaves de API criadas no Google AI Studio são criadas automaticamente como chaves de autorizaçã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 que têm 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. Você deve migrar para uma chave de autorização antes dessa data para evitar interrupções no serviço. Faça a migração para chaves de autorização antes de setembro de 2026.

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 da API 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 do Google Cloud e uma chave de API padrão depois que você aceitar os Termos de Serviço. Você pode renomear esse projeto navegando até 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. Você precisa importar os projetos que quer usar:

1. Acesse o Google AI Studio.
2. Abra o painel no painel esquerdo 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 importado, navegue até 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 não estiver disponível e mostrar a mensagem: "Você não tem permissão para criar uma chave neste projeto", é porque 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: necessária para criar a conta de serviço vinculada.
• iam.serviceAccountApiKeyBindings.create: vincula a conta de serviço à chave de API.

Se você não conseguir acesso administrativo, crie um novo 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 aplicativos.

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 as duas estiverem definidas, 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

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")

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how AI works in a few words"
)
print(response.text)

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

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

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

package main

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

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)
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

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

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3.5-flash",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent"       -H 'Content-Type: application/json'       -H "x-goog-api-key: YOUR_API_KEY"       -X POST       -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Segurança e gerenciamento de secrets

Trate sua chave da API Gemini como uma senha. Se ela for comprometida, outras pessoas poderão 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 faça check-in de chaves de API em sistemas de controle de origem como o Git.
• Nunca exponha chaves no 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 as 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 o uso ou os custos aumentarem.

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 de substituição no Google AI Studio ou no console do Cloud.
2. Atualize seu aplicativo: implante o código usando a nova chave.
3. Desative ou exclua a chave comprometida: desative a chave vazada no console do Cloud depois que a nova chave for verificada. Não exclua a chave antiga até que a nova esteja totalmente ativa para evitar 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 os possíveis danos 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 apropriado para seu ambiente).
4. Especifique os endereços IP ou intervalos 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, você precisa proteger todas as chaves irrestritas.

Restringir a chave apenas à API Gemini pelo 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 Irrestrita.
2. Passe o cursor sobre o rótulo e clique em Adicionar restrições na caixa de diálogo.
3. Selecione Restringir apenas à API Gemini.
4. Clique em Restringir chave para confirmar.

Restringir a chave para outros serviços pelo 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 restrita separada 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 estiverem inativas por um período prolongado. Essas chaves mostram uma tag Bloqueada no AI Studio. Você precisa gerar uma nova chave ou usar uma chave restrita atual para continuar.

Migrar para uma chave de autorização

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

1. Acesse a página "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 autorização.
4. Copie a nova chave de API de autorização.
5. Atualize o código do aplicativo, as variáveis de ambiente e todas as configurações de implantação para usar a nova chave de API de autorização.
6. Teste o aplicativo para confirmar se ele funciona corretamente com a nova chave.
7. Depois de verificada, exclua ou revogue a chave de tráfego antiga para evitar o 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 no máximo 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.