«Compatible con OpenAI» se ha convertido casi en un argumento de venta universal para los servicios de modelos: cambias una Base URL y el mismo SDK de OpenAI llama a los modelos de otro proveedor. Suena a modificar una línea de configuración, pero en una migración real aparecen 404, errores de parámetros, cortes en el streaming y formatos de llamada a herramientas distintos. La razón es sencilla: la compatibilidad suele cubrir las interfaces más usadas, no todas las capacidades.

Este artículo explica los límites de la compatibilidad, cómo escribir la Base URL, la configuración de los SDK, las diferencias de parámetros y los pasos de migración, para que puedas cambiar de modelo o de proveedor sin tocar el código de negocio.

Nota: OpenAI es una marca de su titular y este artículo no guarda relación de afiliación con los fabricantes mencionados. El alcance de compatibilidad de cada proveedor figura en su documentación; los modelos y precios, en la página de precios de modelos.

1. ¿Qué capa cubre exactamente la «compatibilidad»?

Una API compatible con OpenAI suele mantener las mismas rutas HTTP, campos del cuerpo de la petición y estructura de respuesta. El grado de compatibilidad varía mucho según la interfaz:

Interfaz Uso Compatibilidad habitual
/v1/chat/completions Conversación y generación de texto La más extendida; admite la mayoría de campos básicos
/v1/embeddings Vectores de texto Frecuente, pero hay que comprobar la dimensión del vector
/v1/models Lista de modelos Algunos solo devuelven parte de los modelos o nada
/v1/images/generations Generación de imágenes Depende del proveedor
/v1/audio/transcriptions Transcripción de voz Depende del proveedor
/v1/responses Interfaz Responses, más reciente Soporte desigual; confírmalo antes de migrar

Por tanto, «compatible» no significa «totalmente equivalente». El mínimo para aceptar un servicio es que /v1/chat/completions responda correctamente; si el negocio depende de llamadas a herramientas, salida estructurada o multimodalidad, hay que validarlo punto por punto y no quedarse con la página promocional.

2. Cómo escribir correctamente la Base URL

El SDK añade automáticamente rutas como /chat/completions después de la Base URL. Por eso esta suele escribirse hasta /v1, no hasta el endpoint concreto. Formas habituales:

Forma ¿Frecuente? Explicación
https://api.example.com/v1 La más común El SDK añade /chat/completions
https://api.example.com/openai/v1 Algunas pasarelas El prefijo de ruta lo define el proveedor
https://api.example.com/v1/chat/completions Incorrecta Genera una ruta duplicada y devuelve 404
https://api.example.com Según implementación Algunos servicios añaden /v1 solos; no lo des por hecho

Tres detalles:

  1. No añadas varias barras al final; evitarás //chat/completions.
  2. Distingue la «dirección de la consola» de la «dirección de la API»; la primera normalmente no sirve como Base URL.
  3. Si el ejemplo del proveedor funciona tal cual, cópialo; no reescribas la ruta por tu cuenta.

3. Conexión con SDK: tres formas equivalentes

Con el SDK oficial de Python:

from openai import OpenAI

client = OpenAI(
    api_key="sk-tu-clave",
    base_url="https://api.example.com/v1",
)

resp = client.chat.completions.create(
    model="tu-nombre-de-modelo",
    messages=[{"role": "user", "content": "Responde solo OK"}],
)
print(resp.choices[0].message.content)

Con el SDK de Node:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.example.com/v1",
});

const resp = await client.chat.completions.create({
  model: "tu-nombre-de-modelo",
  messages: [{ role: "user", content: "Responde solo OK" }],
});
console.log(resp.choices[0].message.content);

También puedes usar variables de entorno para no escribir la dirección y la clave en el código:

export OPENAI_API_KEY="sk-tu-clave"
export OPENAI_BASE_URL="https://api.example.com/v1"

El SDK oficial suele leer OPENAI_BASE_URL, pero el nombre puede variar ligeramente entre lenguajes y versiones; consulta la documentación del SDK que uses. En producción, guarda la Base URL en un centro de configuración y la clave en un gestor de secretos.

4. Compatibilidad de parámetros: dónde están las trampas

Que funcione el chat básico no significa que funcionen todos los parámetros. Antes de migrar, revisa:

Parámetro Diferencia habitual
model Debe ser el nombre que ofrece el proveedor, no el nombre oficial del modelo
max_tokens Algunos modelos nuevos usan max_completion_tokens; el campo antiguo puede rechazarse o ignorarse
temperature / top_p Los modelos de razonamiento pueden fijarlo o ignorarlo
stream Casi todos lo admiten, pero la estructura de eventos puede no ser idéntica
tools / tool_choice El soporte varía mucho; puede que parallel_tool_calls no esté disponible
response_format json_object es habitual; json_schema no siempre
seed / logprobs / n Muchos servicios compatibles no los admiten; enviarlos puede dar error
reasoning_effort Solo algunos modelos de razonamiento; el significado de los valores también puede cambiar

Una práctica segura: mantén un «conjunto mínimo de parámetros» con solo los campos que el negocio necesita de verdad; desactiva por configuración los que no se admitan en lugar de codificarlos en la petición.

5. Pasos para migrar desde la API oficial

Sigue este orden para acotar el riesgo:

  1. Inventaría los puntos de llamada: enumera todos los servicios, scripts y tareas programadas que usan el SDK de OpenAI.
  2. Anota las capacidades de las que dependes: dónde se usan chat, streaming, llamadas a herramientas, salida estructurada, Embeddings y multimodalidad.
  3. Crea una clave nueva con presupuesto: asigna una clave exclusiva a la migración, con límite de gasto y alertas.
  4. Cambia la Base URL: hazlo por variable de entorno o configuración, sin tocar el código de negocio.
  5. Haz una prueba de humo: envía una petición con curl y otra con el SDK para confirmar dirección, clave y nombre del modelo.
  6. Ejecuta muestras de regresión: prepara 30–100 peticiones reales y compara calidad, latencia, códigos de error y consumo de tokens.
  7. Despliega de forma gradual: empieza por un proceso no crítico, observa una semana y amplía; mantén una vuelta atrás inmediata.

