Gemini Generating Content - CometAPI Documentation

POST

v1beta

models

{model}

{operator}

from google import genai

client = genai.Client(
    api_key="<COMETAPI_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
)

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Explain how AI works in a few words",
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "<string>",
        "parts": [
          {
            "text": "<string>",
            "functionCall": {
              "name": "<string>",
              "args": {}
            },
            "inlineData": {
              "mimeType": "<string>",
              "data": "<string>"
            },
            "thought": true
          }
        ]
      },
      "safetyRatings": [
        {
          "category": "<string>",
          "probability": "<string>",
          "blocked": true
        }
      ],
      "citationMetadata": {
        "citationSources": [
          {
            "startIndex": 123,
            "endIndex": 123,
            "uri": "<string>",
            "license": "<string>"
          }
        ]
      },
      "tokenCount": 123,
      "avgLogprobs": 123,
      "groundingMetadata": {
        "groundingChunks": [
          {
            "web": {
              "uri": "<string>",
              "title": "<string>"
            }
          }
        ],
        "groundingSupports": [
          {
            "groundingChunkIndices": [
              123
            ],
            "confidenceScores": [
              123
            ],
            "segment": {
              "startIndex": 123,
              "endIndex": 123,
              "text": "<string>"
            }
          }
        ],
        "webSearchQueries": [
          "<string>"
        ]
      },
      "index": 123
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "<string>",
        "probability": "<string>",
        "blocked": true
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 123,
    "candidatesTokenCount": 123,
    "totalTokenCount": 123,
    "trafficType": "<string>",
    "thoughtsTokenCount": 123,
    "promptTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ]
  },
  "modelVersion": "<string>",
  "createTime": "<string>",
  "responseId": "<string>"
}

CometAPI es compatible con el formato nativo de API de Gemini, lo que te brinda acceso completo a funciones específicas de Gemini como control de thinking, conexión con Google Search, modalidades nativas de generación de imágenes y más. Usa este endpoint cuando necesites capacidades que no están disponibles a través del endpoint de chat compatible con OpenAI.

Se admiten tanto los encabezados x-goog-api-key como Authorization: Bearer para la autenticación.

Inicio rápido

Para usar cualquier SDK de Gemini o cliente HTTP con CometAPI, reemplaza la URL base y la clave de API:

Configuración	Valor predeterminado de Google	CometAPI
URL base	`generativelanguage.googleapis.com`	`api.cometapi.com`
Clave de API	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

Configurar thinking (reasoning)

Los modelos de Gemini pueden realizar reasoning interno antes de generar una respuesta. El método de control depende de la generación del modelo.

Gemini 3 (thinkingLevel)
Gemini 2.5 (thinkingBudget)

Los modelos Gemini 3 usan thinkingLevel para controlar la profundidad del reasoning. Niveles disponibles: MINIMAL, LOW, MEDIUM, HIGH.Usa gemini-3-flash-preview como model de ejemplo predeterminado, a menos que necesites específicamente una variante distinta de Gemini 3.

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Explain quantum physics simply."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "LOW"}
    }
  }'

Los modelos Gemini 2.5 usan thinkingBudget para un control detallado a nivel de Token:

0 — desactivar thinking
-1 — dinámico (el modelo decide, valor predeterminado)
> 0 — presupuesto específico de Tokens (por ejemplo, 1024, 2048)

curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Solve this logic puzzle step by step."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingBudget": 2048}
    }
  }'

Usar thinkingLevel con modelos Gemini 2.5 (o thinkingBudget con modelos Gemini 3) puede causar errores. Usa el parámetro correcto para la versión de tu modelo.

Transmitir respuestas en streaming

Para recibir Server-Sent Events a medida que el modelo genera contenido, usa streamGenerateContent?alt=sse como operador. Cada evento SSE contiene una línea data: con un objeto JSON GenerateContentResponse.

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --no-buffer \
  -d '{
    "contents": [{"parts": [{"text": "Write a short poem about the stars"}]}]
  }'

Establecer instrucciones del sistema

Para guiar el comportamiento del modelo a lo largo de toda la conversación, usa systemInstruction:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "What is 2+2?"}]}],
    "systemInstruction": {
      "parts": [{"text": "You are a math tutor. Always show your work."}]
    }
  }'

Salida JSON de la solicitud

Para forzar una salida JSON estructurada, establece responseMimeType. Opcionalmente, proporciona un responseSchema para una validación estricta del esquema:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "List 3 planets with their distances from the sun"}]}],
    "generationConfig": {
      "responseMimeType": "application/json"
    }
  }'

Fundamentar con Google Search

Para habilitar la búsqueda web en tiempo real, añade una herramienta googleSearch:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Who won the euro 2024?"}]}],
    "tools": [{"google_search": {}}]
  }'

La respuesta incluye groundingMetadata con URL de las fuentes y puntuaciones de confianza.

Ejemplo de respuesta

Una respuesta típica del endpoint Gemini de CometAPI:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Hello"}]
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.0023
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 1,
    "totalTokenCount": 30,
    "trafficType": "ON_DEMAND",
    "thoughtsTokenCount": 24,
    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 5}],
    "candidatesTokensDetails": [{"modality": "TEXT", "tokenCount": 1}]
  },
  "modelVersion": "gemini-3-flash-preview",
  "createTime": "2026-03-25T04:21:43.756483Z",
  "responseId": "CeynaY3LDtvG4_UP0qaCuQY"
}

