Referência da API

O SUB&SUB expõe um relay multi-provedor em https://api.subnsub.com/v1. Clientes OpenAI acessam /v1/chat/completions; clientes Anthropic acessam /v1/messages. A mesma chave sk-cf-... roteia ambos — escolha o modelo no corpo da requisição e o relay escolhe o upstream.

Início rápido

Três coisas de que você precisa:

1. Base URL: https://api.subnsub.com/v1 (clientes OpenAI) ou https://api.subnsub.com (clientes Anthropic — o SDK acrescenta /v1/messages por conta própria)
2. Chave API: sk-cf-... emitida no console
3. Modelo: um dos 21 modelos verificados — ex.: gpt-5.4-mini ou claude-haiku-4.5

Autenticação

Toda requisição deve carregar um cabeçalho Authorization: Bearer sk-cf-.... As chaves são emitidas no console e armazenadas como hashes SHA-256 — assim que você sai da tela de criação, o texto plano se perde para sempre, então salve-o imediatamente.

Endpoints

POST /v1/chat/completions

Envie uma requisição de chat completion. O formato da requisição corresponde à API OpenAI Chat Completions — os SDKs da OpenAI funcionam sem modificações.

POST /v1/messages

Endpoint nativo da Anthropic para os modelos claude-* — o SDK da Anthropic (anthropic-sdk-python, @anthropic-ai/sdk, claude-code) funciona sem modificações contra este caminho. Aponte sua base URL para https://api.subnsub.com e autentique pelo cabeçalho x-api-key (a forma Authorization-Bearer também funciona, se o seu cliente preferir).

GET /v1/models

Lista os modelos que você pode de fato chamar. O relay mescla os catálogos OpenAI e Anthropic do sub2api e filtra para os 21 que testamos de ponta a ponta contra o pool de contas atual — IDs fantasma que dão 503 no momento do roteamento, ou 400 de upstream no primeiro token, ficam ocultos. Se todo upstream configurado estiver inacessível, o endpoint retorna 502 models_unreachable em vez de uma lista vazia enganosa.

# 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 disponíveis

Duas famílias de upstream. Os 7 modelos OpenAI roteiam para contas compartilhadas de nível ChatGPT; os 14 modelos Claude roteiam por um proxy reverso Kiro até o AWS CodeWhisperer. As tarifas por token dependem do tier (veja Preços) — a mesma chave funciona para ambos.

OpenAI

Anthropic

Esforço de raciocínio

Cada modelo OpenAI acima é um modelo de raciocínio — o backend pode gastar mais ou menos tokens de "pensamento" antes de emitir a saída visível. Defina reasoning_effort no corpo da requisição OpenAI /v1/chat/completions para controlar o orçamento. Para o Claude, use o campo de requisição nativo da Anthropic thinking (ou escolha uma variante de modelo -thinking) — veja a seção /v1/messages. Os modelos OpenAI aceitam os mesmos cinco valores de esforço:

# 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

Defina "stream": true para receber Server-Sent Events. O chunk final carrega um bloco usage (forçamos stream_options.include_usage no upstream para que as contagens de tokens sejam sempre emitidas), e então um literal data: [DONE] encerra o 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]

Busca na web

Acrescente :online a qualquer ID de modelo suportado pelo endpoint e o relay executará uma busca na web antes de encaminhar ao modelo, prefixando os resultados na conversa para que a resposta se baseie em dados frescos. O sufixo funciona em /v1/chat/completions e /v1/messages (este último ainda exige uma base claude-*); nenhum campo de requisição específico de busca é necessário.

# 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?"}
    ]
  }'

Como funciona: o relay remove o :online, toma a mensagem de usuário mais recente como consulta (limitada a 400 caracteres), chama o Tavily para até 3 resultados com o texto da página extraído quando disponível, mais um resumo opcional gerado pelo Tavily, e então os prefixa nesse mesmo turno do usuário como um bloco <search_results> claramente delimitado antes de enviar a requisição ao upstream. A chamada de busca tem um timeout de 8 segundos. Os resultados são deliberadamente injetados no papel de usuário — nunca no system prompt — para que trechos não confiáveis não possam ser elevados a instruções de prioridade de sistema.

