Riferimento API

unbleep parla la Chat Completions API di OpenAI. Se hai già chiamato OpenAI, conosci già questa API — punta il tuo client a https://unbleep.ai/v1 e cambia la chiave.

Quickstart

Installa l'SDK OpenAI, imposta il base URL e la tua chiave, e fai una chiamata.

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)

Autenticazione

Ogni richiesta richiede un Bearer token nell'header Authorization. Le chiavi hanno un prefisso, così una chiave trapelata è subito evidente agli scanner di segreti:

• ub_live_… — produzione, addebitata sul tuo credito prepagato.
• ub_test_… — per lo sviluppo locale. Addebitata esattamente come una chiave live, alla stessa tariffa per token, sullo stesso credito prepagato; l'unica differenza è un limite di frequenza per chiave più basso (vedi Limiti di frequenza). Una chiave di test è una credenziale separata e revocabile — non un piano gratuito.

Authorization: Bearer ub_live_9f2c…

Tieni le chiavi lato server. Non distribuire mai una chiave live nel codice browser o mobile.

Modelli

Passa uno di questi ID come model. L'alias semplice punta sempre alla build più recente; anche gli ID snapshot datati sono accettati e attualmente risolvono a quella stessa build. Qualunque forma tu invii, la risposta riporta l'ID semplice — una richiesta per unbleep-250811 torna come "model": "unbleep".

Chat completions

POST /v1/chat/completions — l'endpoint principale. I body di richiesta e risposta seguono lo schema 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

Imposta "stream": true per ricevere Server-Sent Events. Ogni evento è un chat.completion.chunk con un delta; lo stream termina con un data: [DONE] letterale.

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

Reasoning

I modelli di reasoning ragionano prima di rispondere. La traccia torna come reasoning_content accanto al consueto content — su message per una chiamata normale, e su delta durante lo streaming. Il campo è presente solo quando il modello ha effettivamente prodotto una traccia, quindi trattalo come opzionale e leggi content per la risposta vera e propria.

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

I token di reasoning vengono fatturati. La traccia è output generato e viene addebitata alla normale tariffa di output del modello, che il tuo codice legga o meno il campo. Una lunga riflessione su una domanda breve è una voce reale sul tuo conto.

Invia "thinking": false per disattivare il reasoning, così il budget di completamento va alla risposta invece che alla traccia:

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

Manopola policy

Il tratto distintivo di unbleep. Il parametro opzionale policy stabilisce quanta governance viene applicata a una richiesta. Il valore predefinito è off.

• off — baseline senza filtri (predefinito). Nessun rifiuto iniettato.
• research — risponde esattamente come off. Il valore viene registrato sulla riga di utilizzo per la tua reportistica; non applica alcuno screening aggiuntivo.
• strict — confronta il testo del messaggio con la blocklist del servizio e restituisce un errore di policy in caso di corrispondenza. La blocklist è gestita dall'operatore e si applica a chiunque la attivi; non esiste una blocklist per account da configurare.

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

Errori

Gli errori usano l'envelope OpenAI, quindi la gestione degli errori esistente funziona senza modifiche.

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

Limiti di frequenza

Si applicano due limiti indipendenti, entrambi per account: una frequenza di richieste e un tetto di concorrenza.

Frequenza di richieste

60 richieste al minuto per account, misurate su una finestra scorrevole di 60 secondi. Il limite è sull'account, non sulla chiave — creare chiavi aggiuntive non compra throughput aggiuntivo, e ogni chiave che possiedi attinge alle stesse 60. Una chiave di test ha un tetto per chiave più basso di 15 richieste al minuto; conta comunque sulla stessa finestra dell'account.

Ogni risposta porta gli header standard, così puoi cadenzare le richieste senza tirare a indovinare. Riportano la finestra più vicina a fermarti:

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

x-ratelimit-reset-requests è un intero semplice — secondi interi finché la finestra libera uno slot, senza suffisso di unità. Interpretalo come numero, non come stringa di durata.

Concorrenza

Al massimo 8 richieste in corso contemporaneamente per account. Una nona richiesta concorrente viene rifiutata immediatamente con 429 e codice too_many_concurrent_requests; la risposta porta retry-after: 1. Nulla viene fatturato per una richiesta rifiutata. Una chiamata in streaming mantiene il suo slot finché lo stream non termina, quindi sono gli stream lunghi a portarti di solito al tetto.

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

Entrambi i tetti sono fissi per gli account standard — non crescono con il tuo saldo prepagato. Serve più margine? Enterprise li alza.