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 realizar tu primera llamada a la API. Si buscas referencias para 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 endpoints principales:

  • Generación de contenido estándar (generateContent): Es un extremo REST estándar que procesa tu solicitud y devuelve 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 los chatbots.
  • Live API (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 REST estándar para enviar lotes de solicitudes generateContent.
  • Embeddings (embedContent): Es un extremo REST estándar que genera un vector de incorporación de texto a partir de la entrada Content.
  • 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 la plataforma: Son extremos de utilidad que admiten capacidades principales, como la carga de archivos y el recuento de 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 Cómo usar claves de la 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:

  • Objeto Content: Representa un solo turno en una conversación.
  • Objeto Part: Es un fragmento de datos dentro de un turno de Content (como texto o una imagen).
  • inline_data (Blob): Es un contenedor para los bytes de medios 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 conversación, 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 respuesta es similar para los modos de transmisión y estándar, excepto por lo siguiente:

En términos generales, 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 devolvió el modelo.

Ejemplos de solicitudes

En los siguientes ejemplos, se muestra cómo se combinan 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. A su vez, el array parts de ese objeto 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, debes definir el array contents con varios objetos Content. La API usará todo este historial como contexto para la próxima 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 clave

  • 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, URI de imagen, URI de video, etcétera).
  • Elige tu método de datos:
    • Para los medios pequeños incorporados directamente (como la mayoría de las imágenes), usa un Part con inline_data.
    • Para archivos más grandes o archivos que quieras reutilizar en varias 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 array contents agregando objetos Content para cada turno, alternando entre los roles "user" y "model". Si usas un SDK, consulta su documentación para conocer la forma recomendada de administrar el historial de conversaciones.

Ejemplos de respuestas

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

Respuesta de solo texto

Una respuesta de texto simple 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 vincula 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 de Live (BidiGenerateContent) API de WebSockets

La API de Live ofrece una API basada en WebSocket con estado para la transmisión bidireccional que permite casos de uso de transmisión en tiempo real. Puedes consultar la guía de la API de Live y la referencia de la API de Live 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 la plataforma

El resto de los extremos habilitan capacidades adicionales para usar con los extremos principales que se describieron hasta ahora. Consulta los temas Modo por lotes y API de archivos 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: