Riferimento Uncensored API, Spiegato Campo per Campo

Convenzioni e trasporto

L'URL di base è https://api.uncensoredapis.com/v1. Tutti i corpi sono in JSON e UTF-8. Ogni richiesta trasporta Authorization: Bearer <key>; una chiave mancante o errata restituisce 401. Esistono solo due endpoint e qualsiasi altro percorso restituisce 404.

Metodo	Percorso	Scopo
POST	/v1/chat/completions	Genera un messaggio dell'assistente, eventualmente in streaming
GET	/v1/models	Elenca l'ID del modello che puoi richiedere

L'API è solo per il testo. Non ci sono endpoint per embedding, immagini, audio o video, né fine-tuning, ed esiste esattamente un modello, indicato come uncensored. Poiché il formato di trasmissione è compatibile con la convenzione dei completamenti conversazionali, gli SDK ufficiali Python e Node.js funzionano quando sovrascrivi base_url. La documentazione copre la configurazione iniziale; questa pagina è il manuale a livello di campo.

Campi del corpo della richiesta

La tabella elenca i campi che l'endpoint riconosce. I campi di campionamento vengono passati alla generazione invariati, quindi i valori che scegli si comportano come in qualsiasi API di tipo completamento conversazionale.

Campo	Tipo	Note
model	stringa	Sempre "uncensored".
messages	array	Oggetti ordinati con role (system, user, assistant, tool) e content.
max_tokens	intero	Limite di completamento. Predefinito 2048, massimo 32.000.
temperature	numero	Casualità. Valore più basso significa maggiore determinismo.
top_p	numero	Taglio campionamento nucleo.
stop	stringa o array	Sequenze che terminano la generazione.
stream	booleano	true attiva le risposte tramite server-sent events.
tools	array	Definizioni di funzioni nel formato standard JSON-schema.

Ecco una richiesta annotata completa. Il messaggio di sistema definisce il comportamento, il messaggio utente trasporta il compito e stop termina la generazione alla prima riga vuota.

Copycurl https://api.uncensoredapis.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a terse release-notes writer."},
      {"role": "user", "content": "Summarize: fixed login bug, added dark mode."}
    ],
    "max_tokens": 120,
    "temperature": 0.4,
    "stop": ["\n\n"]
  }'

Due regole di budget sono importanti. In primo luogo, il prompt più il completamento devono rientrare in 100.000 token, quindi una richiesta i cui token del prompt più max_tokens superano tale limite viene rifiutata con un 400. In secondo luogo, il corpo serializzato non può superare 8 MB. Se invii cronologie lunghe, riduci i turni vecchi dal tuo lato prima che si avvicinino a uno di questi due limiti.

L'oggetto di risposta

Una chiamata senza streaming restituisce un oggetto JSON. Leggila dall'alto verso il basso come segue.

Copy{
  "id": "chatcmpl-example123",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "v1.4: Login bug fixed. Dark mode added."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 14,
    "total_tokens": 52
  }
}

• id: un identificativo univoco per il completamento. Registralo accanto al tuo ID di richiesta quando devi correlare gli eventi.
• object: la costante chat.completion.
• created: timestamp Unix in secondi.
• model: ripete uncensored.
• choices: un array. Ricevi una sola voce, quindi choices[0] è la risposta. index è la sua posizione.
• choices[].message: role è assistant; content contiene il testo, oppure è null quando il modello ha restituito chiamate di funzioni invece.
• choices[].finish_reason: il motivo per cui la generazione si è arrestata; vedi la sezione successiva.
• usage: contabilizzazione dei token per la fatturazione, trattata di seguito.

Valori di finish_reason

Valuta finish_reason prima di fidarti del contenuto. Una risposta troncata e una risposta completa appaiono identiche finché non la verifichi.

Valore	Significato	Cosa deve fare il tuo codice
stop	Il modello ha raggiunto una fine naturale o ha incontrato una delle tue sequenze stop.	Usa il contenuto così com'è.
length	È stato raggiunto il limite max_tokens (o la finestra di contesto) a metà risposta.	Aumenta max_tokens, accorcia il prompt o chiedi al modello di continuare.
tool_calls	Il modello vuole eseguire una o più funzioni.	Eseguile e invia i risultati come messaggi tool.

Quando il valore è tool_calls, il messaggio appare così, con gli argomenti forniti come un JSON string che devi analizzare tu stesso:

