NL ▾
API-sleutel aanvragen
OpenAI-compatibele ongecensureerde API voor ontwikkelaars.Bijgewerkt

Uncensored LLM API JSON-modus en toolaanroepen

De instelling voor JSON-modus van de ongecensureerde llm api is dezelfde die je al kent van OpenAI-clients: stuur response_format met type json_object en het antwoord komt terug als een JSON-object. Deze pagina behandelt dat, plus toolaanroepen, met code die je tegen het live endpoint kunt uitvoeren.

Gloeiende haken samengesteld uit kubussen met een mechanische arm, die gestructureerde JSON-uitvoer en toolaanroepen illustreren

Snelstart met curl

Het kleinste werkende JSON-modus-verzoek ziet er als volgt uit. Het gebruikt de basis-URL https://api.uncensoredllmapi.com/v1, het model uncensored en je sleutel als bearer-token:

curl https://api.uncensoredllmapi.com/v1/chat/completions   -H "Authorization: Bearer $UNCENSORED_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Reply only with a JSON object."},
      {"role": "user", "content": "Create a tavern NPC with keys name, trade and rumour."}
    ]
  }'

Het assistant-bericht in choices[0].message.content is een string die een JSON-object bevat. Je moet het nog steeds zelf parseren. Sla de instructie in de prompt niet over: JSON-modus beperkt de uitvoer tot een object, maar het kan niet raden welke sleutels je wilt. Het noemen van de sleutels, en bij voorkeur het tonen van een voorbeeld op één regel, zorgt voor een stabiele structuur.

Heb je nog geen sleutel? De API-sleutelpagina geeft na het aanmaken van je account met één klik $0,50 aan proeftegoed. Dit tegoed vereist geen betaling, is 7 dagen geldig en is beperkt tot één per persoon.

JSON-modus in Python met validatie

Behandel modeluitvoer als elke andere externe input. Parse het, controleer het tegen een schema en probeer het een beperkt aantal keren opnieuw als het mislukt. Pydantic maakt dit kort:

import json, os
from openai import OpenAI
from pydantic import BaseModel, ValidationError

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

class Npc(BaseModel):
    name: str
    trade: str
    rumour: str

SYSTEM = (
    "Reply only with a JSON object with exactly these keys: "
    "name, trade, rumour. Each value is a string."
)

def make_npc(setting, tries=3):
    for _ in range(tries):
        r = client.chat.completions.create(
            model="uncensored",
            response_format={"type": "json_object"},
            messages=[
                {"role": "system", "content": SYSTEM},
                {"role": "user", "content": f"Setting: {setting}"},
            ],
            temperature=0.7,
            max_tokens=300,
        )
        choice = r.choices[0]
        if choice.finish_reason == "length":
            continue           # cut off, so the JSON is incomplete
        try:
            return Npc(**json.loads(choice.message.content))
        except (json.JSONDecodeError, ValidationError, TypeError):
            continue
    raise RuntimeError("no valid JSON after retries")

print(make_npc("a river port in a plague year"))

Drie gewoontes in die code snippet zijn het waard om te kopiëren. De code controleert finish_reason voordat het parseren begint, omdat een antwoord dat stopt bij max_tokens midden in een object eindigt. Het gebruikt een gematigde temperatuur, omdat hoge temperaturen de kans op onjuiste uitvoer vergroten. En het beperkt het aantal pogingen, zodat een slechte prompt niet oneindig kan doorgaan. Omdat mislukte of geweigerde verzoeken niet worden aangerekend, is het budget voor herhaling een kwestie van latentie en geen van kosten.

Veelgemaakte fouten met JSON-modus

  • Om JSON in de prompt te vragen, maar niet in response_format. Het model zal vaak gehoorzamen, maar het kan het object in tekst of een code fence verpakken. Stel beide in.
  • Het instellen van max_tokens te laag. Schat het langste geldige antwoord en voeg marge toe. Een lange lijst met items kan snel meer dan 300 tokens overschrijden.
  • Verwachten van een array op het hoogste niveau. JSON-modus vraagt om een object. Als je een lijst nodig hebt, vraag dan om {"items": [...]}.
  • Het stapelen van een stopsequentie die in de JSON voorkomt. De stop parameter wordt doorgegeven, en een stopstring die binnen een waarde voorkomt, zal het antwoord kort afsluiten.
  • JSON-modus gebruiken met streaming en elk fragment parseren. Verzamel eerst de volledige tekst en parseer deze daarna eenmaal aan het einde.

