Referência da API

O unbleep fala a API Chat Completions da OpenAI. Se você já chamou a OpenAI antes, já conhece esta API — aponte seu cliente para https://unbleep.ai/v1 e troque a chave.

Início rápido

Instale o SDK da OpenAI, defina a URL base e a sua chave, e faça uma chamada.

from openai import OpenAI

client = OpenAI(
    base_url="https://unbleep.ai/v1",
    api_key="ub_live_9f2c…",
)

resp = client.chat.completions.create(
    model="unbleep",
    messages=[{"role": "user", "content": "Say hello."}],
)
print(resp.choices[0].message.content)

Autenticação

Toda requisição precisa de um token Bearer no cabeçalho Authorization. As chaves têm um prefixo para que um vazamento seja óbvio para scanners de segredos:

• ub_live_… — produção, cobrada do seu crédito pré-pago.
• ub_test_… — para desenvolvimento local. Cobrada exatamente como uma chave live, à mesma tarifa por token, do mesmo crédito pré-pago; a única diferença é um limite de requisições por chave mais baixo (veja Limites de requisições). Uma chave de teste é uma credencial separada e revogável — não um nível gratuito.

Authorization: Bearer ub_live_9f2c…

Mantenha as chaves no servidor. Nunca envie uma chave live em código de navegador ou mobile.

Modelos

Passe um destes IDs como model. O alias simples sempre aponta para o build mais recente; os IDs de snapshot datados também são aceitos e hoje resolvem para esse mesmo build. Seja qual for a forma enviada, a resposta informa o ID simples — uma requisição para unbleep-250811 volta como "model": "unbleep".

Chat completions

POST /v1/chat/completions — o endpoint principal. Os corpos de requisição e resposta seguem o esquema da OpenAI.

curl https://unbleep.ai/v1/chat/completions \
  -H "Authorization: Bearer ub_live_9f2c…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "unbleep",
    "messages": [
      {"role": "system", "content": "You are terse."},
      {"role": "user", "content": "Explain abliteration in one line."}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

{
  "id": "chatcmpl_a1b2c3",
  "object": "chat.completion",
  "model": "unbleep",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 }
}

Streaming

Defina "stream": true para receber Server-Sent Events. Cada evento é um chat.completion.chunk com um delta; o stream termina com um data: [DONE] literal.

data: {"choices":[{"delta":{"content":"Ab"}}]}
data: {"choices":[{"delta":{"content":"literation"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

Raciocínio

Modelos de raciocínio pensam antes de responder. O rastro volta como reasoning_content ao lado do content habitual — em message numa chamada normal, e em delta durante o streaming. O campo só está presente quando o modelo realmente produziu um rastro, então trate-o como opcional e leia content para a resposta em si.

{
  "index": 0,
  "message": {
    "role": "assistant",
    "reasoning_content": "The question asks for one line, so…",
    "content": "…"
  },
  "finish_reason": "stop"
}

Tokens de raciocínio são cobrados. O rastro é saída gerada e é cobrado à tarifa normal de saída do modelo, independentemente de o seu código ler o campo ou não. Uma deliberação longa sobre uma pergunta curta é uma linha real na sua fatura.

Envie "thinking": false para desligar o raciocínio, de modo que o orçamento da conclusão vá para a resposta em vez do rastro:

{
  "model": "unbleep",
  "messages": […],
  "thinking": false
}

Seletor de política

O diferencial do unbleep. O parâmetro opcional policy define quanta governança roda em uma requisição. O padrão é off.

• off — linha de base sem filtro (padrão). Nenhuma recusa injetada.
• research — responde exatamente como off. O valor é registrado na linha de uso para o seu próprio relatório; não aplica nenhuma triagem extra.
• strict — verifica o texto da mensagem contra a lista de bloqueio do serviço e retorna um erro de política quando há correspondência. A lista é mantida pelo operador e vale para todos que optam por ela; não há lista de bloqueio por conta para configurar.

{
  "model": "unbleep",
  "messages": […],
  "policy": "research"
}

Erros

Os erros usam o envelope da OpenAI, então o tratamento de erros existente funciona sem mudanças.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "Incorrect API key provided."
  }
}

Limites de requisições

Dois limites independentes se aplicam, ambos por conta: uma taxa de requisições e um teto de concorrência.

Taxa de requisições

60 requisições por minuto por conta, medidas em uma janela deslizante de 60 segundos. O limite é da conta, não da chave — criar chaves extras não compra mais vazão, e toda chave sua consome das mesmas 60. Uma chave de teste tem um teto por chave mais baixo, de 15 requisições por minuto; ela ainda conta na mesma janela da conta.

Toda resposta traz os cabeçalhos padrão para você ritmar as requisições sem adivinhar. Eles informam a janela que estiver mais perto de te barrar:

x-ratelimit-limit-requests: 60
x-ratelimit-remaining-requests: 58
x-ratelimit-reset-requests: 43

x-ratelimit-reset-requests é um inteiro puro — segundos inteiros até a janela liberar uma vaga, sem sufixo de unidade. Interprete como número, não como string de duração.

Concorrência

No máximo 8 requisições em andamento ao mesmo tempo por conta. Uma nona requisição simultânea é rejeitada na hora com 429 e código too_many_concurrent_requests; a resposta traz retry-after: 1. Nada é cobrado por uma requisição rejeitada. Uma chamada em streaming segura sua vaga até o stream terminar, então streams longos são o que normalmente te leva ao teto.

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_concurrent_requests",
    "message": "Too many concurrent requests for this account (limit 8)."
  }
}

Os dois tetos são fixos para contas padrão — não escalam com o seu saldo pré-pago. Precisa de mais folga? O Enterprise os eleva.