API compatibles con OpenAI: qué probar antes de llamarlas interoperables
Una prueba práctica de compatibilidad: forma de la petición, semántica de respuesta, errores, límites y las funciones que tu aplicación usa de verdad.
La compatibilidad describe una interfaz, no todos los comportamientos
La referencia oficial de OpenAI documenta que POST /chat/completions acepta mensajes de conversación y devuelve una finalización con choices, y define motivos de finalización como stop, length, content_filter y tool_calls. Esos campos dan una base concreta para una prueba de compatibilidad.
Un endpoint de terceros puede aceptar la misma ruta y los campos principales sin coincidir en cada parámetro, evento, error, capacidad o regla operativa. Trata la etiqueta «compatible con OpenAI» como una hipótesis que se contrasta con el contrato de tu aplicación, no como prueba de un servicio intercambiable.
Ejercita el contrato
Empieza por el rechazo de autenticación y el descubrimiento de modelos, y envía una finalización mínima sin streaming. Valida el código de estado, la ubicación del contenido, el valor del modelo, los campos de uso que consumes y el motivo de finalización. Repite con streaming solo si lo usas, comprobando el cierre de eventos y el manejo de contenido parcial.
Después prueba lo que rompería una migración: instrucciones de sistema, llamadas a herramientas, salida JSON o estructurada, entrada de imágenes, comportamiento de stop, límites de tokens y cancelación. El área Models de FreeToken.link identifica candidatos, y el Playground ofrece un espacio acotado para probar la petición antes de tocar código de producción.
Prueba también los fallos
Ejecuta casos negativos: credencial ausente, modelo inválido, entrada malformada y una petición limitada a propósito. Tu adaptador necesita códigos de estado predecibles y errores interpretables; una demo solo de éxito no muestra si los reintentos, los fallbacks o los mensajes al usuario funcionarán.
Las reglas operativas pueden diferir aunque el JSON parezca familiar. Groq documenta varias dimensiones de límite a nivel de organización, respuestas HTTP 429 y cabeceras de límite. Una revisión de compatibilidad debe capturar el alcance actual del límite y las señales de reintento del proveedor, no heredar supuestos de otra API.
Decide con una matriz
Para cada capacidad registra uno de tres resultados: pasa sin cambios, funciona con adaptador o no está soportado. Incluye el fixture de la petición y una muestra de respuesta censurada para poder repetir la prueba cuando cambien proveedor, SDK o modelo.
Llama «interoperable» a un endpoint solo si todo lo que la aplicación necesita pasa sin adaptación. Si no, describe la verdad más estrecha —por ejemplo, compatible con chat-completion para texto sin streaming— y pon la ruta en la Watchlist de FreeToken.link para futuras verificaciones.
Preguntas frecuentes
- P. ¿Una API compatible con OpenAI es lo mismo que la API de OpenAI? / R. No. Puede implementar una interfaz similar, pero eso no prueba funciones, respuestas, límites ni comportamiento idénticos.
- P. ¿Cuál es la prueba de compatibilidad mínima útil? / R. Verificar rechazo de autenticación, descubrimiento de modelos, una finalización mínima, los campos de respuesta que consumes y al menos un caso de fallo.
- P. ¿Cuándo es aceptable un adaptador? / R. Cuando la diferencia es explícita, probada y aislada. Documenta el adaptador en lugar de presentar el endpoint como totalmente intercambiable.
Divulgación de publicación
El primer borrador se generó con el wrapper local basketikun/chatgpt2api a partir de un paquete fijo de hechos de fuentes oficiales. Ese wrapper usa una ruta de sesión web de ChatGPT y no es la API oficial de OpenAI. Un editor humano comprobó cada afirmación retenida contra las referencias enlazadas y añadió la matriz de pruebas de éxito, fallo y funciones antes de publicar.