Usar Gemini API con un cliente compatible con OpenAI: guía para Python y JavaScript

¿Qué aprenderás en esta guía?

Este tutorial aborda los pasos básicos de conexión para desarrolladores que quieren dirigir a Gemini API el código existente de un cliente compatible con OpenAI. Según la documentación de Google, se puede acceder a los modelos Gemini mediante bibliotecas cliente de Python y TypeScript/JavaScript, o a través de la API REST. Para quienes ya utilizan un cliente, la transición básica consiste en configurar la clave de API, la dirección de la solicitud y el nombre del modelo.

Los ejemplos utilizan solicitudes de completado de chat. Los equipos de arquitectura y diseño de interiores pueden considerar este formato básico de conexión como parte de una aplicación para trabajar con textos de proyectos, notas de diseño o consultas sobre presentaciones visuales. Sin embargo, esta guía solo muestra cómo conectarse a la API: no ofrece integración con un software de arquitectura concreto, garantías sobre la precisión de las respuestas del modelo ni un complemento específico para flujos de trabajo de diseño.

Requisitos: clave, cliente y modelo

Antes de empezar, se necesita una clave de Gemini API obtenida en Google AI Studio. La documentación de Google incluye ejemplos de las bibliotecas cliente de OpenAI para Python y JavaScript/TypeScript, además de solicitudes REST. Los ejemplos de código usan el nombre de modelo gemini-3.8-flash; si se prefiere otro modelo compatible, hay que modificar el campo correspondiente. La fuente no indica el número de versión de la biblioteca cliente ni información sobre precios.

Para quienes todavía no utilizan las bibliotecas cliente de OpenAI, Google recomienda llamar directamente a Gemini API. Por eso, si ya existe una aplicación, conviene comprobar primero si el cliente utilizado es adecuado para este método; si se va a crear una aplicación nueva, se debe valorar si la opción de acceso directo a la API satisface los requisitos. En los ejemplos siguientes, GEMINI_API_KEY es un marcador de posición; debe sustituirse por la clave real.

Envía tu primera solicitud paso a paso

1. Obtén una clave de API. Consigue una clave de Gemini API en Google AI Studio. La clave se utiliza para autenticar las solicitudes; los ejemplos contienen un marcador de posición, no una clave real.

2. Dirige el cliente al endpoint de Gemini. En el ejemplo de Python, el campo base_url indica la dirección de Gemini API; en el ejemplo de JavaScript, lo hace baseURL. Esta configuración envía las solicitudes del cliente a la dirección documentada de Gemini en lugar de a la dirección predeterminada.

3. Indica el nombre del modelo. El ejemplo utiliza gemini-3.8-flash. El nombre del modelo aparece como un campo independiente en la solicitud; si se usa otro modelo, el campo debe coincidir con el modelo elegido.

4. Ejecuta la primera solicitud de texto. El siguiente ejemplo de Python envía mensajes de sistema y de usuario en una solicitud de completado de chat e imprime el mensaje de la respuesta. El código procede del tutorial de Google, publicado con una licencia abierta.

from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{ "role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Explain to me how AI works"
}
]
)
print(response.choices[0].message)

El mensaje de usuario del ejemplo solicita una explicación general. En una aplicación orientada a la arquitectura, se puede sustituir por contenido relacionado con su propósito, como una solicitud para resumir una nota de proyecto. Se trata de una adaptación del uso del código; no significa que la fuente garantice resultados para una tarea de arquitectura concreta.

1. Configura la misma conexión básica con JavaScript. El ejemplo de JavaScript también define la clave de API, el endpoint, el modelo y los mensajes. Cuando se completa la solicitud, el mensaje devuelto se imprime en la consola.

import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
const response = await openai.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{ role: "system",
content: "You are a helpful assistant."
},
{
role: "user",
content: "Explain to me how AI works",
},
],
});
console.log(response.choices[0].message);

1. Envía una solicitud REST sin usar un cliente. El siguiente ejemplo de cURL realiza la misma operación básica mediante una solicitud HTTP. La clave se incluye en la cabecera Authorization; el modelo y el mensaje, en el cuerpo de la solicitud.

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "Explain to me how AI works"
}
]
}'

En los tres métodos, lo fundamental es dirigir la solicitud a Gemini API y usar la clave y el nombre del modelo correctos. Google resume la transición con clientes compatibles como un cambio de configuración en tres líneas; esto describe los ajustes básicos de conexión y no significa que todas las aplicaciones puedan funcionar sin ningún otro cambio en el código.

Errores frecuentes y puntos de verificación

• Dejar el endpoint predeterminado: si el cliente no está dirigido a Gemini API, la solicitud podría no enviarse a la dirección esperada. Comprueba la configuración base_url en Python, baseURL en JavaScript y la dirección REST.

• No sustituir el marcador de posición: GEMINI_API_KEY en los ejemplos no es una clave real. Sustitúyelo por el valor obtenido en Google AI Studio.

• Escribir mal el nombre del modelo: en los ejemplos, el campo del modelo aparece como gemini-3.8-flash. Comprueba que el valor de la solicitud coincida con el nombre del modelo elegido.

• Suponer que todas las funciones son compatibles de la misma manera: la guía también aborda temas como las respuestas en streaming, la llamada a funciones y la comprensión de imágenes, además del completado de chat. Sin embargo, cada función puede tener requisitos y configuraciones diferentes; el ejemplo básico de chat incluido aquí no cubre todos los detalles de configuración.

• Usar a la vez los ajustes de razonamiento: la documentación indica que reasoning_effort y los ajustes específicos de Gemini thinking_level o thinking_budget tienen funciones que se solapan y que no deben utilizarse al mismo tiempo. Por eso, al añadir opciones avanzadas de razonamiento, consulta también la documentación del modelo correspondiente.

En los flujos de trabajo de arquitectura, diseño de interiores y archviz, este enfoque puede servir como punto de partida para desarrolladores que quieran probar el acceso a la API basada en texto a través de un cliente existente. Se pueden probar ideas como añadir a una herramienta interna de la oficina solicitudes de texto sobre descripciones de proyectos o notas de diseño; sin embargo, la fuente no especifica compatibilidad con software concreto, flujos de trabajo de generación de imágenes ni requisitos de hardware local. Antes de pasar a producción, también hay que evaluar las licencias y los costos de la API, las condiciones del modelo utilizado y el flujo de datos de la aplicación; esta fuente no ofrece información sobre precios ni hardware.

Próximos pasos

Una vez que funcione la primera solicitud de texto, se pueden consultar las secciones de la misma documentación de Google sobre respuestas en streaming, llamada a funciones y comprensión de imágenes. No son funciones listas para usar que se añadan directamente al ejemplo básico de chat; cada una debe evaluarse según su propio formato de solicitud y sus requisitos. Si la aplicación todavía no utiliza la biblioteca cliente de OpenAI, también conviene considerar desde el principio la opción de llamar directamente a Gemini API.

Para los equipos de arquitectura, el método de prueba más seguro es crear primero un pequeño prototipo con textos de proyectos de ejemplo que no sean sensibles y tratar las respuestas como contenido auxiliar que debe revisarse, no como sustituto de las decisiones de diseño. Esta recomendación no implica que la API garantice un resultado de diseño concreto; es un enfoque práctico para que el equipo establezca su propio proceso de validación antes de incorporar la conexión técnica a un flujo de trabajo real.

Fuente y licencia

Este tutorial es una adaptación al turco basada en los ejemplos de Python, JavaScript y REST de la guía “OpenAI compatibility” de Gemini API de Google. La fuente está bajo la licencia CC BY 4.0.