Usar el SDK de OpenAI para llamar a la API de Gemini: tutorial de migración cambiando solo base_url, API Key y el nombre del modelo

A fecha de 2026-06-14, la documentación de compatibilidad de Gemini con OpenAI de Google lo dice de forma muy directa: si ya tienes código con las bibliotecas de OpenAI en Python o TypeScript, puedes conectarlo a Gemini cambiando la API Key, el base_url y el nombre del modelo; el modelo de ejemplo en la documentación es gemini-3.5-flash, y la página de compatibilidad se actualizó por última vez el 2026-05-18 (Google AI for Developers). Esto no es “magia de una capa de adaptación”: simplemente envía las solicitudes del SDK de OpenAI al endpoint compatible que proporciona Google.

Primero instala el SDK, no cambies el paradigma de llamada

Si tu proyecto ya usa el SDK oficial de OpenAI para Python, basta con conservar chat.completions.create(). El repositorio del SDK de Python de OpenAI sigue siendo la fuente oficial del cliente (openai-python), y la interfaz compatible de Google acepta esa misma forma de llamada.

from openai import OpenAI

client = OpenAI(
    api_key="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": "You are a concise code reviewer."},
        {"role": "user", "content": "Review this Python function for edge cases."},
    ],
)

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

La API Key se crea desde Google AI Studio (AI Studio API key). Presta atención a la barra final: /v1beta/openai/, no el endpoint nativo normal de Gemini /v1beta/models/....

REST también puede llamarse con la forma de OpenAI

Para backend, depuración con curl o comprobaciones de salud de un gateway, no siempre hace falta un SDK. La ruta REST que muestra la documentación de compatibilidad de Google es /openai/chat/completions:

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {"role": "user", "content": "Give me a 5-point migration checklist."}
    ]
  }'

Durante la migración, ejecuta primero ese comando. Permite separar cuatro tipos de problemas —Key, nombre de modelo, salida de red y permisos de facturación— y ahorra tiempo frente a depurar directamente dentro del servicio de negocio.

Cómo se mapea reasoning_effort

El control de thinking de Gemini y el reasoning_effort de OpenAI se solapan, y Google indica explícitamente que no deben enviarse ambos a la vez. La capa compatible mapea los parámetros de estilo OpenAI a los parámetros de thinking de Gemini (Google OpenAI compatibility).

reasoning_effort de OpenAI	thinking_level de Gemini 3	thinking_budget de Gemini 2.5
minimal	minimal o low	1024
low	low	1024
medium	medium	8192
high	high	24576

Si quieres una migración conservadora, al principio no envíes reasoning_effort y deja que el modelo use el valor predeterminado. Si quieres controlar costes, añade low a las tareas con contexto largo y luego observa la calidad de salida y la factura de tokens.

No mires solo el nombre del modelo al comparar precios

La página oficial de precios de Google enumera con claridad los precios estándar de Gemini 2.5 Pro y Flash, en unidades por cada millón de tokens; el precio de salida incluye los thinking tokens (Gemini API pricing).

Modelo	Precio de entrada	Precio de salida
gemini-2.5-pro, prompt ≤ 200k	$1.25	$10.00
gemini-2.5-pro, prompt > 200k	$2.50	$15.00
gemini-2.5-flash, entrada de texto/imagen/vídeo	$0.30	$2.50
gemini-2.5-flash, entrada de audio	$1.00	$2.50

Mi recomendación: para chat, clasificación y tareas ligeras de código, empieza con Flash; para razonamiento complejo, síntesis de documentos largos y refactorización de código, cambia a Pro. El umbral de 200k del prompt en Pro afecta directamente al precio de entrada y de salida, así que no metas sin más logs, fragmentos de recuperación y system prompts repetidos.

Lista de migración

1. Cambia OPENAI_API_KEY por GEMINI_API_KEY, generado desde AI Studio.
2. Cambia base_url a https://generativelanguage.googleapis.com/v1beta/openai/.
3. Cambia el nombre del modelo por un modelo Gemini compatible, por ejemplo gemini-3.5-flash.
4. Primero verifica con REST curl y luego vuelve a conectar el SDK.
5. Pausa los ajustes personalizados de reasoning_effort y añádelos después de confirmar la calidad.
6. Registra el coste de tokens de entrada, salida y thinking, especialmente el umbral de 200k de Pro.

Si también necesitas conectar Claude/GPT

Si solo vas a conectar Gemini, lo más limpio es usar el endpoint compatible oficial de Google. Pero en cuanto tu proyecto necesite Claude, GPT y Gemini al mismo tiempo, manejar varias Keys, varias facturas y varios SDK se vuelve molesto. La ruta más cómoda es onehop: compatible con OpenAI/Anthropic; cambiando el base_url a https://api.onehop.ai/v1, puedes llamar a Claude/GPT/Gemini con el mismo SDK de OpenAI. Su propuesta principal es un precio inferior al oficial, $10 de regalo para cuentas nuevas y sin necesidad de vincular tarjeta.

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Refactor this API handler."}],
)
print(resp.choices[0].message.content)

Si ahora solo quieres poner en marcha el acceso multimodelo, puedes probarlo 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. La clave de la migración no es cambiar un montón de capas de abstracción, sino reducir las variables a tres cosas: endpoint, key y model.