O bloco <search_results> tem esta aparência. Ele é precedido por uma instrução de uma linha dizendo ao modelo para tratar o bloco como dados externos não confiáveis e citar os itens numerados em linha:

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

Quando usar :online

O relay faz uma única chamada ao Tavily por requisição e injeta os resultados — não é um loop de busca agêntico. O modelo não decide buscar de novo com base no que vê, do jeito que o Perplexity Sonar ou a ferramenta de navegação do ChatGPT fazem. Planeje considerando essa limitação:

Formule a última mensagem de usuário como uma consulta de busca autônoma. A busca é executada contra o texto literal do seu turno de usuário mais recente (limitado a 400 caracteres), então perguntas conversacionais de acompanhamento como "e quanto à versão mais recente?" viram consultas inúteis sem contexto. Em um chat multi-turno, reformule o tópico ao adicionar :online — ex.: "versão mais recente do SDK Python da Anthropic" em vez de "a mais recente".

Para perguntas que precisam de síntese em múltiplas etapas (comparar e contrastar, pesquisa aprofundada), divida-as em vários turnos e adicione :online a cada um. O modelo lerá os resultados frescos de cada turno; você direciona a próxima consulta manualmente. Observe que o bloco <search_results> injetado é enviado apenas ao upstream — não é devolvido ao seu cliente nem preservado na próxima requisição, então se um turno posterior depender de detalhes de fontes anteriores, peça ao modelo para resumi-los na sua resposta visível. O modo de pesquisa em uma única tacada não é suportado.

Erros

O envelope depende de qual endpoint você chamou — o relay retorna erros no protocolo que corresponde ao SDK do chamador, e os erros de upstream são repassados tal e qual.

Caminhos OpenAI (/v1/chat/completions, /v1/responses, /v1/models) — envelope OpenAI:

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

Caminhos Anthropic (/v1/messages, /v1/messages/count_tokens) — envelope Anthropic:

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

O envelope Anthropic usa um formato diferente — sem o campo code, e o discriminador type: "error" fica no nível superior (com o error.type interno informando a categoria, ex.: authentication_error, invalid_request_error, permission_error, api_error). Os SDKs da Anthropic já analisam esse formato; os tratadores de erro do SDK OpenAI puro não, então chame /v1/messages com um SDK da Anthropic (ou faça HTTP cru).

Os códigos de status são os HTTP canônicos em ambos os protocolos:

Preços e cobrança

Pague pelo uso, cobrado por token em microdólares (1 micro = $0.000001 = 1/10,000 de um centavo) para que requisições abaixo de um centavo sejam rastreadas com precisão. As tarifas são por 1M tokens, por tier — veja a tabela de modelos para qual tier cada modelo mapeia.

As tarifas do tier Ultra correspondem ao preço de lista do Opus publicado pela Anthropic — repasse direto, sem margem. Os outros tiers operam abaixo de suas tarifas de upstream graças ao respaldo da assinatura compartilhada.

Os tokens de raciocínio (quando você define reasoning_effort na OpenAI, ou usa uma variante -thinking do Claude) contam como tokens de saída à tarifa do tier do modelo — não há sobretaxa separada para esforço alto, mas uma requisição de pensamento profundo pode facilmente emitir 10–50× mais tokens de saída do que uma sem esforço, então a conta em dólares escala junto.

O prompt-caching da Anthropic é cobrado como um item separado: escritas em cache a 1.25× e leituras em cache a 0.10× da tarifa de entrada do tier. Então um cache hit do haiku-4.5 custa 0.20 × 0.10 = $0.02 per 1M tokens, e um cache hit do sonnet-4.5 custa 0.75 × 0.10 = $0.075 per 1M tokens. As colunas de cache são registradas em cada linha de liquidação para que o console possa mostrar o detalhamento.

O saldo é descontado em tempo real conforme cada requisição retorna — para requisições em streaming, a liquidação ocorre depois que o chunk [DONE] chega. Veja seu saldo ao vivo e as liquidações por requisição em /console#billing.

Limites de taxa

Sem limites de taxa por chave hoje. Aplicam-se a concorrência do pool de contas de upstream & o throttling do lado do servidor da OpenAI; se você esbarrar neles, o relay retorna 429 com um cabeçalho retry-after. Limites de RPM / TPM por chave chegarão pós-MVP.