Instellingen voor sampling zoals temperatuur, top_p, seed en de straffactoren worden doorgegeven. Voor extractietaken zorgen een lage temperatuur van ongeveer 0,2 en een vaste seed voor de meest reproduceerbare uitvoer. Voor creatieve generatie, zoals de NPC hierboven, is een hogere waarde prima zolang je maar valideert.

Toolaanroepen: de volledige lus

Toolaanroepen stellen het model in staat je code iets te laten doen en vervolgens door te gaan met het resultaat. De flow heeft vier stappen: je declareert tools, het model antwoordt met tool_calls, je voert ze uit en je stuurt de resultaten terug als berichten met role: "tool".

import json, os
from openai import OpenAI

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

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_inventory",
        "description": "Return the stock count for an item in the shop.",
        "parameters": {
            "type": "object",
            "properties": {"item": {"type": "string"}},
            "required": ["item"],
        },
    },
}]

def lookup_inventory(item):
    stock = {"healing potion": 4, "rope": 12}
    return {"item": item, "count": stock.get(item.lower(), 0)}

messages = [{"role": "user", "content": "Do you still have healing potions?"}]

for _ in range(4):                      # hard cap on tool rounds
    r = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools, tool_choice="auto"
    )
    msg = r.choices[0].message
    if not msg.tool_calls:
        print(msg.content)
        break
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = lookup_inventory(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

De argumenten komen binnen als een JSON-string die je moet parseren, en het model kan af en toe argumenten produceren die niet overeenkomen met je schema. Valideer ze voordat je iets uitvoert met neveneffecten. Geef ze nooit door aan een shell, een SQL-string of een bestandspad zonder controles.

Het veld tool_choice stelt je in staat het gedrag te sturen. Laat het op "auto" staan en het model beslist. Noem een specifieke functie om een aanroep af te dwingen, wat handig is wanneer je gestructureerde extractie wilt via een toolschema in plaats van JSON-modus.

Gestreamde toolaanroepen in Node

Met stream: true komen toolaanroepen in stukken binnen. Elk fragment bevat een deel van de functienaam of de argumentenreeks, geïndexeerd op positie. Je moet de fragmenten per index aan elkaar plakken en pas parseren als de stream eindigt.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uncensoredllmapi.com/v1",
  apiKey: process.env.UNCENSORED_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Check stock for rope." }],
  tools: [{
    type: "function",
    function: {
      name: "lookup_inventory",
      description: "Return the stock count for an item.",
      parameters: {
        type: "object",
        properties: { item: { type: "string" } },
        required: ["item"],
      },
    },
  }],
});

const calls = [];
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;
  for (const tc of delta?.tool_calls ?? []) {
    const slot = (calls[tc.index] ??= { id: "", name: "", args: "" });
    if (tc.id) slot.id = tc.id;
    if (tc.function?.name) slot.name += tc.function.name;
    if (tc.function?.arguments) slot.args += tc.function.arguments;
  }
}

for (const c of calls) {
  console.log(c.name, JSON.parse(c.args));
}

Onthoud dat een gestreamd verzoek één van je concurrency-slots vasthoudt tot de stream eindigt. Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 per minuut toe, een trialsleutel 2 en 60. Het raken van een van beide geeft HTTP 429 met de code concurrency of rate_limited. Gebruikstotalen worden gemeld aan het einde van de stream, wat handig is voor het loggen van kosten.

JSON-modus of een toolschema

Beide geven je gestructureerde data, dus welke moet je gebruiken? De beslissende vraag is of het model data produceert of een actie kiest.

