Como usar chaves da API Gemini

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

Chaves de API

Uma chave de API é uma string criptografada que pode ser usada ao chamar as APIs do Google Cloud. Você pode criar e gerenciar todas as suas chaves de API Gemini na página Chaves de API do Google AI Studio.

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 sua 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 tiver nenhum projeto criado, crie um ou importe um do Google Cloud para o Google AI Studio. A página Projetos no Google AI Studio mostra todas as chaves com permissão suficiente para usar a API Gemini. Consulte a seção Importar projetos para instruções.

Importar projetos

Cada chave de API do 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. Para importar os projetos desejados, pesquise o nome ou 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, 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 à esquerda.
3. Selecione Projetos.
4. Selecione o botão Importar projetos na página Projetos.
5. Procure e selecione o projeto do Google Cloud que você quer importar e clique no 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

Confira abaixo 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 um máximo de 100 chaves e 100 projetos.
• Somente as chaves de API sem restrições ou restritas à API Generative Language são mostradas.

Para mais acesso de gerenciamento aos seus projetos, acesse o Console do Google Cloud.

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 forem 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.

Veja 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-2.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-2.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-2.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-2.5-flash",
            "Explain how AI works in a few words",
            null);

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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 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

• Nunca confirme chaves de API no controle de origem. Não verifique sua chave de API em sistemas de controle de versões como o Git.

• Nunca exponha chaves de API no lado do cliente. Não use sua 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.

Práticas recomendadas

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

• Use tokens efêmeros para acesso do lado do cliente (somente API Live): para acesso direto do lado do cliente à API Live, use tokens efêmeros. Elas têm menos riscos de segurança e podem ser adequadas para uso em produção. Consulte o guia sobre 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 vazar.

Para conferir algumas práticas recomendadas gerais, consulte este artigo de suporte.