Cómo funciona el gateway

La idea de Half Off Dev es que sigas usando el código que ya tienes. Claude, GPT y Gemini se sirven cada uno en el formato de su propio fabricante, desde un único host y a mitad del precio de lista. Tu SDK envía exactamente el mismo JSON que enviaría al fabricante; solo cambian la URL base y la clave.

No hay ninguna capa de traducción en medio. Una petición con formato de Anthropic va a un canal que habla Anthropic, una con formato de OpenAI a uno que habla OpenAI, y así sucesivamente. Salvo por dos ajustes muy concretos, el cuerpo llega tal como lo escribiste, de modo que opciones como thinking, cache_control, tools o generationConfig funcionan tal y como las describe la referencia de cada fabricante.

Endpoints de un vistazo#

Pásale a tu SDK la URL base de esta tabla y deja que él construya la ruta.

Lo que no aparece en esta lista no está soportado; consulta lo que no puedes llamar.

Cómo enviar tu clave#

Cada endpoint busca la clave en cuatro sitios, así que funciona con lo que cada SDK haga por defecto:

Los dos endpoints del catálogo son públicos y no necesitan clave. Cómo crear, limitar y rotar claves se explica en Autenticación.

Formato nativo de cada familia#

Cada familia se diseñó alrededor de una API concreta. Si la llamas ahí, tienes todas las funciones que publica el fabricante.

Si usas un formato que no es el nativo, el canal convierte la petición para el modelo y por el camino pueden perderse o rechazarse opciones propias del fabricante. cache_control y thinking de Anthropic, reasoning_effort de OpenAI y thinkingConfig de Gemini solo están garantizados en el formato de origen del modelo.

Los formatos que acepta un modelo dependen de los canales que lo sirven, así que la lista puede cambiar. El catálogo de modelos muestra los formatos actuales de cada uno. Si ningún canal acepta tu formato, recibes 404 con un mensaje como Model 'gpt-6.1-sol' is not served in gemini format in any group.

Ids de modelo#

Los ids canónicos son los de GET /v1/models, por ejemplo claude-opus-5.5, gpt-6.1-sol o gemini-3-flash. Las herramientas que escriben los ids a su manera también llegan al modelo correcto, porque el gateway normaliza lo que recibe:

La normalización pasa el id a minúsculas, quita un prefijo vendor/ o models/, trata . y - como el mismo carácter y elimina una fecha final (-20251001), -preview o -latest. La facturación, los registros y las listas de modelos permitidos de cada clave usan siempre el id canónico.

Un id que no corresponde a ningún modelo devuelve 404: Model '<id>' is not available. See GET /v1/models.

El recorrido de una petición#

1. Clave. Una clave inactiva o caducada recibe 401.
2. Modelo. El id se normaliza como se explica arriba y se compara con la lista de modelos permitidos de la clave; un modelo fuera de ella recibe 403.
3. Saldo. Un saldo igual o inferior a cero, o una clave que agotó su límite de gasto, recibe 402.
4. Límites de la clave. Se aplican los topes de peticiones por minuto y de concurrencia de la clave (429). Detalles en Límites y conmutación por error.
5. Elección de canal. Una conversación ya en marcha vuelve al canal que guarda su caché de prompt; una nueva va al canal más sano de su grupo de canales. Consulta Caché de prompts.
6. Llamada al modelo. Si un canal falla antes de producir salida, se sustituye por otro, con un máximo de tres intentos. Los streams se retienen hasta el primer token para que el cambio no se note. Consulta Streaming.
7. Medición. Los recuentos de tokens de la respuesta fijan el cargo, a mitad del precio de lista, que se descuenta de tu saldo en segundos. Consulta Precios.

Qué cambia el gateway#

Solo se hacen dos cambios en el cuerpo:

1. model. El gateway escribe el id tal como lo espera el canal que atiende la petición. Por eso el campo model de la respuesta puede venir con la grafía del fabricante, por ejemplo claude-opus-5-5.
2. Uso en los streams de OpenAI. Toda petición de Chat Completions en streaming recibe stream_options.include_usage: true para poder facturarla. Tu stream termina, por tanto, con un fragmento extra cuyo array choices está vacío y que trae usage. Asegúrate de que tu bucle tolere un choices vacío.

Las cabeceras que envías se descartan, salvo tres que se reenvían: anthropic-version, anthropic-beta y openai-beta. Si falta anthropic-version, se completa con 2023-06-01. En las rutas de Gemini, los parámetros de consulta como alt=sse pasan; key se elimina.

El cuerpo de la respuesta se devuelve byte a byte. Se conservan content-type y cache-control, y el gateway añade sus propias cabeceras; los ids de petición y las cabeceras de límite de cada fabricante no se reenvían.

Si el modelo rechaza la petición por no ser válida (400, 404, 413, 422), recibes ese estado y el motivo en el formato de error de la API que llamaste. Cualquier otro fallo se reintenta primero en otro canal. Más en Límites y conmutación por error y Errores.

Cabeceras en cada respuesta#

Las tres primeras figuran en access-control-expose-headers, así que el JavaScript del lado del cliente puede leerlas.

Lo que no puedes llamar#

Los endpoints de la tabla de arriba son todo lo que hay para modelos. En concreto, no se sirven:

• OpenAI: respuestas almacenadas (/v1/responses/{id}), Completions heredado, embeddings, audio, archivos y lotes. La Responses API en sí solo funciona con modelos GPT.
• Anthropic: Message Batches, Files y la consulta de un modelo concreto por id.
• Gemini: cachedContents (caché de contexto explícita), subida de archivos, embedContent y la Live API.

Para configurar un cliente concreto, consulta Integraciones.