--- title: "AI Gateway" description: "Una sola dirección, un solo token y un solo saldo para modelos de OpenAI, Anthropic, Google, xAI y DeepSeek: SDK de OpenAI y de Anthropic, Vercel AI SDK, Claude Code y tus propias claves del proveedor." category: "Despliegue" language: es source: https://cubepath.com/es/docs/products/despliegue/ai-gateway-es updated: 2026-11-10 --- # AI Gateway El AI Gateway de CubePath te da una sola dirección, un solo token y un solo saldo para modelos de **OpenAI, Anthropic, Google, xAI y DeepSeek**. Habla la API de OpenAI y la API nativa de Anthropic, así que los SDK y las herramientas que ya usas funcionan cambiando una URL. Abre la página **AI Gateway** en [my.cubepath.com](https://my.cubepath.com). URL base: `https://ai-gateway.cubepath.com` ## Primeros pasos ```steps ### Crea un token de API En la página del AI Gateway, pulsa **Create API Token**. Tiene que ser un token de API: los tokens OAuth no se aceptan. Un token puede hacer lo que permite el rol del miembro que lo creó: propietarios, administradores y miembros pueden usar el gateway, los de solo lectura solo pueden ver los modelos y el rol de facturación no puede usarlo. ### Añade fondos Pulsa **Add AI Funds** para recargar tu saldo. Pagas por uso, por token, al terminar cada petición. ### Apunta tu SDK o herramienta al gateway Pon la URL base `https://ai-gateway.cubepath.com` y usa tu token de API de CubePath como clave. ``` Los modelos se llaman `proveedor/modelo`, por ejemplo `openai/gpt-4o`, `google/gemini-2.5-pro` o `anthropic/claude-sonnet-5`. Lista los modelos con sus precios: ```bash curl https://ai-gateway.cubepath.com/models -H "Authorization: Bearer $CUBEPATH_TOKEN" ``` ## Modelos El catálogo **Models** muestra qué hay disponible y cuánto cuesta: - **Precio por 1M de tokens**, de entrada y de salida por separado. La salida suele costar varias veces más que la entrada. `/models` también da los precios de lectura y escritura de caché cuando el proveedor los tiene. - **Ventana de contexto**: cuánto puedes enviar en una petición. - **Salida máxima**: el techo de una sola respuesta. - **Capacidades**: streaming, visión, uso de herramientas. ![Catálogo de modelos con precio por token, capacidades y contexto](https://cdn.cubepath.com/img/docs/products/946d16df-ce05-40b1-99a6-d879b80d7529.png) > Consejo: Cambia de proveedor cambiando solo el nombre del modelo. Tu token, tu dirección y tu facturación siguen igual, así que puedes probar un modelo más barato frente al actual con tráfico real. ## SDK de OpenAI La URL base funciona con o sin `/v1`. ```python from openai import OpenAI client = OpenAI(base_url="https://ai-gateway.cubepath.com", api_key="") reply = client.chat.completions.create( model="openai/gpt-4o", messages=[{"role": "user", "content": "¡Hola!"}], ) print(reply.choices[0].message.content) ``` El gateway sirve Chat Completions. La API Responses de OpenAI (`/v1/responses`) no está disponible. ## Vercel AI SDK Para cualquier proveedor, usa el adaptador compatible con OpenAI: ```ts import { createOpenAICompatible } from "@ai-sdk/openai-compatible"; import { generateText } from "ai"; const cubepath = createOpenAICompatible({ name: "cubepath", baseURL: "https://ai-gateway.cubepath.com/v1", apiKey: process.env.CUBEPATH_TOKEN, includeUsage: true, }); const { text } = await generateText({ model: cubepath("google/gemini-2.5-pro"), prompt: "¡Hola!" }); ``` Para Claude, el adaptador nativo te da el razonamiento, la caché de prompts y la salida estructurada tal como los define Anthropic: ```ts import { createAnthropic } from "@ai-sdk/anthropic"; const anthropic = createAnthropic({ baseURL: "https://ai-gateway.cubepath.com/v1", apiKey: process.env.CUBEPATH_TOKEN, }); // anthropic("claude-sonnet-5") ``` Si usas `@ai-sdk/openai`, llama a `.chat("openai/gpt-4.1-mini")`: su modelo por defecto usa la API Responses, que el gateway no sirve. ## SDK de Anthropic El SDK añade `/v1/messages` por su cuenta, así que la URL base no lleva `/v1`. ```python import anthropic client = anthropic.Anthropic(base_url="https://ai-gateway.cubepath.com", api_key="") msg = client.messages.create( model="claude-sonnet-5", max_tokens=1024, messages=[{"role": "user", "content": "¡Hola!"}], ) ``` Valen `claude-sonnet-5` y `anthropic/claude-sonnet-5`, y también los nombres con fecha y con `-latest`. `POST /v1/messages/count_tokens` está disponible y es gratis. En `/v1/messages` solo están los modelos de Anthropic. ## Claude Code ```bash export ANTHROPIC_BASE_URL=https://ai-gateway.cubepath.com export ANTHROPIC_AUTH_TOKEN= export ANTHROPIC_API_KEY= claude ``` `ANTHROPIC_API_KEY` tiene que estar vacía para que Claude Code no envíe una clave suya. Algunas funciones de Anthropic que tienen un cargo aparte todavía no están disponibles y devuelven un error 400 que dice cuál: las herramientas del servidor (búsqueda web, descarga de páginas, ejecución de código, el asesor, el conector MCP), el modo rápido y el beta de contexto de 1M en modelos anteriores a Claude 4.6. Tus propias herramientas (también bash, editor de texto, computer y memory) funcionan. Claude Code pide respuestas muy largas y el gateway las reserva en tu saldo (mira más abajo). Si tu saldo es pequeño, baja el límite de salida con `export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192`. ## Usa tu propia clave del proveedor (BYOK) Envía tu clave del proveedor en la cabecera `X-Provider-Api-Key` y la petición va al proveedor con tu clave. El gateway no te cobra esos tokens (se siguen anotando en tu uso) y le pagas al proveedor directamente. Tu token de CubePath va donde siempre. - Funciona en `/chat/completions`, `/v1/messages` y `/v1/messages/count_tokens`. - Tu organización necesita un saldo en efectivo de al menos 0 $ (el crédito promocional no cuenta). - Si el proveedor rechaza tu clave, recibes un 401 o un 403 con la cabecera `X-Provider-Key-Rejected: 1`. En `/chat/completions` el mensaje empieza por "Your provider key was rejected"; en `/v1/messages` el cuerpo es el error del propio proveedor. Si la respuesta por partes ya había empezado, el error llega dentro de ella y sin la cabecera. - `count_tokens` con tu propia clave está limitado a 30 peticiones por minuto. - Tu clave no se guarda en ningún registro y se quita de los mensajes de error. ```python client = OpenAI(base_url="https://ai-gateway.cubepath.com", api_key="", default_headers={"X-Provider-Api-Key": ""}) ``` Claude Code: `export ANTHROPIC_CUSTOM_HEADERS="X-Provider-Api-Key: "`. Vercel AI SDK: la opción `headers`. ## Cómo se cobra Pagas por token según los precios de `/models`, y se descuenta de tu saldo al terminar cada petición. El crédito promocional no se puede gastar en el AI Gateway. **Caché de prompts.** La entrada en caché tiene sus propios precios: leer de la caché sale más barato que la entrada normal, y algunos proveedores cobran un extra por escribir en ella (Anthropic tiene escritura de 5 minutos y de 1 hora). El uso de cada respuesta muestra los tokens de caché por separado. Si usas `cache_control` con Claude, se envía tal cual. **Razonamiento.** Los tokens de razonamiento se cobran como tokens de salida. Puedes ajustarlos con `reasoning_effort` (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`); el gateway lo adapta a lo que admite cada modelo. xAI da sus tokens de razonamiento aparte de `completion_tokens`, y los dos se cobran como salida. Los modelos de razonamiento pueden gastar muchos tokens de salida, así que elige `max_tokens` con eso en mente. **Reservas de saldo.** Antes de ejecutar una petición, el gateway reserva en tu saldo lo máximo que podría costar (tu entrada más la salida máxima) y, al terminar, cobra el coste real. Puedes tener muchas peticiones a la vez, y la reserva de cada una cuenta contra tu saldo. - `402`: tu saldo en efectivo no llega para la petición. Recarga o baja `max_tokens`. - `429` con `Retry-After`: tienes saldo suficiente, pero otras peticiones en curso lo tienen reservado ahora mismo. Reintenta en unos segundos o baja `max_tokens`. - `503` con `Retry-After`: el proveedor ha fallado o no ha respondido, la facturación no está disponible un momento, el gateway se está reiniciando o está ocupado con peticiones muy grandes. Reintenta. Ejemplo: con Claude Opus (5,25 $ por millón de tokens de entrada, 26,25 $ por millón de salida), una petición con 120.000 tokens de contexto y `max_tokens` 32000 reserva 0,63 $ + 0,84 $ = 1,47 $, aunque el coste real acabe siendo de céntimos. Con la caché de prompts la entrada se reserva al precio de escritura en caché (6,5625 $ por millón, o 10,50 $ con la caché de 1 hora), así que la misma petición reserva unos 1,63 $; Claude Code usa la caché por defecto, así que tres peticiones suyas a la vez necesitan unos 4,88 $ de saldo. Con `max_tokens` 8192 la reserva baja a unos 1,00 $. Bajar `max_tokens` baja la reserva. Las reservas se liberan al terminar la petición y caducan solas si algo falla. ## Respuestas largas con `stream: true` Usa `stream: true` para respuestas largas, modelos de razonamiento y agentes: ves la respuesta a medida que se escribe y, mientras el modelo piensa, llegan comentarios para mantener la conexión, que los SDK ignoran, así que nada por el camino la corta. Una llamada sin `stream` que tarda más de 80 segundos recibe el estado `200` en ese momento y después un espacio cada 15 segundos hasta que la respuesta está lista. Los lectores de JSON ignoran esos espacios del principio, así que los SDK leen la respuesta como siempre. Si el proveedor falla después de ese punto, el error llega en el cuerpo con estado `200`: `{"detail": "...", "error": {...}}` en `/chat/completions` y el formato de error de Anthropic en `/v1/messages`. Una llamada sin `stream` se corta a los 15 minutos y entonces pagas la entrada. Qué pagas si te desconectas: - Antes de que el proveedor tenga tu petición: nada. - De una llamada sin `stream`, cuando el proveedor ya la tiene: la respuesta entera, como si hubieras esperado. El proveedor sigue trabajando y la cobra completa. - De una respuesta por partes: lo que hayas recibido, o la entrada si aún no había llegado texto. Si el proveedor no envía nada durante 300 segundos, la respuesta por partes se corta. ## Herramientas con Claude en /chat/completions Los modelos Claude que razonan devuelven su razonamiento como `reasoning_details` en `/chat/completions`. Cuando encadenes llamadas a herramientas, devuelve el mensaje del asistente tal como lo recibiste. Para controlar del todo el razonamiento, la caché y las herramientas con Claude, usa `/v1/messages` (el SDK de Anthropic o el adaptador de Anthropic de Vercel). ## Límites - Límite de peticiones: 60 por minuto por organización por defecto. Contar tokens tiene un límite propio, más alto. - Tamaño de la petición: 10 MiB en `/chat/completions` y 32 MiB en `/v1/messages`. - `response_format` (modo JSON y esquema JSON) funciona con los modelos de OpenAI y xAI en `/chat/completions`. DeepSeek solo admite el modo JSON (`json_object`), y el prompt tiene que mencionar JSON. Claude y Gemini lo ignoran ahí; para salida estructurada con Claude usa `/v1/messages`. - DeepSeek V4 razona por defecto y rechaza un `tool_choice` forzado mientras razona; envíalo con `reasoning_effort: "none"`. - Los precios más altos que aplican algunos proveedores a partir de cierto tamaño de prompt se cobran al precio base. - Navegadores: el gateway solo admite llamadas desde el navegador en los sitios de CubePath. Llámalo desde tu servidor. ## Errores `/chat/completions` devuelve `{"detail": "..."}`. `/v1/messages` devuelve errores con el formato de Anthropic (`{"type":"error","error":{"type":"...","message":"..."}}`), así que el SDK de Anthropic los entiende. Cuando el proveedor falla o no responde, el gateway devuelve `503` con `Retry-After`, y los SDK lo reintentan solos. Un `502` o un `504` solo vienen de nuestra red cuando no se puede llegar al gateway, como una página corta de texto plano; trátalos como un `503`. ## Vigilar el coste El panel registra **peticiones, tokens y coste**, por día y por modelo, en los últimos 30 días. Míralo por modelo y no en total: lo normal es que una sola llamada de tu aplicación, como un resumen o un clasificador que se ejecuta en cada petición, se lleve la mayor parte de la factura, y pasar solo esa llamada a un modelo más pequeño cambia mucho la cifra. ## Buenas prácticas - **Usa el modelo más pequeño que pase tus pruebas**, no el más grande que te puedas permitir. La diferencia de calidad suele ser menor que la de precio. - **Limita la salida** con `max_tokens` donde una respuesta desbocada saldría cara. También baja la reserva. - **Reutiliza los prompts largos** para que el proveedor los sirva desde su caché, y guarda en tu lado los resultados que vas a volver a necesitar.