Como usar chaves da API Gemini

Para usar a API Gemini, você precisa de uma chave de API. Esta página descreve como criar e gerenciar suas chaves no Google AI Studio, além de como configurar seu ambiente para usá-las no código.

Criar ou visualizar uma chave da API Gemini

Chaves de API

É possível criar e gerenciar todas as chaves da API Gemini na página Google AI Studio Chaves de API.

Depois de ter uma chave de API, você tem as seguintes opções para se conectar à API Gemini:

• Definir a chave de API como uma variável de ambiente
• Fornecer a chave de API explicitamente

Para testes iniciais, é possível codificar uma chave de API, mas isso só deve ser temporário, já que não é seguro. Você pode encontrar exemplos de codificação da chave de API na seção Fornecer a chave de API explicitamente.

Projetos do Google Cloud

Os projetos do Google Cloud são fundamentais para usar os serviços do Google Cloud (como a API Gemini), gerenciar o faturamento e controlar colaboradores e permissões. O Google AI Studio oferece uma interface leve para seus projetos do Google Cloud.

Se você ainda não criou nenhum projeto, crie um novo ou importe um do Google Cloud para o Google AI Studio. A página Projetos no Google AI Studio mostra todas as chaves que têm permissão suficiente para usar a API Gemini. Consulte a seção Importar projetos para instruções.

Projeto padrão

Para novos usuários, depois de aceitar os Termos de Serviço, o Google AI Studio cria um projeto do Google Cloud e uma chave de API padrão para facilitar o uso. É possível renomear esse projeto no Google AI Studio acessando a visualização Projetos no Painel, clicando no botão de configurações de três pontos ao lado de um projeto e escolhendo Renomear projeto. Os usuários atuais ou aqueles que já têm contas do Google Cloud não terão um projeto padrão criado.

Importar projetos

Cada chave da API Gemini está associada a um projeto do Google Cloud. Por padrão, o Google AI Studio não mostra todos os projetos do Cloud. É necessário importar os projetos desejados pesquisando o nome ou o ID do projeto na caixa de diálogo Importar projetos. Para conferir uma lista completa dos projetos a que você tem acesso, acesse o Console do Cloud.

Se você ainda não importou nenhum projeto na nuvem, siga estas etapas para importar um projeto do Google Cloud e criar uma chave:

1. Acesse o Google AI Studio.
2. Abra o Painel no painel esquerdo.
3. Selecione Projetos.
4. Selecione o botão Importar projetos na página Projetos.
5. Pesquise e selecione o projeto do Google Cloud que você quer importar e selecione o botão Importar.

Depois que um projeto for importado, acesse a página Chaves de API no menu Painel e crie uma chave de API no projeto que você acabou de importar.

Limitações

A seguir, confira as limitações do gerenciamento de chaves de API e projetos do Google Cloud no Google AI Studio.

• É possível criar no máximo 10 projetos por vez na página Projetos do Google AI Studio.
• É possível nomear e renomear projetos e chaves.
• As páginas Chaves de API e Projetos mostram no máximo 100 chaves e 50 projetos.
• Somente as chaves de API que não têm restrições ou que estão restritas à API Generative Language são mostradas.

Para mais acesso de gerenciamento aos seus projetos, incluindo a modificação e restrição de chaves de API, acesse a página de credenciais do Console do Google Cloud. No Console do Cloud, é possível selecionar seu projeto, clicar em uma chave de API e restringi-la à API Generative Language.

Definir a chave de API como uma variável de ambiente

Se você definir a variável de ambiente GEMINI_API_KEY ou GOOGLE_API_KEY, a chave de API será escolhida automaticamente pelo cliente ao usar uma das bibliotecas da API Gemini. Recomendamos que você defina apenas uma dessas variáveis, mas, se ambas estiverem definidas, GOOGLE_API_KEY terá precedência.

Se você estiver usando a API REST ou JavaScript no navegador, será necessário fornecer a chave de API explicitamente.

Confira como definir sua chave de API localmente como a variável de ambiente GEMINI_API_KEY com diferentes sistemas operacionais.

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

Em alguns casos, talvez seja necessário fornecer uma chave de API explicitamente. Exemplo:

• Você está fazendo uma chamada de API simples e prefere codificar a chave de API.
• Você quer controle explícito sem precisar depender da descoberta automática de variáveis de ambiente pelas bibliotecas da API Gemini.
• Você está usando um ambiente em que as variáveis de ambiente não são compatíveis (por exemplo, a Web) ou está fazendo chamadas REST.

Confira abaixo exemplos de como fornecer uma chave de API explicitamente:

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"
          }
        ]
      }
    ]
  }'

Mantenha sua chave de API segura