Gebruik JSON-modus wanneer de uitvoer zelf het product is: een NPC-blad, een lijst met tags, een classificatie met een confidence-veld. Je beheert de hele prompt, je krijgt één object terug en er is één verzoek om te betalen.

Gebruik tools wanneer het model moet beslissen of het moet handelen, of wanneer verschillende acties mogelijk zijn. Een schema per functie documenteert het contract, tool_choice stelt je in staat een aanroep af te dwingen of toe te staan, en de lus in de vorige sectie behandelt multi-step taken. De kosten zijn een extra verzoek per ronde, plus de tooldefinities die elke keer als input worden meegeteld.

Een praktische middenweg voor extractie: declareer één tool waarvan de parameters de velden zijn die je wilt, en stel tool_choice in op die functie. Je krijgt argumenten-JSON die de vorm van je schema volgt zonder de lijst met sleutels in de prompt te schrijven. Hoe dan ook, valideer het resultaat voordat je het vertrouwt, en log de X-Request-Id waarde van elk verzoek dat iets onverwachts produceerde.

Wat het kost

JSON en toolaanroepen worden gefactureerd als elke andere token: $0,15 per 1M input en $0,50 per 1M output. Tooldefinities tellen als input bij elk verzoek, en elk toolresultaat dat je terugstuurt voegt toe aan de input van het volgende verzoek.

Voorbeeld: een tool-gebruikende assistant-beurt met een 600-token toolschema en prompt, een 150-token modelaanroep, dan een tweede verzoek met 900 input tokens (de eerdere berichten plus een toolresultaat) en een 200-token antwoord.

  • Verzoek één: 600 input en 150 output. Input 600 x $0,15 / 1M = $0,00009. Output 150 x $0,50 / 1M = $0,000075. Subtotaal $0,000165.
  • Verzoek twee: 900 input en 200 output. Input 900 x $0,15 / 1M = $0,000135. Output 200 x $0,50 / 1M = $0,0001. Subtotaal $0,000235.
  • Totaal voor de beurt: $0.0004.

Bij dat tarief kosten 1.000 beurten $0,40. Het tegoed is prepaid in vaste bedragen van $20 tot $500 (bonus: +5% vanaf $50, +10% vanaf $100, +15% vanaf $200), betaald in crypto met USDT op TRC20 of USDC op Base. Zie de prijzenpagina voor de huidige cijfers.

Waar je nu naartoe kunt

Referentie voor elk verzoekveld staat in de API-documentatie. Als je een applicatie voorbereidt voor echt verkeer, is de productiechecklist de volgende pagina om te lezen, en ondersteuning kan helpen als een verzoek zich onverwacht gedraagt. Houd je request ID bij, die terugkomt in de X-Request-Id header, paraat.

De service is alleen tekst en het contextvenster is 100.000 tokens, inclusief je tooldefinities en -resultaten. Seksuele inhoud met minderjarigen is niet toegestaan, en dat geldt voor gestructureerde en door tools gestuurde uitvoer precies zo goed als voor gewone chat.

Vragen en antwoorden

Garandeert JSON-modus mijn exacte schema?

Nee. Het maakt het antwoord tot een JSON-object, maar de sleutels komen uit je prompt. Valideer het resultaat met een schemabibliotheek en probeer opnieuw als het mislukt.

Hoe stuur ik toolresultaten terug?

Voeg het assistant-bericht toe dat tool_calls bevat, en voeg vervolgens één bericht per aanroep toe met role tool, de bijbehorende tool_call_id en het resultaat als string.

Kan ik tool calls streamen?

Ja. Als stream op true staat, komen de tool_calls gefragmenteerd binnen. Concateneer de strings voor de naam en argumenten per index en parse ze eenmaal als de stream eindigt.

Worden ongeldige JSON-antwoorden aangerekend?

Een voltooid antwoord wordt gefactureerd, zelfs als je parser het verwerpt. Mislukte of geweigerde verzoeken worden niet in rekening gebracht.

Je sleutel is nog maar één formulier verwijderd

Maak een account aan, kopieer de sleutel, pas de base URL aan. Dat is de hele setup.