Generar contenido

POST

v1beta

models

{model}

{operator}

import os
from google import genai

client = genai.Client(
    api_key=os.environ["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 admite el formato nativo de la API de Gemini, lo que te da acceso completo a funciones específicas de Gemini como control de pensamiento, anclaje 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.

Usa la referencia oficial de la API GenerateContent de Google como fuente autorizada para conocer los campos completos de la solicitud, el esquema de respuesta y el comportamiento específico de los modelos Gemini. Esta página de CometAPI explica cómo enviar ese formato de solicitud nativo a través de CometAPI.

Los parámetros de solicitud y los campos de respuesta de Gemini pueden cambiar a medida que Google actualiza la API nativa. Consulta la documentación de generación de texto de Gemini para ver la lista completa más reciente de parámetros y el comportamiento específico del proveedor.

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:

Setting	Google Default	CometAPI
URL base	Valor predeterminado de Google	CometAPI
Clave de API	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

Enviar entrada de video

Gemini generateContent acepta video como una parte de contenido. Elige la forma de entrada según dónde esté almacenado el video:

Fuente de video	Parte de la solicitud	Usar cuando
Archivo de video local	`inlineData`	El video es lo suficientemente pequeño como para enviarlo como base64 en la solicitud JSON.
URL pública de video	`fileData.fileUri`	El video está disponible a través de una URL HTTPS pública que no requiere autenticación.

Para solicitudes REST y curl, usa los nombres de campo en camelCase de Gemini, como inlineData.mimeType y fileData.fileUri. No envíes medios por URL como file_data.file_uri.

Este ejemplo lee un archivo MP4 local, lo codifica como base64 y lo envía en el cuerpo de la solicitud:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_PATH="./your_video.mp4"
VIDEO_B64=$(base64 < "$VIDEO_PATH" | tr -d '\n')

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<EOF
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "video/mp4",
            "data": "${VIDEO_B64}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF

Este ejemplo envía una URL pública de MP4 con fileData.fileUri:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_URL="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<EOF
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "${VIDEO_URL}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF

CometAPI no recomienda un flujo de carga separado de Gemini Files API para este endpoint. Envía los medios en la propia solicitud generateContent con inlineData o fileData.fileUri.

Configurar thinking (reasoning)

Los modelos Gemini pueden realizar razonamiento 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 razonamiento. Niveles disponibles: MINIMAL, LOW, MEDIUM, HIGH.Usa gemini-3-flash-preview como model de ejemplo predeterminado a menos que necesites específicamente una variante diferente 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 — desactiva thinking
-1 — dinámico (el modelo decide, predeterminado)
> 0 — presupuesto específico de tokens (p. ej., 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

Para recibir eventos enviados por el servidor 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 durante 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."}]
    }
  }'

Solicitar salida JSON

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"
    }
  }'

Basarse en Google Search

Para habilitar la búsqueda web en tiempo real, agrega 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 de 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.

Comparación con el endpoint compatible con OpenAI

Característica	Gemini nativo (`/v1beta/models/...`)	Compatible con OpenAI (`/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 $COMETAPI_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[]

Conversation content. Each entry has an optional role (user or model) and a parts array.

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.

Crear un mensaje

APIs de generación y edición de imágenes

import os
from google import genai

client = genai.Client(
    api_key=os.environ["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>"
}

Moderación de contenido

Claves API

Inicio rápido

Enviar entrada de video

Configurar thinking (reasoning)

Transmitir respuestas

Establecer instrucciones del sistema

Solicitar salida JSON

Basarse en Google Search

Ejemplo de respuesta

Comparación con el endpoint compatible con OpenAI

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

​Inicio rápido

​Enviar entrada de video

​Configurar thinking (reasoning)

​Transmitir respuestas

​Establecer instrucciones del sistema

​Solicitar salida JSON

​Basarse en Google Search

​Ejemplo de respuesta

​Comparación con el endpoint compatible con OpenAI

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Inicio rápido

Enviar entrada de video

Configurar thinking (reasoning)

Transmitir respuestas

Establecer instrucciones del sistema

Solicitar salida JSON

Basarse en Google Search

Ejemplo de respuesta

Comparación con el endpoint compatible con OpenAI