Referencia de la API

SUB&SUB expone un relay multiproveedor en https://api.subnsub.com/v1. Los clientes de OpenAI llaman a /v1/chat/completions; los clientes de Anthropic llaman a /v1/messages. La misma clave sk-cf-... enruta ambos — elige el modelo en el cuerpo de la solicitud y el relay elige el upstream.

Inicio rápido

Tres cosas que necesitas:

1. URL base: https://api.subnsub.com/v1 (clientes de OpenAI) o https://api.subnsub.com (clientes de Anthropic — el SDK añade /v1/messages por sí mismo)
2. Clave API: sk-cf-... emitida desde la consola
3. Modelo: uno de los 21 modelos verificados — p. ej. gpt-5.4-mini o claude-haiku-4.5

Autenticación

Cada solicitud debe llevar una cabecera Authorization: Bearer sk-cf-.... Las claves se emiten desde la consola y se almacenan como hashes SHA-256 — una vez que abandonas la pantalla de creación, el texto plano desaparece para siempre, así que guárdalo de inmediato.

Endpoints

POST /v1/chat/completions

Envía una solicitud de chat completion. La forma de la solicitud coincide con la API de Chat Completions de OpenAI — los SDK de OpenAI funcionan sin modificaciones.

POST /v1/messages

Endpoint nativo de Anthropic para los modelos claude-* — el SDK de Anthropic (anthropic-sdk-python, @anthropic-ai/sdk, claude-code) funciona sin modificaciones contra esta ruta. Apunta tu URL base a https://api.subnsub.com y autentícate mediante la cabecera x-api-key (la forma Authorization-Bearer también funciona, si tu cliente lo prefiere).

GET /v1/models

Lista los modelos que realmente puedes llamar. El relay fusiona los catálogos de OpenAI y Anthropic de sub2api y los filtra hasta los 21 que hemos probado de extremo a extremo contra el grupo de cuentas actual — los IDs fantasma que dan 503 en el momento del enrutamiento, o un 400 upstream en el primer token, quedan ocultos. Si todos los upstreams configurados son inalcanzables, el endpoint devuelve 502 models_unreachable en lugar de una lista vacía engañosa.

# sample response (truncated)
{
  "object": "list",
  "data": [
    { "id": "gpt-5.4-mini",      "type": "model", ... },
    { "id": "gpt-5.4",           "type": "model", ... },
    { "id": "claude-sonnet-4.5", "type": "model", ... },
    { "id": "claude-haiku-4.5",  "type": "model", ... },
    ...
  ]
}

Modelos disponibles

Dos familias de upstream. Los 7 modelos de OpenAI se enrutan a cuentas compartidas de la gama de ChatGPT; los 14 modelos de Claude se enrutan a través de un proxy inverso de Kiro hacia AWS CodeWhisperer. Las tarifas por token dependen del tier (consulta Precios) — la misma clave funciona para ambos.

OpenAI

Anthropic

Esfuerzo de razonamiento

Cada modelo de OpenAI anterior es un modelo de razonamiento — el backend puede gastar más o menos tokens de "pensamiento" antes de emitir salida visible. Establece reasoning_effort en el cuerpo de la solicitud de OpenAI /v1/chat/completions para controlar el presupuesto. Para Claude, usa el campo de solicitud nativo de Anthropic thinking (o elige una variante de modelo -thinking) — consulta la sección /v1/messages. Los modelos de OpenAI aceptan los mismos cinco valores de esfuerzo:

# Two equivalent forms — pick whichever your SDK supports
{
  "model": "gpt-5.4-mini",
  "reasoning_effort": "high",
  "messages": [ ... ]
}

{
  "model": "gpt-5.5",
  "reasoning": { "effort": "xhigh" },
  "messages": [ ... ]
}

Streaming

Establece "stream": true para recibir Server-Sent Events. El fragmento final lleva un bloque usage (forzamos stream_options.include_usage en el upstream para que los recuentos de tokens siempre se emitan), y luego un literal data: [DONE] cierra el stream.

# Streaming format (line by line)
data: {"id":"resp_...","choices":[{"delta":{"content":"Hi"}}]}

data: {"id":"resp_...","choices":[{"delta":{"content":"!"}}]}

data: {"id":"resp_...","choices":[],"usage":{"prompt_tokens":18,"completion_tokens":11,"total_tokens":29}}

data: [DONE]

Búsqueda web

Añade :online a cualquier ID de modelo soportado por el endpoint y el relay ejecutará una búsqueda web antes de reenviar al modelo, anteponiendo los resultados a la conversación para que la respuesta se base en datos frescos. El sufijo funciona en /v1/chat/completions y /v1/messages (este último sigue requiriendo una base claude-*); no se requiere ningún campo de solicitud específico de búsqueda.

# Same call as before — just :online on the model
curl https://api.subnsub.com/v1/chat/completions \
  -H "Authorization: Bearer sk-cf-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini:online",
    "messages": [
      {"role": "user", "content": "What did Anthropic ship this week?"}
    ]
  }'