Migrar no es «cambiar la dirección y listo». Al cambiar de modelo pueden variar el estilo de salida, la longitud de contexto y la tasa de éxito de las herramientas; un conjunto de evaluación es más fiable que la sensación.

6. Errores habituales y diagnóstico

Error Causa habitual Solución
401 Unauthorized Clave incorrecta, caducada o ausente Revisa la cabecera y si la clave tiene caracteres de más
403 Forbidden La clave no tiene permiso para ese modelo o se activó el control de riesgo Confirma permisos del modelo y estado de la cuenta
404 Not Found Ruta de Base URL incorrecta Quita /chat/completions y confirma si hace falta /v1
400 Bad Request Parámetro no admitido o formato incorrecto Descarta parámetros uno a uno y vuelve al cuerpo mínimo
429 Too Many Requests Concurrencia o cuota excedida Reduce la concurrencia y usa reintentos con retroceso exponencial
500 / 502 / 503 Fallo del upstream o de la pasarela Reintenta y registra el ID de petición; si persiste, cambia al proveedor de respaldo
Corte del streaming Búfer del proxy, timeout o red inestable Desactiva el búfer del proxy y ajusta timeout y latido

Al diagnosticar, conserva siempre la petición original: URL, cabeceras (con la clave oculta), cuerpo, código y cuerpo de la respuesta. Con un simple «la llamada falla» es muy difícil localizar el problema.

7. Diferencias reales en streaming, herramientas y multimodalidad

  • Streaming: las interfaces compatibles suelen devolver Server-Sent Events, que empiezan por data: y terminan con [DONE]. Pero los campos incrementales de las herramientas y las estadísticas de uso dentro del flujo no son iguales en todos los proveedores. Antes de activar el conteo de uso, confirma si el proveedor lo admite.
  • Llamadas a herramientas: los nombres de función y la estructura JSON de parámetros son parecidos, pero pueden faltar llamadas paralelas, modo estricto o campos de razonamiento. Para agentes complejos, prueba primero una cadena de herramientas real.
  • Salida estructurada: json_object suele estar disponible; las restricciones con JSON Schema no siempre. El sistema posterior debe seguir analizando y validando el JSON; no supongas que el modelo siempre devolverá JSON válido.
  • Multimodalidad: hay diferencias notables entre enviar imágenes por URL o en Base64 y entre los formatos y tamaños admitidos. Valida tamaño y formato antes de subir.
  • API Responses: la cobertura de esta interfaz más reciente en servicios compatibles es menor que la de Chat Completions; si tu aplicación depende de ella, confírmalo por separado antes de migrar.

8. Coste y facturación

La facturación de una API compatible también puede cambiar:

  1. Confirma si se cobra por separado la entrada y la salida o de forma conjunta.
  2. Comprueba si los aciertos de caché y los tokens de razonamiento se facturan aparte.
  3. Las respuestas en streaming no siempre devuelven usage; si hace falta, estima los tokens localmente.
  4. Separa las claves por proyecto o línea de negocio para poder conciliar a fin de mes.
  5. Configura presupuestos diarios y alertas para evitar que los reintentos en bucle disparen el gasto.

El precio unitario exacto figura en precios de modelos. No calcules el coste total a partir del precio de un solo modelo: el modelo, la longitud de contexto y las reglas de facturación cambian.

Preguntas frecuentes

¿Una API compatible con OpenAI es lo mismo que la API oficial de OpenAI?

No. Compatible significa que el formato de la interfaz se parece; el proveedor, los modelos, la facturación y las condiciones de datos pueden ser distintos. Que la forma de llamar sea igual no implica las mismas capacidades ni el mismo cumplimiento.

¿La Base URL debe incluir /v1?

Depende de la documentación del proveedor. La mayoría pide llegar hasta /v1 y deja que el SDK añada /chat/completions; algunas pasarelas tienen su propio prefijo. La prueba es que Base URL + /chat/completions lleve al endpoint correcto.

¿Por qué funciona con curl pero el SDK devuelve 404?

La causa habitual es que el SDK añade la ruta por su cuenta y la Base URL ya incluía /chat/completions; también puede ser que una variable de entorno esté sobrescribiendo la configuración del código. Imprime la dirección real de la petición y compárala.

¿Las interfaces compatibles admiten llamadas a herramientas y salida estructurada?

Algunas sí, en función del proveedor y del modelo. Antes de migrar, prueba una cadena de herramientas real y un JSON Schema; no te limites a una conversación normal.

¿Qué hago si la calidad baja después de migrar?

Confirma primero que el nombre del modelo, la temperatura y el prompt no han cambiado y compara con el mismo lote de muestras. Si hace falta, ajusta el prompt, cambia de modelo o mantén dos proveedores con reparto de tráfico; no decidas solo por una o dos impresiones subjetivas.

Siguiente paso

El valor de una API compatible con OpenAI es reducir el coste de cambio, pero lo compatible es el protocolo, no la capacidad. Empieza validando el cuerpo mínimo de la petición y activa después streaming, herramientas y salida estructurada uno por uno. Si necesitas una entrada compatible con OpenAI unificada, gestión de claves y estadísticas de uso, puedes registrarte en la pasarela de IA de ZSQH; los modelos y precios figuran en precios de modelos.

Lecturas relacionadas: