API compatible con OpenAI: cambiar la Base URL

Una API compatible con OpenAI permite mantener la cabecera de autenticación, la estructura JSON y el flujo de streaming que ya entiende el cliente, aunque el tráfico pase por otra pasarela. A veces basta con cambiar la URL base y la clave, pero la compatibilidad sigue siendo un contrato de protocolo: no implica que todos los modelos admitan todos los endpoints ni todos los campos propios de cada proveedor.

Esta guía propone una migración prudente para aplicaciones, scripts y herramientas de IA que ya utilizan una API con el formato de OpenAI.

Qué cubre realmente la compatibilidad con OpenAI

Las partes más reutilizables del contrato son:

• autenticación mediante token Bearer en la cabecera Authorization;
• peticiones y respuestas JSON en endpoints versionados bajo /v1;
• endpoints habituales como /v1/models, /v1/chat/completions y /v1/responses;
• eventos enviados por el servidor (SSE) cuando el endpoint admite streaming;
• campos conocidos como model, messages, input, stream y las definiciones de herramientas previstas por cada protocolo.

Ser compatible no significa que un modelo pueda moverse libremente entre Chat Completions y Responses. Puede que solo esté publicado mediante uno de los dos protocolos verificados. Los campos de razonamiento, búsqueda o entrada multimodal propios de un proveedor también pueden requerir un passthrough sin transformar.

Consulta siempre el catálogo en vivo de Modelos y precios para confirmar el modelo, el grupo y el formato de API que vas a utilizar.

Preparar la migración

Antes de tocar el código de la aplicación:

1. Crea una clave exclusiva en Claves API; no reutilices una clave personal o de otra integración.
2. Elige un grupo principal que tenga acceso al modelo previsto.
3. Añade grupos de respaldo en un orden explícito y solo si admiten el mismo modelo y encajan en la política de coste y fiabilidad.
4. Anota el endpoint actual, el ID exacto del modelo, si usas streaming y qué herramientas intervienen. Así podrás comparar el comportamiento antes y después.

La URL base canónica de la API compatible con OpenAI de Modelflare es:

https://modelflare.dev/v1

La mayoría de SDK esperan que la URL termine en /v1 y añaden por su cuenta /chat/completions o /responses. Revisa la documentación del cliente antes de duplicar el sufijo del endpoint.

Comprobar primero la autenticación y el acceso al modelo

Guarda la clave en una variable de entorno, nunca en el código fuente:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Comprueba después que la clave puede listar los modelos disponibles:

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

Una respuesta correcta confirma el dominio, la conexión TLS y la validez de la clave. No demuestra todavía que todos los modelos acepten cualquier formato de petición; la siguiente prueba debe usar el endpoint real de la aplicación.

Enviar una petición con el protocolo previsto

Para un modelo anunciado como compatible con Chat Completions:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "user", "content": "Responde con el nombre del modelo activo."}
    ],
    "stream": false
  }'

Para un modelo de programación compatible con Responses:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Responde con el nombre del modelo activo.",
    "stream": false
  }'

Utiliza el ID exacto que aparece en el catálogo. Un error model_not_found suele indicar que la clave o el grupo no puede acceder al modelo; cambiar mayúsculas y minúsculas rara vez resuelve el problema.

Validar el streaming por separado

Que una petición sin streaming funcione no basta si la aplicación depende de respuestas incrementales. Repite la prueba con "stream": true, comprueba que los eventos llegan progresivamente y verifica que el cliente no acumula toda la respuesta antes de mostrarla.

Al investigar un streaming lento, separa:

• el tiempo de autenticación y selección de ruta;
• la espera hasta las cabeceras del proveedor;
• el tiempo hasta el primer texto, razonamiento o evento de herramienta útil;
• la velocidad de generación una vez iniciada la salida visible.

Los registros de uso de Modelflare conservan estas métricas por petición sin almacenar prompts, respuestas, cuerpos en bruto, claves API, correos electrónicos ni direcciones IP en texto claro.

Lista de comprobación para producción

• Guarda la clave en un gestor de secretos o una variable de entorno.
• Fija la URL base en https://modelflare.dev/v1.
• Elige un modelo que admita expresamente el endpoint seleccionado.
• Prueba por separado los modos con y sin streaming.
• Si los utilizas, prueba herramientas, salida estructurada, controles de razonamiento y entradas multimodales.
• Conserva los valores explícitos 0 y false cuando tengan significado.
• Configura el timeout para la carga real, no para un prompt mínimo de comprobación.
• Tras el cambio, revisa estado, latencia, tokens, grupo elegido y coste en los registros de uso.

Una vez verificado el límite del protocolo, el cliente suele poder conservar su ciclo de petición. Modelflare se ocupa detrás del mismo endpoint del acceso a modelos, la política de enrutamiento y la trazabilidad por petición.