Uncensored API Referentie, veld voor veld uitgelegd

Conventies en transport

De base URL is https://api.uncensoredapis.com/v1. Alle request bodies zijn JSON en UTF-8. Elk verzoek bevat Authorization: Bearer <key>; een ontbrekende of verkeerde key retourneert 401. Er zijn slechts twee routes; elk ander pad retourneert 404.

Methode	Pad	Doel
POST	/v1/chat/completions	Genereer een assistant bericht, optioneel gestreamd
GET	/v1/models	Lijst van model id's die je kunt aanvragen

De API is alleen voor tekst. Er zijn geen embeddings, afbeeldingen, audio of video routes en geen fine-tuning, en er is precies één model, aangesproken als uncensored. Omdat de wire format compatibel is met de chat completions conventie, werken de officiële Python en Node SDKs wanneer je base_url overschrijft. De docs dekken de eerste keer opzetten; deze pagina is de veld-niveau metgezel.

Request body velden

De tabel somt de velden op die de endpoint begrijpt. Sampling velden worden ongewijzigd doorgegeven aan de generatie, dus de waarden die je kiest gedragen zich zoals in een chat-completions-style API.

Veld	Type	Opmerkingen
model	string	Altijd "uncensored".
messages	array	Gesorteerde objecten met role (system, user, assistant, tool) en content.
max_tokens	integer	Completion cap. Standaard 2048, maximum 32.000.
temperature	number	Willekeurigheid. Lager is deterministischer.
top_p	number	Nucleus sampling cutoff.
stop	string of array	Sequenties die generatie beëindigen.
stream	boolean	true schakelt het antwoord om naar server-sent events.
tools	array	Functiedefinities in het standaard JSON-schema-formaat.

Hier is een volledig geannoteerd verzoek. De systeemboodschap bepaalt het gedrag, de gebruikersboodschap bevat de taak en stop stopt de generatie bij de eerste lege regel.

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

Twee budgetregels zijn belangrijk. Ten eerste moeten de prompt en de completion samen binnen 100.000 tokens passen, dus een verzoek waarbij de prompttokens plus max_tokens die grens overschrijden, wordt afgewezen met een 400. Ten tweede mag de geserialiseerde body niet groter zijn dan 8 MB. Als je lange geschiedenisberichten verstuurt, knip dan oude draadjes aan je eigen kant voordat ze een van beide limieten naderen.

Het responsobject

Een niet-streamende aanroep retourneert één JSON-object. Lees het van boven naar beneden als volgt.

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: een unieke identificatie voor de completion. Log deze naast je eigen request-id als je gebeurtenissen aan elkaar moet koppelen.
• object: de constante chat.completion.
• created: Unix-timestamp in seconden.
• model: echo van uncensored.
• choices: een array. Je ontvangt één entry, dus choices[0] is het antwoord. index is de positie.
• choices[].message: role is assistant; content bevat de tekst, of is null als het model tool calls heeft geretourneerd.
• choices[].finish_reason: waarom de generatie stopte; zie de volgende sectie.
• usage: tokenadministratie voor facturatie, hieronder behandeld.

finish_reason-waarden

Neem een beslissing op basis van finish_reason voordat je de content vertrouwt. Een afgekapt antwoord en een compleet antwoord zien er hetzelfde uit totdat je het controleert.

Waarde	Betekenis	Wat je code moet doen
stop	Het model bereikte een natuurlijk einde of raakte een van je stop-sequenties.	Gebruik de content zoals die is.
length	De max_tokens-limiet (of het contextvenster) is bereikt tijdens het antwoord.	Verhoog max_tokens, maak de prompt korter of vraag het model om door te gaan.
tool_calls	Het model wil een of meer functies uitvoeren.	Voer ze uit en stuur resultaten terug als tool-berichten.

Als de waarde tool_calls is, ziet de message er als volgt uit, met argumenten geleverd als een JSON string die je zelf moet parseren:

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"
  }]
}

Wikkel json.loads of JSON.parse op arguments altijd in foutafhandeling, omdat gegenereerde JSON soms onjuist kan zijn.

De usage-blok en wat het kost

