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.

Disponibilidad del servicio

Inicio rápido

Para una cuenta existente con acceso a la API necesitas tres cosas:

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. Model: uno de los 16 modelos compatibles, p. gpt-5.4-mini o claude-sonnet-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

La superficie pública estable se describe a continuación y en el documento OpenAPI 3.1 legible por máquinas. Los campos no enumerados pueden enviarse al proveedor, pero no pasan automáticamente a formar parte del contrato de compatibilidad de SUB&SUB.

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/responses

OpenAI Responses API: la forma de solicitud OpenAI más nueva (client.responses.create(...)). Funciona con todos los modelos de catálogo: gpt-* de forma nativa, claude-* a través del mismo puente de compatibilidad que chat/compleciones. El uso se mide de manera idéntica: tokens de entrada/salida según la tasa de nivel del modelo.

Ejemplo ejecutable de Responses:

curl https://api.subnsub.com/v1/responses \
  -H "Authorization: Bearer sk-cf-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Explain exponential backoff in two sentences."
  }'

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).

Ejemplo ejecutable de Anthropic Messages:

curl https://api.subnsub.com/v1/messages \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

POST /v1/messages/count_tokens

Cuenta un prompt con formato Anthropic antes de enviarlo. Usa los mismos campos x-api-key, anthropic-version, model, system, messages y tools que enviarías a /v1/messages. Este endpoint no se factura. Se elimina el sufijo :online, pero no se obtienen ni se cuentan resultados de búsqueda.

curl https://api.subnsub.com/v1/messages/count_tokens \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Count this prompt."}]
  }'

GET /v1/models

Enumere los modelos que realmente puede utilizar. El relé verifica el estado de ambas familias ascendentes y devuelve las 16 identificaciones públicas verificadas, la misma lista blanca que aplican los puntos finales POST, por lo que el descubrimiento nunca anuncia un modelo que sería 400. Si no se puede acceder al catálogo ascendente, el punto final 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-5",     "type": "model", ... },
    { "id": "claude-fable-5",      "type": "model", ... },
    ...
  ]
}

Contrato de compatibilidad

Ser compatible con OpenAI no garantiza todos los campos de todos los modelos upstream en cada ruta. Hay tres niveles de soporte:

Modelos disponibles

Dos familias río arriba. Los 7 modelos OpenAI se dirigen a cuentas compartidas del nivel ChatGPT; los 9 modelos Claude son atendidos por cuentas oficiales Anthropic. Las tarifas por token dependen del nivel (consulte Pricing): la misma clave funciona para ambos.

OpenAI

Anthropic

Esfuerzo de razonamiento

Cada modelo OpenAI anterior es un modelo de razonamiento: el backend puede gastar más o menos tokens de "pensamiento" antes de emitir resultados visibles. Establezca reasoning_effort en el cuerpo de la solicitud OpenAI /v1/chat/completions (o reasoning: {"effort": ...} en /v1/responses) para controlar el presupuesto. Para Claude, utilice los campos Anthropic nativos thinking y output_config.effort; consulte la sección /v1/messages. Los modelos 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]

Ejemplo ejecutable de streaming en Python:

from openai import OpenAI

client = OpenAI(
    api_key="sk-cf-xxxxxxxxxxxx",
    base_url="https://api.subnsub.com/v1",
)

stream = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    text = chunk.choices[0].delta.content if chunk.choices else None
    if text:
        print(text, end="", flush=True)

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:

Reintentos y fiabilidad

Usa un número limitado de reintentos. El relay depende de capacidad upstream compartida y las solicitudes de generación no son idempotentes.

• Reintenta: respuestas 429, 502, 503 y 500 claramente transitorias. Respeta retry-after; si no existe, usa espera exponencial con jitter (por ejemplo, 1 s, 2 s y 4 s; tres intentos como máximo).
• No reintentes sin cambios: 400, 401, 402 o 403. Corrige primero el payload, la clave, el saldo o el estado de acceso.
• Riesgo de duplicados: cada generación correcta es una solicitud facturable independiente. SUB&SUB no deduplica actualmente los POST de generación mediante una clave de idempotencia; conserva un ID de operación en tu aplicación y evita reintentar tras una respuesta completa.
• Streaming: un flujo SSE interrumpido no se puede reanudar. Reconectar inicia otra generación y puede producir un segundo cargo.

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 de Fable y Ultra coinciden con los precios de lista publicados de Anthropic. Sonnet 5 utiliza la tarifa introductoria de $2/$10 de Anthropic hasta el 31 de agosto de 2026; su precio estándar publicado después de esa fecha es $3/$15. Los otros niveles funcionan por debajo de las tarifas ascendentes gracias al respaldo de suscripción conjunta.

Los tokens de razonamiento (cuando configuras reasoning_effort en OpenAI, o el campo nativo thinking de Anthropic en Claude) cuentan como output tokens según la tasa de nivel del modelo; no hay un recargo separado por esfuerzo elevado, pero una solicitud de pensamiento profundo puede emitir fácilmente entre 10 y 50 veces más tokens de salida que una uno sin esfuerzo, por lo que el billete de un dólar crece con él.

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. Los tokens de caché se detallan en el registro de facturación de cada solicitud — la consola muestra 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. Siguen aplicándose la capacidad upstream compartida y la limitación del lado del proveedor; si alcanzas esos límites, el relay devuelve 429 con una cabecera retry-after. Los límites de RPM / TPM por clave están previstos.

Estado y soporte

• Las cuentas con acceso a la API pueden ver el estado de los proveedores en Consola → Estado del servicio y los avisos operativos en Aviso del sistema.
• Para ayuda con la cuenta, facturación, privacidad o seguridad, escribe a [email protected].
• Al informar de un fallo de API, incluye la hora UTC, endpoint, modelo, estado HTTP y prefijo visible de la clave. No envíes nunca la clave completa ni el contenido del prompt salvo que soporte pida expresamente una reproducción redactada.
• El servicio funciona según el mejor esfuerzo y no tiene SLA. Consulta los Términos de servicio, solo en inglés, para disponibilidad y reembolsos, y la Política de privacidad para el tratamiento de datos.

Última revisión de la documentación: 14 de julio de 2026.