Guía de API compatible con OpenAI: cambia la URL base

Conoce qué cubre la compatibilidad con OpenAI, cómo cambiar un cliente existente a Modelflare y qué límites verificar antes de enviar tráfico de producción.

Guía de API compatible con OpenAI: cambia la URL base

Una API compatible con OpenAI permite que un cliente existente conserve el encabezado de autenticación, la estructura de las solicitudes JSON y el patrón de streaming que ya conoce, mientras envía el tráfico a otro gateway. El cambio puede limitarse a reemplazar la URL base y la clave de API, pero la compatibilidad sigue siendo un contrato de protocolo: no garantiza que todos los modelos admitan todos los endpoints ni todos los campos específicos de cada proveedor.

Esta guía explica cómo migrar de forma segura aplicaciones, scripts y herramientas de IA que ya usan una API con el formato de OpenAI.

Qué cubre realmente la compatibilidad con OpenAI

Las partes más reutilizables del contrato son:

  • Autenticación con token Bearer mediante el encabezado Authorization.
  • Solicitudes y respuestas JSON en endpoints versionados bajo /v1.
  • Endpoints habituales como /v1/models, /v1/chat/completions y /v1/responses.
  • Server-Sent Events (SSE) para las solicitudes de streaming admitidas.
  • Campos de solicitud conocidos como model, messages, input, stream y las definiciones de herramientas, cuando el protocolo elegido los admite.

La compatibilidad no significa que un modelo pueda pasar libremente de Chat Completions a Responses. Es posible que un modelo solo esté disponible mediante un protocolo verificado. Además, los campos de razonamiento, búsqueda o entrada multimodal propios de un proveedor pueden requerir un reenvío directo sin cambios (pass-through) en lugar de una traducción en el gateway.

Toma el catálogo en vivo de Modelos y precios como fuente de verdad para el modelo, el grupo y el formato de API que piensas usar.

Prepara la migración

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

  1. Crea una clave dedicada en Claves de API en lugar de reutilizar una clave personal o de otra integración.
  2. Selecciona un grupo de modelos principal que tenga acceso al modelo previsto.
  3. Agrega grupos de respaldo ordenados solo si también admiten ese modelo y encajan en la misma política de costo y confiabilidad.
  4. Anota el endpoint actual, el ID del modelo, la configuración de streaming y el uso de herramientas para poder comparar el comportamiento antes y después.

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

https://modelflare.dev/v1

La mayoría de los SDK esperan que la URL base termine en /v1 y agregan por su cuenta /chat/completions o /responses. Revisa la documentación del cliente antes de agregar un segundo sufijo de endpoint.

Verifica primero la autenticación y el acceso al modelo

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

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Luego confirma que la clave puede listar sus modelos disponibles:

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

Una respuesta exitosa demuestra que el nombre de host, la conexión TLS y la clave son válidos. Todavía no demuestra que un formato de solicitud concreto sea válido para todos los modelos devueltos, así que la siguiente verificación debe usar el endpoint previsto.

Envía una solicitud con el protocolo previsto

Para un modelo de Chat Completions que aparece como compatible con ese formato:

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": "Reply with the active model name."}
    ],
    "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": "Reply with the active model name.",
    "stream": false
  }'

Usa el ID exacto del modelo que aparece en el catálogo en vivo. Un resultado model_not_found suele significar que la clave o el grupo seleccionado no puede acceder a ese modelo, no que cambiar mayúsculas y minúsculas vaya a corregir la solicitud.

Valida el streaming por separado

Que funcione una solicitud sin streaming no basta para una aplicación que depende del streaming. Repite la solicitud con "stream": true, confirma que los eventos llegan de forma incremental y asegúrate de que el cliente no almacene en búfer la respuesta completa antes de mostrarla.

Para diagnosticar un streaming lento, separa:

  • el tiempo dedicado a la autenticación y a la selección de la ruta;
  • el tiempo hasta los encabezados de respuesta del proveedor;
  • el tiempo hasta el primer contenido efectivo o el primer delta de herramienta;
  • la velocidad de generación una vez que comienza la salida visible.

Para esto, los registros de uso de Modelflare conservan metadatos de tiempos por solicitud sin almacenar prompts, texto de respuesta, cuerpos de solicitud sin procesar, claves de API, correos electrónicos ni direcciones IP en texto plano.

Lista de verificación para migrar a producción

  • Guarda la clave de API en un administrador de secretos o en una variable de entorno.
  • Fija la URL base en https://modelflare.dev/v1.
  • Usa un modelo que admita explícitamente el endpoint elegido.
  • Prueba por separado los modos con y sin streaming.
  • Prueba herramientas, salida estructurada, controles de razonamiento y entrada multimodal si la aplicación los usa.
  • Conserva los valores explícitos cero o false cuando tengan significado en la solicitud del cliente.
  • Configura los tiempos de espera del cliente según la carga de trabajo real, no según un prompt corto de verificación de estado.
  • Después del cambio, revisa en los registros de uso el estado, la latencia, el uso de tokens, el grupo seleccionado y el costo.

Una vez verificado el límite del protocolo, el cliente normalmente puede conservar su ciclo de solicitudes actual, mientras Modelflare aporta el acceso a modelos, la política de enrutamiento y la visibilidad por solicitud detrás del endpoint compatible.

Para conocer la capa operativa que hay detrás de ese endpoint, lee ¿Qué es un gateway de API de IA?. Si el cliente puede usar más de un formato de OpenAI, compara Responses API vs. Chat Completions antes de cambiar las rutas.