Trate sua chave da API Gemini como uma senha. Se comprometida, outras pessoas poderão usar a cota do seu projeto, gerar cobranças (se o faturamento estiver ativado) e acessar seus dados particulares, como arquivos.

Regras de segurança críticas

• Mantenha as chaves confidenciais: as chaves de API do Gemini podem acessar dados sensíveis de que seu aplicativo depende.

  • Nunca confirme chaves de API no controle de origem. Não faça check-in da chave de API em sistemas de controle de versão, como o Git.

  • Nunca exponha chaves de API no lado do cliente. Não use a chave de API diretamente em apps da Web ou para dispositivos móveis em produção. As chaves no código do lado do cliente (incluindo nossas bibliotecas JavaScript/TypeScript e chamadas REST) podem ser extraídas.

• Restringir o acesso: restrinja o uso da chave de API a endereços IP, referenciadores HTTP ou apps Android/iOS específicos, quando possível.

• Restringir o uso: ative apenas as APIs necessárias para cada chave.

• Realizar auditorias regulares: audite suas chaves de API regularmente e faça a rotação delas periodicamente.

Práticas recomendadas

• Usar chamadas do lado do servidor com chaves de API : a maneira mais segura de usar a chave de API é chamar a API Gemini de um aplicativo do lado do servidor em que a chave pode ser mantida confidencial.

• Usar tokens temporários para acesso do lado do cliente (somente API Live) : para acesso direto do lado do cliente à API Live, é possível usar tokens temporários. Eles têm riscos de segurança menores e podem ser adequados para uso em produção. Consulte o guia de tokens temporários para mais informações.

• Considere adicionar restrições à sua chave: é possível limitar as permissões de uma chave adicionando restrições de chave de API. Isso minimiza os possíveis danos se a chave for vazada.

Para algumas práticas recomendadas gerais, consulte também este artigo de suporte.

Proteger chaves de API irrestritas

As chaves de API irrestritas são vulneráveis a agentes mal-intencionados e uso não autorizado. A partir de 19 de junho de 2026, para melhorar a segurança, a API Gemini vai descontinuar o suporte a chaves de tráfego irrestritas.

Isso significa que as solicitações da API Gemini vão falhar se você não tomar medidas.

Para continuar usando a API Gemini sem interrupção, proteja suas chaves de tráfego adicionando restrições em AI Studio.

Em aistudio.google.com/api-keys, você verá um banner para notificar quando as chaves de API forem irrestritas. É possível conferir quais chaves são irrestritas e o uso do serviço nos últimos 90 dias.

Para chaves irrestritas, é necessário escolher uma das seguintes opções:

• Usar a chave somente para a API Gemini.
• Usar a chave para uso da API não Gemini.

Restringir a chave somente à API Gemini

Se você quiser restringir a chave somente à API Gemini, proteja-a no AI Studio clicando no botão Restringir à API Gemini.

Restringir a chave para uso da API não Gemini

Se você quiser restringir a chave para uso da API não Gemini:

1. Acesse a página de credenciais do Console do Google Cloud.
2. Verifique se o projeto foi selecionado corretamente.
3. Selecione uma chave de API.
4. Expanda o menu suspenso Restrições de API e aplique restrições de serviço à chave de API.

Se você quiser modificar chaves com restrições atuais ou recém-adicionadas, acesse o Console do Google Cloud.

Chaves 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. Esses usuários vão encontrar uma tag Bloqueado para a chave em aistudio.google.com/api-keys e precisarão gerar uma nova chave ou usar uma chave restrita alternativa para continuar usando a API Gemini.

Solução de problemas na criação de chaves de API

No Google AI Studio, o botão Criar chave de API pode aparecer indisponível, com a mensagem: "Você não tem permissão para criar uma chave neste projeto".

Isso ocorre quando você não tem as permissões necessárias no projeto para gerar uma nova chave:

• resourcemanager.projects.get: permite que o AI Studio verifique a existência do projeto.
• apikeys.keys.create: permite a geração da chave de API.
• serviceusage.services.enable: necessário para garantir que a API Gemini esteja ativa no projeto.
• iam.serviceAccounts.create: cada nova chave de API agora exige uma conta de serviço vinculada gerada na criação da chave de API, .
• iam.serviceAccountApiKeyBindings.create: necessário para vincular a conta de serviço recém-criada à chave de API.

Para corrigir suas permissões, peça ao administrador do projeto ou da organização (se o projeto pertencer a uma organização) para conceder a você um papel com as permissões listadas acima (como editor de projetos ou um papel personalizado).

Se você não tiver acesso administrativo a um projeto, crie um novo projeto que não esteja associado a uma organização para gerar suas chaves.

Para uma lista completa das permissões do IAM necessárias para todos os recursos do Google AI Studio (como visualizar o uso, os limites de taxa ou o faturamento), consulte o guia de solução de problemas do AI Studio.