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.

URL base: https://ai-gateway.cubepath.com

Primeros pasos

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:

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.

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.

from openai import OpenAI

client = OpenAI(base_url="https://ai-gateway.cubepath.com", api_key="<tu-token-de-cubepath>")
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:

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:

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.

import anthropic

client = anthropic.Anthropic(base_url="https://ai-gateway.cubepath.com", api_key="<tu-token-de-cubepath>")
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

export ANTHROPIC_BASE_URL=https://ai-gateway.cubepath.com
export ANTHROPIC_AUTH_TOKEN=<tu-token-de-cubepath>
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.

client = OpenAI(base_url="https://ai-gateway.cubepath.com", api_key="<token-de-cubepath>",
                default_headers={"X-Provider-Api-Key": "<tu-clave-de-openai>"})

Claude Code: export ANTHROPIC_CUSTOM_HEADERS="X-Provider-Api-Key: <tu-clave-de-anthropic>". 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.