Familia Gemini

Los modelos de texto Gemini de Google, principalmente la serie Gemini 3.x. Se pueden llamar de dos formas: con el endpoint nativo de Gemini (el SDK oficial google-genai funciona directamente) o con el endpoint compatible con OpenAI.

Tareas habituales

Controlar el thinking El thinking está activado por defecto; cómo reducirlo cuando tarda demasiado.Búsqueda de Google Obtener información en tiempo real de la web con sus fuentes.PDF y audio Subir documentos y audio para analizarlos.Solución de errores Respuesta truncada, modelo retirado, contexto excedido.Uso en Gemini CLI Configuración y preguntas frecuentes.

Modelos

Admiten entrada de texto, imágenes, audio y PDF, con un contexto de aproximadamente 1M tokens. La lista completa de modelos y los precios en tiempo real están en la página de modelos ; también puede consultarlos con la Models API. Los modelos de generación de imágenes están en Nano Banana.

IDs de modelo habituales (cópielos tal cual al llamar)

Gemini 3.8 Flashgoogle/gemini-3.8-flash

Gemini 3.1 Pro Previewgoogle/gemini-3.1-pro-preview

Gemini 3.5 Flash-Litegoogle/gemini-3.5-flash-liteSin thinking por defecto; respuesta rápida

Gemini 3.5 Flashgoogle/gemini-3.5-flash

El ID de modelo puede omitir el prefijo google/. En la URL del endpoint nativo también puede incluirse o no el prefijo: tanto models/google/gemini-3.8-flash:generateContent como models/gemini-3.8-flash:generateContent son válidos.

Elección de endpoint

ClaveSi necesita controlar el thinking con precisión u obtener las fuentes de la búsqueda de Google, use el endpoint nativo de Gemini.

	Endpoint nativo de Gemini (recomendado)	Endpoint compatible con OpenAI
URL	`POST https://api.ofox.ai/gemini/v1beta/models/<ID de modelo>:generateContent`	`POST https://api.ofox.ai/v1/chat/completions`
SDK	`google-genai`, con `base_url` igual a `https://api.ofox.ai/gemini`	SDK de OpenAI, con `base_url` igual a `https://api.ofox.ai/v1`
Autenticación	`x-goog-api-key: <Key>`; también acepta `Authorization: Bearer <Key>`	`Authorization: Bearer <Key>`
Streaming	`:streamGenerateContent?alt=sse`	`"stream": true`
Thinking	`thinkingConfig`; puede devolver un resumen del thinking	`reasoning_effort` o `reasoning`; devuelve `reasoning_details`
Búsqueda de Google	`tools: [{"google_search": {}}]`; devuelve las fuentes y los términos de búsqueda	`web_search_options`; solo devuelve la respuesta

El endpoint nativo no admite pasar la Key mediante el parámetro de URL ?key=, que devuelve 401; use la cabecera.

Actualmente, los modelos Gemini los ofrece Google Vertex AI (google_vertex). Los parámetros completos de la petición se describen en Generate Content.

Ejemplos de llamada

Python (google-genai)

gemini_basic.py


import os
from google import genai
 
client = genai.Client(
    api_key=os.environ["OFOX_API_KEY"],
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
resp = client.models.generate_content(
    model="google/gemini-3.8-flash",
    contents="Explica en una frase qué es la idempotencia.",
)
print(resp.text)

cURL

Terminal


curl "https://api.ofox.ai/gemini/v1beta/models/google/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explica en una frase qué es la idempotencia."}]}]
  }'

Python (SDK de OpenAI)

gemini_openai_sdk.py


import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])
 
resp = client.chat.completions.create(
    model="google/gemini-3.8-flash",
    messages=[{"role": "user", "content": "Explica en una frase qué es la idempotencia."}],
)
print(resp.choices[0].message.content)

Caché de prompts

Gemini aplica caché implícita automáticamente: cuando el prefijo de una petición coincide con el de peticiones recientes y es lo bastante largo, la parte acertada se factura al precio de lectura de caché, sin cambiar la petición.

