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

Você pode 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, você pode codificar uma chave de API, mas isso só deve ser temporário, já que não é seguro. Confira 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 e uma chave de API padrão do Google Cloud para facilitar o uso. Você pode renomear esse projeto no Google AI Studio navegando até 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 de API Gemini está associada a um projeto do Google Cloud. Por padrão, o Google AI Studio não mostra todos os seus projetos do Cloud. Você precisa 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 lateral.
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.
• Você pode 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 ter mais acesso de gerenciamento aos seus projetos, incluindo a modificação e a restrição de chaves de API, acesse a página de credenciais do Console do Google Cloud. No Console do Cloud, selecione seu projeto, clique em uma chave de API e restrinja-a à 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 você queira fornecer uma chave de API explicitamente. Por 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 usando a API Interactions:

# This will only work for SDK newer than 2.0.0
from google import genai

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

interaction = client.interactions.create(
    model="gemini-3-flash-preview", 
    input="Explain how AI works in a few words"
)
print(interaction.steps[-1].content[0].text)

// This will only work for SDK newer than 2.0.0
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-flash-preview",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

main();

# Specifies the API revision to avoid breaking changes when they become default
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -X POST \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain how AI works in a few words"
  }'

Mantenha sua chave de API segura

Trate sua chave da API Gemini como uma senha. Se ela for 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 as alterne 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 efêmeros para acesso do lado do cliente (somente API Live) : para acesso direto do lado do cliente à API Live, você pode usar tokens efêmeros. Eles têm riscos de segurança menores e podem ser adequados para uso em produção. Consulte o guia de tokens efêmeros 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.

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.

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ê uma função com as permissões listadas acima (como Editor de Projetos ou uma função personalizada).

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