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.

Disponibilidade do serviço

Início rápido

Para uma conta existente com API ativa, são necessárias três coisas:

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 16 modelos compatíveis — por exemplo, gpt-5.4-mini ou claude-sonnet-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

A interface pública estável está descrita abaixo e no documento OpenAPI 3.1 legível por máquina. Os campos não listados podem ser enviados ao upstream, mas não passam automaticamente a fazer parte do contrato de compatibilidade da SUB&SUB.

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

OpenAI Responses API — o formato de solicitação OpenAI mais recente (client.responses.create(...)). Funciona com todos os modelos de catálogo: gpt-* nativamente, claude-* através da mesma ponte de compatibilidade que chat/conclusões. O uso é medido de forma idêntica – tokens de entrada/saída de acordo com a taxa de nível do modelo.

Exemplo executável 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 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).

Exemplo executável 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

Conte um prompt no formato Anthropic antes de o enviar. Use os mesmos campos x-api-key, anthropic-version, model, system, messages e tools que enviaria para /v1/messages. Este endpoint não é faturado. O sufixo :online é removido, mas os resultados de pesquisa não são obtidos nem contados.

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

Liste os modelos que você realmente pode usar. A integridade da retransmissão verifica ambas as famílias upstream e retorna os 16 IDs públicos verificados — a mesma lista de permissões que os endpoints POST impõem, para que a descoberta nunca anuncie um modelo que seria 400. Se o catálogo upstream estiver inacessível, o endpoint retornará 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-5",     "type": "model", ... },
    { "id": "claude-fable-5",      "type": "model", ... },
    ...
  ]
}

Contrato de compatibilidade

Ser compatível com OpenAI não significa que todos os campos de todos os modelos upstream sejam garantidos em todas as rotas. Existem três níveis de suporte:

Modelos disponíveis

Duas famílias a montante. Os 7 modelos OpenAI são direcionados para contas compartilhadas da camada ChatGPT; os 9 modelos Claude são atendidos por contas oficiais Anthropic. As taxas por token dependem do nível (consulte 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 back-end pode gastar mais ou menos tokens de "pensamento" antes de emitir uma saída visível. Defina reasoning_effort no corpo da solicitação OpenAI /v1/chat/completions (ou reasoning: {"effort": ...} em /v1/responses) para controlar o orçamento. Para Claude, use os campos Anthropic-nativos thinking e output_config.effort — consulte 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]

Exemplo executável de streaming em 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)

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:

Novas tentativas e fiabilidade

Limite as novas tentativas. O relay depende de capacidade upstream partilhada e os pedidos de geração não são idempotentes.

• Voltar a tentar: respostas 429, 502, 503 e 500 claramente transitórias. Respeite retry-after; caso contrário, use espera exponencial com jitter (por exemplo, 1 s, 2 s, 4 s; no máximo três tentativas).
• Não repetir sem alterações: 400, 401, 402 ou 403. Corrija primeiro o payload, a chave, o saldo ou o estado de acesso.
• Risco de duplicação: cada geração bem-sucedida é um pedido faturável separado. A SUB&SUB não elimina atualmente POSTs de geração duplicados através de uma idempotency key; mantenha um ID de operação na aplicação e não repita após uma resposta completa.
• Streaming: um fluxo SSE interrompido não pode ser retomado. Uma nova ligação inicia outra geração e pode causar uma segunda cobrança.

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 de Fable e Ultra correspondem aos preços de tabela publicados de Anthropic. Sonnet 5 usa a taxa introdutória de US$ 2/US$ 10 de Anthropic até 31 de agosto de 2026; seu preço padrão publicado após essa data é de US$ 3/US$ 15. Os outros níveis funcionam abaixo das taxas upstream graças ao suporte de assinatura em pool.

Os tokens de raciocínio (quando você define reasoning_effort em OpenAI ou o campo nativo thinking de Anthropic em Claude) contam como tokens de saída na taxa de nível do modelo — não há sobretaxa separada para alto esforço, mas uma solicitação de pensamento profundo pode facilmente emitir de 10 a 50 vezes mais tokens de saída do que uma solicitação sem esforço, portanto a nota de um dólar balança com ela.

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. Os tokens de cache são detalhados no registro de cobrança de cada requisição — o console mostra 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. A capacidade compartilhada de upstream e o throttling do lado do provedor continuam valendo; se você esbarrar neles, o relay retorna 429 com um cabeçalho retry-after. Limites de RPM / TPM por chave estão planejados.

Estado e suporte

• As contas com sessão iniciada e API ativa podem ver o estado dos fornecedores em Consola → Estado do serviço e os avisos operacionais em Aviso do sistema.
• Para ajuda com conta, faturação, privacidade ou segurança, envie email para [email protected].
• Ao comunicar uma falha da API, inclua a hora UTC, endpoint, modelo, estado HTTP e o prefixo visível da chave. Nunca envie a chave completa nem o conteúdo do prompt, salvo se o suporte pedir explicitamente uma reprodução expurgada.
• O serviço funciona segundo o melhor esforço e não tem SLA. Consulte os Termos de Serviço, apenas em inglês, para disponibilidade e reembolsos, e a Política de Privacidade para o tratamento de dados.

Última revisão da documentação: 14 de julho de 2026.