Elemento	Detalle
Confirmar un acierto	En el endpoint nativo, `usageMetadata.cachedContentTokenCount` es mayor que 0; en el compatible con OpenAI, `usage.prompt_tokens_details.cached_tokens` es mayor que 0
Estabilidad	La caché implícita funciona según el principio de mejor esfuerzo; incluso peticiones con el mismo prefijo pueden no acertar
Caché determinista	Si necesita reutilizar de forma estable bloques grandes de contenido, use la caché explícita; consulte Caché explícita de Gemini

Errores habituales

ClaveSi la respuesta se corta a medias, normalmente es porque el thinking consumió el límite de salida; no es un error: revise finishReason.

HTTP · estado	Mensaje de error original	Causa	Solución
200, `finishReason: "MAX_TOKENS"`	—	La longitud total del thinking y la respuesta alcanzó `maxOutputTokens` y la respuesta se truncó	Aumente `maxOutputTokens` o reduzca el thinking con `thinkingLevel: "low"`. En el endpoint compatible con OpenAI aparece como `finish_reason: "length"`
400 `INVALID_ARGUMENT`	`The input token count exceeds the maximum number of tokens allowed 1048576.`	La entrada supera el contexto del modelo	Acorte la entrada
410 `model_deprecated`	`Model 'google/gemini-3-pro-preview' is deprecated and no longer accepts requests; please switch to an active model`	El modelo en versión preview se ha retirado	Use la versión estable o una preview más reciente, como `google/gemini-3.1-pro-preview`
404 `model_not_found`	`Model 'google/gemini-9-pro' not found`	ID de modelo mal escrito	Copie el ID de modelo de esta página
401	—	La Key se pasó mediante `?key=`	Use la cabecera `x-goog-api-key`
Tiempo de espera agotado	—	El thinking está activado por defecto y las preguntas complejas tardan bastante	Use streaming, configure el tiempo de espera del cliente en 300 segundos o más, o reduzca el thinking

Otros errores generales: Gestión de errores.

Documentación oficial

La documentación oficial describe el comportamiento al llamar directamente a Google. Al llamar a través de OfoxAI, los IDs de modelo y las URL de los endpoints son los de esta página.

Preguntas frecuentes

¿Cómo se escribe el ID de modelo de Gemini?

El formato estándar es google/gemini-3.8-flash; también puede omitir el prefijo google/. En la URL del endpoint nativo, el prefijo también es opcional.

¿Qué hago si Gemini responde muy despacio?

Salvo Flash-Lite, Gemini tiene el thinking activado por defecto, y las preguntas complejas pueden tardar más de 1 minuto. Puede enviar thinkingLevel: "low" para reducir el thinking, en algunos modelos thinkingBudget: 0 para desactivarlo, o cambiar a un modelo Flash-Lite, que no usa thinking por defecto.

¿Cómo se desactiva el thinking en Gemini?

En 3.5 Flash y 3 Flash Preview puede enviar thinkingBudget: 0 para desactivarlo; en 3.1 Pro Preview y 3.8 Flash no se puede desactivar por completo, pero sí reducirlo con thinkingLevel: "low". La serie Flash-Lite no usa thinking por defecto.

¿La respuesta de Gemini se trunca con finishReason igual a MAX_TOKENS?

Los tokens de thinking también se cuentan en maxOutputTokens. Aumente maxOutputTokens o reduzca el thinking.

¿Gemini puede buscar en la web?

Sí. En el endpoint nativo, añada {"google_search": {}} a tools; el groundingMetadata de la respuesta contiene los términos de búsqueda y las fuentes. En el endpoint compatible con OpenAI, envíe web_search_options: {}.

¿Cómo se autentica el endpoint nativo de Gemini?

Pase la API Key de OfoxAI en la cabecera x-goog-api-key; también se acepta Authorization: Bearer. No se admite el parámetro de URL ?key=.

¿Error 410 model_deprecated?

Ese modelo en versión preview se ha retirado, por ejemplo gemini-3-pro-preview. Use google/gemini-3.1-pro-preview o un modelo de versión estable.

¿Gemini puede analizar audio y PDF?

Sí. En el endpoint nativo, los archivos se envían codificados en base64 mediante inline_data; en el endpoint compatible con OpenAI, el PDF se envía con un bloque de contenido file y el audio con un bloque de contenido input_audio.