Copy{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc1",
        "type": "function",
        "function": {"name": "get_order", "arguments": "{\"order_id\": 8841}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Avvolgi sempre json.loads o JSON.parse su arguments in un blocco di gestione degli errori, perché il JSON generato può occasionalmente essere malformato.

Il blocco usage e i relativi costi

usage riporta prompt_tokens, completion_tokens e total_tokens. Questi sono i numeri per cui il tuo saldo viene addebitato: input a $0,25 per milione di token e output a $1,00 per milione. Il saldo prepagato viene detratto per richiesta, senza abbonamento.

Un esempio pratico sotto ipotesi dichiarate: supponi che una richiesta utilizzi 2.000 token del prompt e 500 token di completamento. Il costo dell'input è 2.000 / 1.000.000 x $0,25 = $0,0005. Il costo dell'output è 500 / 1.000.000 x $1,00 = $0,0005. La richiesta ammonta a $0,0010. Questi conteggi di token sono ipotesi per i calcoli, non una misurazione di un carico di lavoro reale. La pagina dei prezzi ha i tassi in un unico posto.

Poiché i token di output costano quattro volte quanto i token di input, un max_tokens stretto è il tuo controllo dei costi più diretto.

Formato dello chunk in streaming

Imposta "stream": true e la risposta diventa text/event-stream. Ogni evento è una riga che inizia con data: seguita da JSON, separata da una riga vuota. Il tipo di oggetto cambia in chat.completion.chunk e message viene sostituito da delta.

Copydata: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"v1.4: "},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Login bug fixed."},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":38,"completion_tokens":14,"total_tokens":52}}

data: [DONE]

1. Il primo chunk di solito imposta delta.role su assistant con contenuto vuoto.
2. Gli chunk di contenuto contengono un frammento in delta.content. Concatenali in ordine di arrivo.
3. Lo chunk di chiusura del contenuto ha un delta vuoto e un finish_reason non nullo.
4. Un segmento finale con una matrice choices vuota trasporta usage. Non lo richiedi; viene aggiunto automaticamente.
5. Il letterale data: [DONE] termina lo stream.

Proteggiti da quella matrice choices vuota: indicizzare choices[0] sul segmento di utilizzo genera un errore nei cicli ingenui. L'esempio SDK di seguito lo gestisce.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.uncensoredapis.com/v1", api_key=os.environ["API_KEY"])

reason, usage = None, None
for chunk in client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Name three uses of a rubber duck in debugging."}],
    stream=True,
):
    if chunk.choices:
        piece = chunk.choices[0].delta.content
        if piece:
            print(piece, end="", flush=True)
        if chunk.choices[0].finish_reason:
            reason = chunk.choices[0].finish_reason
    if getattr(chunk, "usage", None):
        usage = chunk.usage

print("\nfinish:", reason, "| tokens:", usage.total_tokens if usage else "n/a")

Per le chiamate di strumenti in streaming, delta.tool_calls arriva in frammenti; accumula la stringa arguments per indice di chiamata e analizza una volta che finish_reason è tool_calls.

L'endpoint dei modelli

GET /v1/models richiede solo l'intestazione Bearer e restituisce un oggetto lista. Essendo presente un solo modello, data contiene una voce, uncensored. I client che popolano un menu a discesa dei modelli da questa rotta mostreranno quindi un'unica scelta.

Copycurl https://api.uncensoredapis.com/v1/models -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {"id": "uncensored", "object": "model"}
  ]
}

È anche il modo più economico per verificare una chiave: un 200 significa che la chiave è valida, un 401 significa che è errata o è stata rigenerata. Chiamare questo endpoint non genera token. Per la gestione degli errori e le regole di retry, consulta il manuale degli errori e dei limiti di richiesta.

Lista di controllo di riferimento per gli autori di client

Se stai scrivendo una libreria client o avvolgendo l'endpoint in un gateway, verifica ciascuno di questi comportamenti rispetto alla specifica sopra prima della spedizione.

1. Igiene delle intestazioni. Invia la chiave solo nell'intestazione Authorization, mai nella query string e mai registrare il valore dell'intestazione.
2. Analizza in modo difensivo. Tratta i campi extra sconosciuti nelle risposte come ignorabili. Blocca il tuo parser sui campi documentati qui piuttosto che sull'ordine esatto delle chiavi JSON.
3. Verifica finish_reason su ogni risposta. Mostra un indicatore visibile quando è uguale a length, perché gli utenti altrimenti leggono il testo tagliato come risposta completa.
4. Budget prima di inviare. Stima i token del prompt, aggiungi il tuo max_tokens e confronta la somma con 100.000. Il rifiuto locale è più veloce dell'attesa per un 400.
5. Gestisci la coda dello streaming. Prevedi un segmento con una lista choices vuota e un oggetto usage, poi [DONE]. Chiudi la connessione dopo la sentinella.
6. Registra l'utilizzo. Memorizza total_tokens per richiesta in modo da poter riconciliare la tua misurazione con il saldo prepagato in seguito.
7. Rispetta il limite massimo. L'account consente 300 richieste al minuto per chiave, quindi un gateway che distribuisce a molti utenti ha bisogno della propria coda.

Nessuno di questi passaggi dipende da un SDK del fornitore. Un client HTTP base che imposta l'intestazione Bearer e decodifica il JSON è sufficiente, e gli esempi SDK in questa pagina sono comodità, non requisiti. Abbina questo elenco di controllo alla tabella degli errori nel playbook e copri l'intero ciclo di vita della richiesta: creazione, invio, streaming, analisi, addebito e recupero.