Gemini API reference

Esta referência de API descreve as APIs padrão, de streaming e em tempo real que você pode usar para interagir com os modelos do Gemini. É possível usar as APIs REST em qualquer ambiente que ofereça suporte a solicitações HTTP. Consulte o Guia de início rápido para saber como começar com sua primeira chamada de API. Se você estiver procurando referências para nossas bibliotecas e SDKs específicos de linguagem, acesse o link da linguagem na navegação à esquerda em Referências de SDK.

Endpoints principais

A API Gemini é organizada em torno dos seguintes endpoints principais:

  • Geração de conteúdo padrão (generateContent): um endpoint REST padrão que processa sua solicitação e retorna a resposta completa do modelo em um único pacote. Isso é ideal para tarefas não interativas em que você pode esperar o resultado completo.
  • Geração de conteúdo por streaming (streamGenerateContent): usa eventos enviados pelo servidor (SSE) para enviar partes da resposta conforme elas são geradas. Isso oferece uma experiência mais rápida e interativa para aplicativos como chatbots.
  • API Live (BidiGenerateContent): uma API com estado baseada em WebSocket para streaming bidirecional, projetada para casos de uso de conversas em tempo real.
  • Modo em lote (batchGenerateContent): um endpoint REST padrão para enviar lotes de solicitações generateContent.
  • Embeddings (embedContent): um endpoint REST padrão que gera um vetor de embedding de texto da entrada Content.
  • APIs Gen Media:endpoints para gerar mídia com nossos modelos especializados, como Imagen para geração de imagens e Veo para geração de vídeos. O Gemini também tem esses recursos integrados, que podem ser acessados usando a API generateContent.
  • APIs de plataforma:endpoints de utilidade que oferecem suporte a recursos principais, como fazer upload de arquivos e contar tokens.

Autenticação

Todas as solicitações para a API Gemini precisam incluir um cabeçalho x-goog-api-key com sua chave de API. Crie uma com alguns cliques no Google AI Studio.

Confira abaixo um exemplo de solicitação com a chave de API incluída no cabeçalho:

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

Para instruções sobre como transmitir sua chave para a API usando os SDKs do Gemini, consulte o guia Como usar chaves de API do Gemini.

Geração de conteúdo

É o endpoint central para enviar comandos ao modelo. Há dois endpoints para gerar conteúdo. A principal diferença é como você recebe a resposta:

  • generateContent (REST): recebe uma solicitação e fornece uma única resposta depois que o modelo conclui toda a geração.
  • streamGenerateContent (SSE): recebe exatamente a mesma solicitação, mas o modelo transmite partes da resposta à medida que elas são geradas. Isso proporciona uma melhor experiência do usuário para aplicativos interativos, já que permite mostrar resultados parciais imediatamente.

Estrutura do corpo da solicitação

O corpo da solicitação é um objeto JSON idêntico para os modos padrão e de streaming e é criado com alguns objetos principais:

  • Objeto Content: representa uma única rodada em uma conversa.
  • Objeto Part: um dado em uma ação Content (como texto ou imagem).
  • inline_data (Blob): um contêiner para bytes de mídia brutos e o tipo MIME deles.

No nível mais alto, o corpo da solicitação contém um objeto contents, que é uma lista de objetos Content, cada um representando turnos na conversa. Na maioria dos casos, para a geração de texto básica, você terá um único objeto Content, mas se quiser manter o histórico de conversas, use vários objetos Content.

Confira a seguir um corpo de solicitação generateContent típico:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Estrutura do corpo da resposta

O corpo da resposta é semelhante para os modos de streaming e padrão, exceto pelo seguinte:

Em um nível geral, o corpo da resposta contém um objeto candidates, que é uma lista de objetos Candidate. O objeto Candidate contém um objeto Content que tem a resposta gerada retornada do modelo.

Exemplos de solicitações

Os exemplos a seguir mostram como esses componentes se unem para diferentes tipos de solicitações.

Comando somente de texto

Um comando de texto simples consiste em uma matriz contents com um único objeto Content. A matriz parts desse objeto, por sua vez, contém um único objeto Part com um campo text.

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

Comando multimodal (texto e imagem)

Para fornecer texto e uma imagem em um comando, a matriz parts precisa conter dois objetos Part: um para o texto e outro para a imagem inline_data.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Conversas com vários turnos (chat)

Para criar uma conversa com várias trocas de mensagens, defina a matriz contents com vários objetos Content. A API vai usar todo esse histórico como contexto para a próxima resposta. O role de cada objeto Content precisa alternar entre user e model.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Pontos principais

  • Content é o envelope: é o contêiner de nível superior para uma troca de mensagens, seja do usuário ou do modelo.
  • O Part permite a multimodalidade: use vários objetos Part em um único objeto Content para combinar diferentes tipos de dados (texto, imagem, URI de vídeo etc.).
  • Escolha seu método de dados:
    • Para mídias pequenas e incorporadas diretamente (como a maioria das imagens), use um Part com inline_data.
    • Para arquivos maiores ou que você quer reutilizar em várias solicitações, use a API File para fazer upload do arquivo e referenciá-lo com uma parte file_data.
  • Gerenciar o histórico de conversas: para aplicativos de chat que usam a API REST, crie a matriz contents anexando objetos Content para cada turno, alternando entre as funções "user" e "model". Se você estiver usando um SDK, consulte a documentação dele para saber a maneira recomendada de gerenciar o histórico de conversas.

Exemplos de respostas

Os exemplos a seguir mostram como esses componentes se unem para diferentes tipos de solicitações.

Resposta somente texto

Uma resposta de texto simples consiste em uma matriz candidates com um ou mais objetos content que contêm a resposta do modelo.

Confira a seguir um exemplo de resposta padrão:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Confira a seguir uma série de respostas de streaming. Cada resposta contém um responseId que une a resposta completa:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

API Live (BidiGenerateContent) WebSockets

A API Live oferece uma API com estado baseada em WebSocket para streaming bidirecional, permitindo casos de uso de streaming em tempo real. Consulte o guia da API Live e a referência da API Live para mais detalhes.

Modelos especializados

Além da família de modelos do Gemini, a API Gemini oferece endpoints para modelos especializados, como Imagen, Lyria e modelos de embedding. Confira esses guias na seção "Modelos".

APIs da plataforma

O restante dos endpoints permite usar outros recursos com os principais endpoints descritos até agora. Confira os tópicos Modo em lote e API File na seção "Guias" para saber mais.

A seguir

Se você está começando, confira os guias a seguir, que vão ajudar você a entender o modelo de programação da API Gemini:

Confira também os guias de recursos, que apresentam diferentes recursos da API Gemini e fornecem exemplos de código: