Gemini API reference

Esta referência da API descreve as APIs padrão, de streaming e em tempo real que podem ser usadas 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 a fazer sua primeira chamada de API. Se você estiver procurando as referências das nossas bibliotecas e SDKs específicos do idioma, acesse o link do idioma na navegação à esquerda em Referências do 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. Essa opção é mais adequada para tarefas não interativas em que você pode esperar o resultado completo.
  • Geração de conteúdo de streaming (streamGenerateContent): usa eventos enviados pelo servidor (SSE) para enviar blocos da resposta à medida que são gerados. 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 conversacionais 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 Content de entrada.
  • APIs Gen Media: endpoints para gerar mídia com nossos modelos especializados como o Imagen para geração de imagens, e o Veo para geração de vídeos. O Gemini também tem esses recursos integrados, que podem ser acessados usando a API generateContent.
  • APIs da plataforma: endpoints de utilitários que oferecem suporte a recursos principais, como upload de arquivos e contagem de 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 a seguir 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 da API Gemini.

Geração de conteúdo

Esse é 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 termina toda a geração.
  • streamGenerateContent (SSE): recebe a mesma solicitação, mas o modelo transmite blocos da resposta à medida que são gerados. Isso oferece uma melhor experiência do usuário para aplicativos interativos, porque permite mostrar resultados parciais imediatamente.

Estrutura do corpo da solicitação

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

  • Content objeto: representa um único turno em uma conversa.
  • Part objeto: um pedaço de dados em um turno Content (como texto ou uma imagem).
  • inline_data (Blob): um contêiner para bytes de mídia brutos e o tipo MIME.

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 da conversa, poderá usar 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 ambos os modos de streaming e padrão, exceto pelo seguinte:

Em um nível alto, 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ção

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 inline_data da imagem.

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árias interações (chat)

Para criar uma conversa com várias interações, 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 um turno de mensagem, seja do usuário ou do modelo.
  • 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 uma 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 da conversa: 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 da conversa.

Exemplos de resposta

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

Resposta somente de texto

Uma resposta de texto padrão 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
    }
  ],
}

A seguir, há uma série de respostas de streaming. Cada resposta contém um responseId que vincula 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) API 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 em tempo real e a referência da API em tempo real para mais detalhes.

Modelos especializados

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

APIs da plataforma

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

A seguir

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

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