El campo thoughtsTokenCount en usageMetadata muestra cuántos tokens gastó el modelo en razonamiento interno, incluso cuando la salida de pensamiento no se incluye en la respuesta.

Comparar con el endpoint compatible con OpenAI

Función	Gemini Native (`/v1beta/models/...`)	OpenAI-Compatible (`/v1/chat/completions`)
Control de pensamiento	`thinkingConfig` con `thinkingLevel` / `thinkingBudget`	No disponible
Fundamentación con Google Search	`tools: [\{"google_search": \{\}\}]`	No disponible
Fundamentación con Google Maps	`tools: [\{"googleMaps": \{\}\}]`	No disponible
Modalidad de generación de imágenes	`responseModalities: ["IMAGE"]`	No disponible
Encabezado de autenticación	`x-goog-api-key` o `Bearer`	Solo `Bearer`
Formato de respuesta	Formato nativo de Gemini (`candidates`, `parts`)	Formato OpenAI (`choices`, `message`)

Autorizaciones

x-goog-api-key

string

header

requerido

Your CometAPI key passed via the x-goog-api-key header. Bearer token authentication (Authorization: Bearer <key>) is also supported.

Parámetros de ruta

model

string

requerido

Gemini model ID. Example: gemini-3-flash-preview, gemini-2.5-pro. See the Models page for current options.

operator

enum<string>

requerido

The operation to perform. Use generateContent for synchronous responses, or streamGenerateContent?alt=sse for Server-Sent Events streaming.

Opciones disponibles:

generateContent,

streamGenerateContent?alt=sse

Cuerpo

application/json

contents

object[]

Show child attributes

systemInstruction

object

System instructions that guide the model's behavior across the entire conversation. Text only.

Show child attributes

tools

object[]

Tools the model may use to generate responses. Supports function declarations, Google Search, Google Maps, and code execution.

Show child attributes

toolConfig

object

Configuration for tool usage, such as function calling mode.

Show child attributes

safetySettings

object[]

Safety filter settings. Override default thresholds for specific harm categories.

Show child attributes

generationConfig

object

Configuration for model generation behavior including temperature, output length, and response format.

Show child attributes

cachedContent

string

The name of cached content to use as context. Format: cachedContents/{id}. See the Gemini context caching documentation for details.

Respuesta

200 - application/json

Successful response. For streaming requests, the response is a stream of SSE events, each containing a GenerateContentResponse JSON object prefixed with data:.

candidates

object[]

The generated response candidates.

Show child attributes

promptFeedback

object

Feedback on the prompt, including safety blocking information.

Show child attributes

usageMetadata

object

Token usage statistics for the request.

Show child attributes

modelVersion

string

The model version that generated this response.

createTime

string

The timestamp when this response was created (ISO 8601 format).

responseId

string

Unique identifier for this response.

Anthropic Messages

Embeddings

from google import genai

client = genai.Client(
    api_key="<COMETAPI_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
)

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Explain how AI works in a few words",
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "<string>",
        "parts": [
          {
            "text": "<string>",
            "functionCall": {
              "name": "<string>",
              "args": {}
            },
            "inlineData": {
              "mimeType": "<string>",
              "data": "<string>"
            },
            "thought": true
          }
        ]
      },
      "safetyRatings": [
        {
          "category": "<string>",
          "probability": "<string>",
          "blocked": true
        }
      ],
      "citationMetadata": {
        "citationSources": [
          {
            "startIndex": 123,
            "endIndex": 123,
            "uri": "<string>",
            "license": "<string>"
          }
        ]
      },
      "tokenCount": 123,
      "avgLogprobs": 123,
      "groundingMetadata": {
        "groundingChunks": [
          {
            "web": {
              "uri": "<string>",
              "title": "<string>"
            }
          }
        ],
        "groundingSupports": [
          {
            "groundingChunkIndices": [
              123
            ],
            "confidenceScores": [
              123
            ],
            "segment": {
              "startIndex": 123,
              "endIndex": 123,
              "text": "<string>"
            }
          }
        ],
        "webSearchQueries": [
          "<string>"
        ]
      },
      "index": 123
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "<string>",
        "probability": "<string>",
        "blocked": true
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 123,
    "candidatesTokenCount": 123,
    "totalTokenCount": 123,
    "trafficType": "<string>",
    "thoughtsTokenCount": 123,
    "promptTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ]
  },
  "modelVersion": "<string>",
  "createTime": "<string>",
  "responseId": "<string>"
}

Documentation Index

​Inicio rápido

​Configurar thinking (reasoning)

​Transmitir respuestas en streaming

​Establecer instrucciones del sistema

​Salida JSON de la solicitud

​Fundamentar con Google Search

​Ejemplo de respuesta

​Comparar con el endpoint compatible con OpenAI

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Inicio rápido

Configurar thinking (reasoning)

Transmitir respuestas en streaming

Establecer instrucciones del sistema

Salida JSON de la solicitud

Fundamentar con Google Search

Ejemplo de respuesta

Comparar con el endpoint compatible con OpenAI