Gemini API reference

En esta referencia de la API, se describen las APIs estándar, de transmisión y en tiempo real que puedes usar para interactuar con los modelos de Gemini. Puedes usar las APIs de REST en cualquier entorno que admita solicitudes HTTP. Consulta la guía de inicio rápido para comenzar a usar tu primera llamada a la API. Si buscas las referencias de nuestras bibliotecas y SDKs específicos del lenguaje, ve al vínculo de ese lenguaje en la navegación de la izquierda, en Referencias del SDK.

Extremos principales

La API de Gemini se organiza en torno a los siguientes extremos principales:

  • Generación de contenido estándar (generateContent): Es un extremo de REST estándar que procesa tu solicitud y muestra la respuesta completa del modelo en un solo paquete. Es ideal para tareas no interactivas en las que puedes esperar el resultado completo.
  • Generación de contenido de transmisión (streamGenerateContent): Usa eventos enviados por el servidor (SSE) para enviarte fragmentos de la respuesta a medida que se generan. Esto proporciona una experiencia más rápida e interactiva para aplicaciones como chatbots.
  • API en vivo (BidiGenerateContent): Es una API con estado basada en WebSocket para la transmisión bidireccional, diseñada para casos de uso conversacionales en tiempo real.
  • Modo por lotes (batchGenerateContent): Es un extremo de REST estándar para enviar lotes de solicitudes generateContent.
  • Embeddings (embedContent): Es un extremo de REST estándar que genera un vector de incorporación de texto a partir de la Content de entrada.
  • APIs de Gen Media: Son extremos para generar contenido multimedia con nuestros modelos especializados como Imagen para la generación de imágenes, y Veo para la generación de videos. Gemini también tiene estas capacidades integradas a las que puedes acceder con la API de generateContent.
  • APIs de plataforma: Son extremos de utilidad que admiten capacidades básicas, como subir archivos y contar tokens.

Autenticación

Todas las solicitudes a la API de Gemini deben incluir un encabezado x-goog-api-key con tu clave de API. Crea una con unos pocos clics en Google AI Studio.

A continuación, se muestra un ejemplo de solicitud con la clave de API incluida en el encabezado:

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 obtener instrucciones sobre cómo pasar tu clave a la API con los SDKs de Gemini, consulta la guía Usa claves de API de Gemini.

Generación de contenido

Este es el extremo central para enviar instrucciones al modelo. Existen dos extremos para generar contenido. La diferencia clave es cómo recibes la respuesta:

  • generateContent (REST): Recibe una solicitud y proporciona una sola respuesta después de que el modelo finaliza toda su generación.
  • streamGenerateContent (SSE): Recibe exactamente la misma solicitud, pero el modelo transmite fragmentos de la respuesta a medida que se generan. Esto proporciona una mejor experiencia del usuario para las aplicaciones interactivas, ya que te permite mostrar resultados parciales de inmediato.

Estructura del cuerpo de la solicitud

El cuerpo de la solicitud es un objeto JSON que es idéntico para los modos estándar y de transmisión, y se compila a partir de algunos objetos principales:

  • Content objeto: Representa un solo turno en una conversación.
  • Part objeto: Es una parte de datos dentro de un turno Content (como texto o una imagen).
  • inline_data (Blob): Es un contenedor para bytes de contenido multimedia sin procesar y su tipo de MIME.

En el nivel más alto, el cuerpo de la solicitud contiene un objeto contents, que es una lista de objetos Content, cada uno de los cuales representa turnos en la conversación. En la mayoría de los casos, para la generación de texto básica, tendrás un solo objeto Content, pero, si deseas mantener el historial de conversaciones, puedes usar varios objetos Content.

A continuación, se muestra un cuerpo de solicitud 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
          ]
      }
    ]
  }'

Estructura del cuerpo de la respuesta

El cuerpo de la respuesta es similar para ambos los modos de transmisión y estándar, excepto por lo siguiente:

En un nivel superior, el cuerpo de la respuesta contiene un objeto candidates, que es una lista de objetos Candidate. El objeto Candidate contiene un objeto Content que tiene la respuesta generada que se muestra desde el modelo.

Ejemplos de solicitudes

En los siguientes ejemplos, se muestra cómo se unen estos componentes para diferentes tipos de solicitudes.

Instrucción de solo texto

Una instrucción de texto simple consta de un array contents con un solo objeto Content. El array parts de ese objeto, a su vez, contiene un solo objeto Part con un 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."
          }
        ]
      }
    ]
  }'

Instrucción multimodal (texto e imagen)

Para proporcionar texto y una imagen en una instrucción, el array parts debe contener dos objetos Part: uno para el texto y otro para la imagen 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?"},
      ]
    }]
  }'

Conversaciones de varios turnos (chat)

Para crear una conversación con varios turnos, define el array contents con varios objetos Content. La API usará todo este historial como contexto para la siguiente respuesta. El role de cada objeto Content debe alternar entre user y 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." }
        ]
      }
    ]
  }'

Conclusiones principales

  • Content es el sobre: Es el contenedor de nivel superior para un turno de mensaje, ya sea del usuario o del modelo.
  • Part habilita la multimodalidad: Usa varios objetos Part dentro de un solo objeto Content para combinar diferentes tipos de datos (texto, imagen, URI de video, etcétera).
  • Elige tu método de datos:
    • Para contenido multimedia pequeño y directamente incorporado (como la mayoría de las imágenes), usa un Part con inline_data.
    • Para archivos más grandes o que deseas reutilizar en las solicitudes, usa la API de File para subir el archivo y hacer referencia a él con una parte file_data.
  • Administra el historial de conversaciones: Para las aplicaciones de chat que usan la API de REST, compila el contents array agregando Content objetos para cada turno, alternando entre "user" y "model" funciones. Si usas un SDK, consulta la documentación del SDK para conocer la forma recomendada de administrar el historial de conversaciones.

Ejemplos de respuestas

En los siguientes ejemplos, se muestra cómo se unen estos componentes para diferentes tipos de solicitudes.

Respuesta de solo texto

Una respuesta de texto predeterminada consta de un array candidates con uno o más objetos content que contienen la respuesta del modelo.

A continuación, se muestra un ejemplo de una respuesta estándar:

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

A continuación, se muestra una serie de respuestas de transmisión. Cada respuesta contiene un responseId que une la respuesta 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 en vivo (BidiGenerateContent) API de WebSockets

La API en vivo ofrece una API con estado basada en WebSocket para la transmisión bidireccional para habilitar casos de uso de transmisión en tiempo real. Puedes consultar la guía de la API en vivo y la referencia de la API en vivo para obtener más detalles.

Modelos especializados

Además de la familia de modelos de Gemini, la API de Gemini ofrece extremos para modelos especializados, como Imagen, Lyria y modelos de incorporación. Puedes consultar estas guías en la sección Modelos.

APIs de plataforma

El resto de los extremos habilitan capacidades adicionales para usar con los extremos principales descritos hasta ahora. Consulta los temas Modo por lotes y API de File en la sección Guías para obtener más información.

¿Qué sigue?

Si recién comienzas, consulta las siguientes guías, que te ayudarán a comprender el modelo de programación de la API de Gemini:

También puedes consultar las guías de capacidades, que presentan diferentes funciones de la API de Gemini y proporcionan ejemplos de código: