API compatible con OpenAI o Anthropic: ¿cuál elegir?

Qué significa realmente que una API sea compatible

Una API compatible acepta una estructura de solicitud conocida y devuelve una respuesta que un SDK o cliente existente puede interpretar. En una integración habitual, el desarrollador cambia la Base URL, la API Key y el Model ID, pero conserva la mayor parte del código de la aplicación.

El término tiene un límite claro. Un proveedor puede admitir generación básica de texto sin ofrecer un parámetro concreto, una herramienta alojada, audio, un endpoint de imágenes o la misma semántica de errores. Incluso dos endpoints con un campo model pueden diferir en cómo enumeran los modelos y conceden acceso.

¿Quieres probar el protocolo elegido con una solicitud real? Puedes crear tu propia cuenta de BetterToken y una API Key, abrir la guía rápida y enviar una prueba mínima. BetterToken ofrece interfaces separadas compatibles con OpenAI y Anthropic; el protocolo, la Base URL, el tipo de API Key y el Model ID vigente deben coincidir con la referencia actual de la API.

Diferencias en solicitudes y autenticación

En un flujo compatible con OpenAI, el cliente suele crear messages para Chat Completions o input para Responses. La autenticación utiliza habitualmente un token Bearer:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anthropic Messages utiliza su propia estructura de mensajes, un campo system independiente, un límite de salida obligatorio y una versión del protocolo. La API oficial de Anthropic utiliza cabeceras como x-api-key y anthropic-version:

x-api-key: YOUR_API_KEY
anthropic-version: CURRENT_SUPPORTED_VERSION
Content-Type: application/json

Una pasarela compatible puede aceptar otro esquema de autenticación. Obtén las cabeceras de la documentación del endpoint al que llamas. Un ejemplo de la API oficial explica el formato del protocolo, pero no sustituye la guía de integración del proveedor.

La instrucción del sistema también ocupa lugares distintos en cada contrato. Un protocolo puede incluirla entre los mensajes y otro enviarla en un campo separado. Una conversión mecánica puede alterar el orden del contexto, un prefijo de caché o el comportamiento del cliente.

Chat Completions, Responses y Messages son contratos distintos

La expresión compatible con OpenAI no indica qué interfaz está implementada. Antes de una migración, registra el contrato exacto:

• Chat Completions: un array messages, una respuesta bajo choices y fragmentos transmitidos bajo delta.
• Responses API: elementos de entrada, elementos de salida tipados y eventos separados del ciclo de vida de la respuesta.
• Anthropic Messages: messages, un campo system independiente, bloques de contenido y sus propios eventos de streaming.

Si una biblioteca espera Responses, no basta con un endpoint que solo implemente /chat/completions. Si Claude Code espera Anthropic Messages, un endpoint compatible con OpenAI no funciona sin un adaptador. Sustituir la Base URL solo es suficiente cuando el cliente y el servidor implementan el mismo contrato.

Diferencias en streaming y finalización

Las tres interfaces pueden transmitir datos, pero los nombres y el orden de sus eventos son distintos.

Responses API envía Server-Sent Events tipados para la creación de la respuesta, los fragmentos de texto y los estados terminales. El cliente debe esperar un evento de finalización o gestionar una respuesta fallida o incompleta.

Anthropic Messages envía message_start, eventos de bloques de contenido, message_delta y message_stop. Un error puede llegar dentro de un stream ya abierto después de que la respuesta HTTP inicial haya sido correcta.

Con Chat Completions, el cliente suele acumular choices[0].delta y detectar el final según el contrato de ese endpoint. El código que solo espera un marcador no puede copiarse en Responses o Messages sin comprobarlo.

Un controlador mínimo mantiene cuatro estados:

created -> receiving -> completed
                   \-> failed
                   \-> disconnected

disconnected no equivale a completed. Si la conexión termina después de una respuesta parcial, conserva los eventos recibidos y decide si es seguro reintentar.

Uso de herramientas y salida estructurada

Nombres de campos parecidos, como tools y tool_calls, pueden sugerir más compatibilidad de la que existe. Prueba al menos:

• JSON Schema y las restricciones de tipos admitidos;
• llamadas paralelas a herramientas;
• cómo se devuelve al modelo el resultado de una herramienta;
• el ensamblado de argumentos transmitidos;
• el comportamiento ante JSON no válido;
• la salida estructurada estricta y los rechazos del esquema.

Un adaptador debe conservar el significado de la llamada, no limitarse a cambiar nombres de campos. Esto es especialmente importante con herramientas que tienen efectos secundarios: repetir la misma llamada puede enviar un segundo mensaje, crear otro registro o ejecutar dos veces una operación.

No asignes errores solo por el estado HTTP

401, 403, 404, 429 y 5xx ofrecen una primera clasificación útil, pero los cuerpos y las cabeceras de error varían entre proveedores. Conserva:

• el estado HTTP;
• el tipo y el código de error del proveedor;
• un mensaje breve sin secretos;
• el request ID;
• las cabeceras relacionadas con reintentos;
• el endpoint, el protocolo y el Model ID.

No registres la API Key, el prompt completo ni una respuesta sensible. Si una pasarela normaliza los errores, conserva el código original del proveedor en un campo interno seguro. De lo contrario, model not found, la falta de acceso y un endpoint incompatible pueden convertirse en el mismo 400 poco útil.

Cómo elegir el protocolo

Una herramienta de IA lista para usar

Lee primero la documentación de la herramienta. Si solicita una OpenAI Base URL y utiliza Chat Completions o Responses, elige el endpoint compatible con OpenAI correspondiente. Si lee ANTHROPIC_BASE_URL y espera Messages, utiliza un endpoint compatible con Anthropic.

No elijas el protocolo por el nombre del modelo. Un modelo puede estar disponible mediante una pasarela aunque el cliente siga necesitando un formato de solicitud específico.

Tu propia aplicación

La decisión depende del SDK y de las funciones que ya utilizas. Para una aplicación nueva, enumera las capacidades necesarias: streaming, herramientas, salida estructurada, visión, uso de tokens, operaciones por lotes u otros endpoints. Verifica cada una en la documentación oficial del proveedor.

Una migración de proveedor

Calcula la superficie del contrato, no el número de líneas modificadas. Un chat básico puede requerir solo tres valores de configuración nuevos. Una aplicación de agentes con herramientas, historial largo, caché y streaming suele necesitar un adaptador y pruebas de integración.

Prueba antes de trasladar el tráfico de producción

1. Registra el SDK, el endpoint y la versión de la API.
2. Copia el Model ID exacto del catálogo actual.
3. Envía una solicitud breve sin herramientas ni streaming.
4. Transmite una respuesta básica hasta su evento terminal.
5. Ejecuta una llamada segura a una herramienta sin efectos externos.
6. Provoca un error controlado con un Model ID deliberadamente no válido.
7. Compara usage, el estado y el request ID con el Dashboard.
8. Prueba la gestión del timeout y un reintento limitado.

Solo entonces traslada el tráfico real. Con BetterToken, empieza por la referencia de la API, elige un protocolo y confirma una solicitud mínima antes de habilitar herramientas de agentes.

Preguntas frecuentes

¿Una API compatible con OpenAI reproduce por completo la API de OpenAI?

No. El término indica compatibilidad con una interfaz concreta. Los modelos, parámetros, herramientas, streaming, errores y endpoints adicionales siguen necesitando una verificación independiente.

¿Puedo llamar a un endpoint compatible con Anthropic mediante el SDK de OpenAI?

No directamente cuando el SDK envía el contrato de OpenAI. Utiliza un cliente que admita Anthropic Messages o un adaptador que convierta correctamente los mensajes, el streaming y el uso de herramientas.

¿Basta con sustituir la Base URL?

A veces, para una solicitud breve de texto en un cliente ya compatible. En una migración de producción, verifica de todos modos el Model ID, la autenticación, el streaming, las herramientas, los errores y el uso.

¿Qué protocolo necesita Claude Code?

Claude Code utiliza normalmente una interfaz compatible con Anthropic. Obtén las variables exactas, la Base URL y la configuración del modelo de la guía actual de BetterToken.