Llamar a Gemini con el SDK de OpenAI: tutorial de integración cambiando solo base_url, la API Key y el nombre del modelo

Google lo dice sin rodeos: los modelos Gemini se pueden acceder mediante los SDK de OpenAI para Python y TypeScript/JavaScript; en esencia, basta con cambiar tres líneas de código. El endpoint indicado en la documentación oficial de compatibilidad es https://generativelanguage.googleapis.com/v1beta/openai/, y el modelo de ejemplo es gemini-3.5-flash (Compatibilidad de Google con OpenAI). Esto resulta muy cómodo para proyectos que ya usan el SDK de OpenAI: no hace falta desmontar primero la abstracción de provider ni cambiar toda la pila de llamadas; lo importante es hacerlo funcionar primero.

Primero confirma qué modelo quieres llamar

A fecha de 2026-06-14, la página de modelos de Google lista Gemini 3.5 Flash como Stable e indica que el código del modelo es gemini-3.5-flash; este modelo admite hasta 1,048,576 tokens de entrada y 65,536 tokens de salida, soporta entradas de texto, imagen, vídeo, audio y PDF, y su salida es texto (Gemini 3.5 Flash). La página del modelo se actualizó por última vez el 2026-05-19 UTC.

También hay que revisar la documentación de precios del día. La página de precios de Google se actualizó por última vez el 2026-06-09 UTC; para gemini-3.5-flash, el nivel Standard paid tier indica un precio de entrada de $1.50 / 1M tokens y de salida de $9.00 / 1M tokens, donde el precio de salida incluye los thinking tokens; Batch cuesta $0.75 para entrada y $4.50 para salida (Precios de Gemini API).

Modelo	Estado	Límite de entrada	Entrada Standard	Salida Standard
gemini-3.5-flash	Stable	1,048,576	$1.50 / 1M tokens	$9.00 / 1M tokens
gemini-3-flash-preview	Preview	Ver página del modelo	$0.50 / 1M tokens	$3.00 / 1M tokens
gemini-3.1-flash-lite	Stable	Ver página del modelo	$0.25 / 1M tokens	$1.50 / 1M tokens

gemini-3-flash-preview y gemini-3.1-flash-lite proceden de las páginas actuales de modelos y precios de Google (Modelos, Precios). No uses directamente un modelo Preview como valor predeterminado de producción: la versión y los límites pueden cambiar.

Python: apunta el cliente de OpenAI a Gemini

Primero instala el SDK:

pip install openai
export GEMINI_API_KEY="你的 Gemini API Key"

Después conserva la forma de llamada del SDK de OpenAI:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "你是一个简洁的工程助手。"},
        {"role": "user", "content": "用三句话解释什么是 API 兼容层。"},
    ],
)

print(resp.choices[0].message.content)

En realidad solo hay tres cambios: sustituir api_key por la clave de Gemini, cambiar base_url al endpoint compatible con OpenAI de Google, y cambiar model por el nombre del modelo Gemini. Ten en cuenta que la URL del ejemplo oficial termina con /; no la borres por descuido para luego acabar investigando un 404.

TypeScript: también es baseURL

En un proyecto Node ocurre lo mismo:

npm install openai
export GEMINI_API_KEY="你的 Gemini API Key"

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const response = await openai.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "user", content: "给我一个 JSON Schema 校验的最小例子。" },
  ],
});

console.log(response.choices[0].message.content);

Si tu proyecto ya encapsula el provider mediante variables de entorno, el cambio será aún menor:

OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="$GEMINI_API_KEY"
OPENAI_MODEL="gemini-3.5-flash"

El problema de muchos proyectos antiguos está aquí: no pasa nada si la variable sigue llamándose OPENAI_API_KEY; su valor puede ser una clave de Gemini. Lo que realmente determina adónde va la petición es base_url/baseURL.

Qué hacer con streaming, llamadas a herramientas y thinking

La documentación de compatibilidad de Google ofrece ejemplos de streaming, function calling, structured outputs, image understanding y más (Compatibilidad con OpenAI). En proyectos que ya usan el SDK de OpenAI, normalmente conviene validar primero tres cosas: chat normal, stream=True y tools/function calling. Cuando todo eso pase, ya puedes tratar las capacidades específicas del modelo.

Hay que tener cuidado con los parámetros de thinking. La documentación de compatibilidad indica que reasoning_effort de OpenAI se mapea a la configuración de thinking de Gemini; pero Gemini 3 y algunos modelos 2.5 no pueden desactivar thinking por completo. Mi recomendación es simple: en la primera versión no ajustes thinking; usa primero los valores predeterminados para establecer una línea base de calidad y coste, y después haz pruebas de carga específicas en tareas largas, agentes de código y flujos de razonamiento complejos.

Si quieres gestionar menos claves

La conexión directa oficial es adecuada para producción seria: facturación, límites y políticas de datos están claros. El problema es que los equipos a menudo no usan solo Gemini, sino también Claude, GPT, e incluso necesitan configurar claves distintas para herramientas diferentes. Una ruta más cómoda es usar onehop: cambia la base URL del SDK de OpenAI a https://api.onehop.ai/v1 y usa una misma entrada compatible con OpenAI/Anthropic para llamar a Claude/GPT/Gemini; las cuentas nuevas reciben $10, sin necesidad de vincular tarjeta, ideal para probar demos y herramientas internas.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url="https://api.onehop.ai/v1",
)

resp = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[{"role": "user", "content": "把这段日志总结成 5 条排障线索。"}],
)

print(resp.choices[0].message.content)

Aquí he puesto model deliberadamente en una variable de entorno: los nombres de modelo del gateway deben seguir lo que indique la consola, no los escribas fijos en el código. Si quieres complicarte menos con la facturación multi-proveedor y las capas de compatibilidad, puedes probar directamente: llamar a Claude y otros modelos en onehop, o reclamar primero el crédito: regístrate y recibe $10 de crédito de prueba.

Última comprobación antes de integrar

Antes de salir a producción, no te limites a comprobar si devuelve texto. Haz al menos cuatro verificaciones: primero, confirma que el modelo sigue disponible en la página actual de modelos de Google; segundo, revisa en la página de precios los costes de entrada, salida, Batch y Search grounding; tercero, registra de forma completa los errores 401, 429 y 5xx; cuarto, configura base_url, api_key y model en tiempo de ejecución, para no tener que publicar una versión solo para cambiar de modelo.

El punto clave de esta integración no es “cambiar de proveedor de modelos”, sino desacoplar la capa SDK del proveedor del modelo. Primero haz funcionar gemini-3.5-flash con la compatibilidad oficial de Google con OpenAI, y después decide si usar conexión directa, gateway o ambas. Así el cambio es pequeño y el rollback también es rápido.