usage rapporteert prompt_tokens, completion_tokens en total_tokens. Dit zijn de getallen waar je saldo tegen wordt verrekend: invoer tegen $0,25 per miljoen tokens en uitvoer tegen $1,00 per miljoen. Prepaid tegoed wordt per verzoek afgeschreven, zonder abonnement.

Een uitgewerkt voorbeeld onder gestelde aannames: stel dat een verzoek 2.000 prompttokens en 500 completiontokens gebruikt. Invoerkosten zijn 2.000 / 1.000.000 x $0,25 = $0,0005. Uitvoerkosten zijn 500 / 1.000.000 x $1,00 = $0,0005. Het verzoek komt in totaal op $0,0010. Deze tokenaantallen zijn aannames voor de rekenkunde, geen meting van een echte workload. De prijzenpagina heeft de tarieven op één plek.

Omdat uitvoertokens vier keer zo duur zijn als inputtokens, is een strakke max_tokens je meest directe manier om kosten te beheersen.

Streaming chunk-formaat

Stel "stream": true in en de respons wordt text/event-stream. Elk evenement is een regel die begint met data: gevolgd door JSON, gescheiden door een lege regel. Het objecttype verandert in chat.completion.chunk en message wordt vervangen door 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. Het eerste chunk stelt meestal delta.role in op assistant met lege content.
2. Content-chunks bevatten een fragment in delta.content. Plak ze in de volgorde van aankomst aan elkaar.
3. Het slotchunk van de content heeft een lege delta en een niet-null finish_reason.
4. Een laatste chunk met een lege choices-array bevat usage. Je vraagt het niet expliciet aan; het wordt automatisch toegevoegd.
5. De letterlijke data: [DONE] beëindigt de stream.

Bescherm je tegen die lege choices-array: indexeren op choices[0] in het usage-chunk geeft een fout in eenvoudige loops. De SDK-voorbeeld hieronder verwerkt dit.

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

Voor gestreamde tool calls komt delta.tool_calls in fragmenten binnen; accumuleer de arguments string per call index en parse eenmaal wanneer finish_reason tool_calls is.

De models endpoint

GET /v1/models vereist alleen de Bearer-header en retourneert een lijstobject. Omdat er maar één model is, bevat data één entry, uncensored. Clients die een model-dropdown vullen via deze route zien dus maar één keuze.

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

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

Het is ook de goedkoopste manier om een sleutel te verifiëren: een 200 betekent dat de sleutel geldig is, een 401 betekent dat deze onjuist is of opnieuw is gegenereerd. Het aanroepen van deze route genereert geen tokens. Zie voor statusafhandeling en retry-regels het errors and rate limits playbook.

Referentiechecklist voor clientauteurs

Als je een clientbibliotheek schrijft of de endpoint in een gateway wilt verpakken, controleer dan elk van deze gedragingen tegen de specificatie hierboven voordat je levert.

1. Header hygiene. Stuur de key alleen in de Authorization header, nooit in de query string, en log de header waarde nooit.
2. Parse defensief. Behandel onbekende extra velden in responsen als negeerbaar. Pin je parser op de velden die hier gedocumenteerd zijn, niet op de exacte JSON-volgorde.
3. Controleer finish_reason op elk antwoord. Toon een zichtbare indicator als deze gelijk is aan length, omdat gebruikers anders afgekapt tekst lezen als het volledige antwoord.
4. Budget voor het verzenden. Schat prompt tokens, tel je max_tokens erbij op en vergelijk de som met 100.000. Lokaal afwijzen is sneller dan wachten op een 400.
5. Verwerk de streamtail. Verwacht een chunk met een lege choices lijst en een usage object, gevolgd door [DONE]. Sluit de verbinding na de sentinel.
6. Log usage. Sla total_tokens per verzoek op zodat je je eigen metering later kunt afstemmen op het prepaid tegoed.
7. Respecteer het plafond. Het account staat 300 verzoeken per minuut per sleutel toe, dus een gateway die veel gebruikers bedient, heeft een eigen wachtrij nodig.

Geen van deze stappen is afhankelijk van een vendor SDK. Een gewone HTTP client die de Bearer header zet en JSON decodeert is voldoende, en de SDK voorbeelden op deze pagina zijn gemakken, geen vereisten. Combineer deze checklist met de error tabel in de playbook en je dekt de hele request lifecycle: build, send, stream, parse, account en recover.