Cómo funciona: el relay elimina :online, toma el mensaje de usuario más reciente como consulta (limitada a 400 caracteres), llama a Tavily para obtener hasta 3 resultados con el texto extraído de la página cuando esté disponible, más un resumen opcional generado por Tavily, y luego los antepone a ese mismo turno de usuario como un bloque <search_results> claramente delimitado antes de enviar la solicitud al upstream. La llamada de búsqueda tiene un timeout de 8 segundos. Los resultados se inyectan deliberadamente en el rol de usuario — nunca en el system prompt — para que los fragmentos no confiables no puedan elevarse a instrucciones de prioridad de sistema.

El bloque <search_results> tiene este aspecto. Va precedido de una instrucción de una línea que indica al modelo que trate el bloque como datos externos no confiables y que cite los elementos numerados de forma inline:

<search_results query="What did Anthropic ship this week?" retrieved="2026-05-21">
Summary: <short LLM-generated synthesis of the result set>

[1] Anthropic launches Opus 4.8
URL: https://www.anthropic.com/news/opus-4-8
<extracted page text, or short snippet if extraction failed — up to ~2000 chars>

[2] ...
</search_results>

Cuándo usar :online

El relay hace una única llamada a Tavily por solicitud e inyecta los resultados — no es un bucle de búsqueda agéntico. El modelo no decide volver a buscar en función de lo que ve, como hacen Perplexity Sonar o la herramienta de navegación de ChatGPT. Planifica teniendo en cuenta esa limitación:

Formula el último mensaje de usuario como una consulta de búsqueda autónoma. La búsqueda se ejecuta contra el texto literal de tu turno de usuario más reciente (limitado a 400 caracteres), por lo que los seguimientos conversacionales como "¿y qué hay de la última versión?" se convierten en consultas inútiles sin contexto. En un chat de varios turnos, replantea el tema cuando añadas :online — p. ej. "última versión del SDK de Python de Anthropic" en lugar de "la más reciente".

Para preguntas que requieren síntesis de varios pasos (comparar y contrastar, investigación profunda), divídelas en varios turnos y añade :online a cada uno. El modelo leerá los resultados frescos de cada turno; tú diriges la siguiente consulta manualmente. Ten en cuenta que el bloque <search_results> inyectado se envía solo al upstream — no se devuelve a tu cliente y no se conserva en la siguiente solicitud, así que si un turno posterior depende de detalles de fuentes anteriores, pide al modelo que los resuma en su respuesta visible. El modo de investigación en una sola pasada no está soportado.

Errores

El envoltorio depende del endpoint que hayas llamado — el relay devuelve los errores en el protocolo que coincide con el SDK del llamante, y los errores del upstream se transmiten literalmente.

Rutas de OpenAI (/v1/chat/completions, /v1/responses, /v1/models) — envoltorio de OpenAI:

{ "error": { "message": "...", "type": "...", "code": "..." } }

Rutas de Anthropic (/v1/messages, /v1/messages/count_tokens) — envoltorio de Anthropic:

{ "type": "error", "error": { "type": "...", "message": "..." } }

El envoltorio de Anthropic usa una forma diferente — sin campo code, y el discriminador type: "error" está en el nivel superior (con el error.type interno dando la categoría, p. ej. authentication_error, invalid_request_error, permission_error, api_error). Los SDK de Anthropic ya parsean esta forma; los manejadores de errores del SDK estándar de OpenAI no, así que llama a /v1/messages con un SDK de Anthropic (o haz HTTP en crudo).

Los códigos de estado son los canónicos de HTTP en ambos protocolos:

Precios y facturación

Pago por uso, facturado por token en microdólares (1 micro = $0.000001 = 1/10,000 de un centavo) para que las solicitudes de menos de un centavo se registren con precisión. Las tarifas son por 1M de tokens, por tier — consulta la tabla de modelos para ver a qué tier mapea cada modelo.

Las tarifas del tier Ultra coinciden con el precio de lista de Opus publicado por Anthropic — pass-through directo, sin margen. Los otros tiers funcionan por debajo de sus tarifas upstream gracias al respaldo de la suscripción agrupada.

Los tokens de razonamiento (cuando estableces reasoning_effort en OpenAI, o usas una variante -thinking de Claude) cuentan como tokens de salida a la tarifa del tier del modelo — no hay recargo aparte por esfuerzo alto, pero una solicitud de pensamiento profundo puede emitir fácilmente entre 10–50× más tokens de salida que una sin esfuerzo, por lo que la factura en dólares escala con ello.

El prompt-caching de Anthropic se factura como una línea aparte: las escrituras en caché a 1.25× y las lecturas en caché a 0.10× la tarifa de entrada del tier. Así, un acierto de caché de haiku-4.5 cuesta 0.20 × 0.10 = $0.02 per 1M tokens, y un acierto de caché de sonnet-4.5 cuesta 0.75 × 0.10 = $0.075 per 1M tokens. Las columnas de caché se registran en cada fila de liquidación para que la consola pueda mostrar el desglose.

El saldo se descuenta en tiempo real a medida que cada solicitud retorna — para las solicitudes en streaming, la liquidación se ejecuta después de que aterrice el fragmento [DONE]. Consulta tu saldo en vivo y las liquidaciones por solicitud en /console#billing.

Límites de tasa

Hoy no hay límites de tasa por clave. Se aplican la concurrencia del grupo de cuentas upstream y la limitación del lado del servidor de OpenAI; si alcanzas esos límites, el relay devuelve 429 con una cabecera retry-after. Los límites de RPM / TPM por clave llegarán después del MVP.