Avvio rapido con curl
La richiesta JSON mode più piccola funzionante è questa. Usa l'URL di base https://api.uncensoredllmapi.com/v1, il modello uncensored e la tua chiave come token bearer:
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."}
]
}'
Il messaggio dell'assistant in choices[0].message.content è una stringa che contiene un oggetto JSON. Devi comunque analizzarlo tu stesso. Non saltare l'istruzione nel prompt: la modalità JSON vincola l'output a essere un oggetto, ma non può indovinare quali chiavi vuoi. Dichiarare le chiavi, e idealmente mostrare un esempio di una riga, è ciò che ti dà una struttura stabile.
Se non hai ancora una chiave, la pagina delle chiavi API eroga $0,50 di credito di prova con un solo clic dopo la registrazione. Questo credito non richiede pagamento, dura 7 giorni ed è limitato a uno per persona.
Modalità JSON in Python con convalida
Tratta l'output del modello come qualsiasi altro input esterno. Analizzalo, controllalo contro uno schema e riprova un numero limitato di volte se fallisce. Pydantic rende questo breve:
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"))
Tre abitudini in questo snippet valgono la pena di essere copiate. Il codice controlla finish_reason prima del parsing, perché una risposta che si interrompe a max_tokens finisce a metà oggetto. Usa una temperatura moderata, poiché temperature elevate rendono più probabile un output malformato. E limita i tentativi, così un prompt errato non può girare all'infinito. Poiché le richieste fallite o rifiutate non vengono addebitate, il budget dei tentativi è una questione di latenza piuttosto che di costo.
Errori comuni nella modalità JSON
- Chiedere JSON nel prompt ma non in
response_format. Il modello spesso acconsentirà, ma potrebbe avvolgere l'oggetto in testo o in un blocco di codice. Imposta entrambi. - Impostare
max_tokenstroppo basso. Stima la risposta valida più lunga e aggiungi margine. Un lungo elenco di elementi può facilmente superare 300 token. - Aspettarsi un array di livello superiore. La modalità JSON richiede un oggetto. Se hai bisogno di un elenco, chiedi
{"items": [...]}. - Accumulare una sequenza di stop che appare nel JSON. Il parametro
stopviene passato e una stringa di stop che appare all'interno di un valore taglierà la risposta a metà. - Usare la modalità JSON con lo streaming e analizzare ogni frammento. Raccogli tutto il testo prima, poi esegui il parsing una volta alla fine.
Le impostazioni di campionamento come temperatura, top_p, seed e le penalità vengono passate. Per attività di estrazione, una temperatura bassa intorno a 0,2 e un seed fisso danno l'output più ripetibile. Per la generazione creativa come l'NPC sopra, un valore più alto va bene purché tu esegua la convalida.
Chiamata di funzioni: il ciclo completo
La chiamata di funzioni permette al modello di chiedere al tuo codice di fare qualcosa e poi continuare con il risultato. Il flusso ha quattro passaggi: dichiari le funzioni, il modello risponde con tool_calls, le esegui e invii i risultati indietro come messaggi con 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),
})
Gli argomenti arrivano come una stringa JSON, che devi analizzare, e il modello può occasionalmente produrre argomenti che non corrispondono al tuo schema. Validali prima di eseguire qualsiasi cosa con effetti collaterali. Non passarli mai a una shell, a una stringa SQL o a un percorso file senza controlli.
Il campo tool_choice ti permette di guidare il comportamento. Lascialo a "auto" e il modello decide. Nomina una funzione specifica per forzare una chiamata, utile quando vuoi un'estrazione strutturata tramite uno schema di funzione invece che la modalità JSON.
Streaming delle chiamate di funzioni in Node
Con stream: true, le chiamate di funzioni arrivano a pezzi. Ogni frammento trasporta una parte del nome della funzione o della stringa degli argomenti, indicizzati per posizione. Devi concatenare i frammenti per indice ed eseguire il parsing solo quando lo streaming termina.
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));
}
Ricorda che una richiesta in streaming occupa uno dei tuoi slot di concorrenza fino alla fine dello streaming. Una chiave completa permette 8 richieste concorrenti e 300 al minuto, una chiave di prova 2 e 60. Superare uno dei limiti restituisce HTTP 429 con il codice concurrency o rate_limited. I totali di utilizzo sono riportati alla fine dello streaming, il che è utile per registrare il costo.
Modalità JSON o schema di tool
Entrambi ti danno dati strutturati, quindi quale dovresti usare? La domanda decisiva è se il modello sta producendo dati o scegliendo un'azione.
Usa la modalità JSON quando l'output stesso è il prodotto: un foglio NPC, un elenco di tag, una classificazione con un campo di confidenza. Controlli l'intero prompt, ricevi un oggetto indietro e c'è una richiesta da pagare.
Usa i tool quando il modello deve decidere se agire, o quando sono possibili diverse azioni. Uno schema per funzione documenta il contratto, tool_choice ti permette di forzare o consentire una chiamata, e il ciclo nella sezione precedente gestisce il lavoro multi-step. Il costo è una richiesta extra per round, più le definizioni di tool conteggiate come input ogni volta.
Un percorso intermedio pratico per l'estrazione: dichiara un tool i cui parametri sono i campi che vuoi, e imposta tool_choice a quella funzione. Ottieni un JSON di argomenti che segue la forma dello schema senza scrivere l'elenco delle chiavi nel prompt. In ogni caso, convalida il risultato prima di fidarti, e registra il valore X-Request-Id di qualsiasi richiesta che ha prodotto qualcosa di inaspettato.
Quanto costa
JSON e chiamate di funzioni sono fatturati come qualsiasi altro token: $0.15 per 1M di input e $0.50 per 1M di output. Le definizioni di funzione contano come input su ogni richiesta, e ogni risultato di funzione che invii indietro si aggiunge all'input della richiesta successiva.
Esempio: un turno di assistant che usa tool con uno schema di tool di 600 token e prompt, una chiamata di modello di 150 token, poi una seconda richiesta contenente 900 token di input (i messaggi precedenti più un risultato di tool) e una risposta di 200 token.
- Richiesta uno: 600 input e 150 output. Input 600 x $0.15 / 1M = $0.00009. Output 150 x $0.50 / 1M = $0.000075. Subtotale $0.000165.
- Richiesta due: 900 input e 200 output. Input 900 x $0.15 / 1M = $0.000135. Output 200 x $0.50 / 1M = $0.0001. Subtotale $0.000235.
- Totale per il turno: $0.0004.
A quel tasso 1.000 turni costano $0.40. Il credito è prepagato in importi interi da $20 a $500 (bonus: +5% da $50, +10% da $100, +15% da $200), pagato in cripto con USDT su TRC20 o USDC su Base. Vedi la pagina prezzi per le cifre attuali.
Prossimi passi
Il riferimento per ogni campo della richiesta è nella documentazione API. Se stai preparando un'applicazione per il traffico reale, la checklist di produzione è la pagina successiva da leggere, e il supporto può aiutarti se una richiesta si comporta in modo inaspettato. Tieni a portata di mano il tuo ID richiesta, che torna nell'intestazione X-Request-Id.
Il servizio è solo testo e la finestra di contesto è di 100.000 token, incluse le tue definizioni e risultati di funzione. I contenuti sessuali che coinvolgono minorenni non sono consentiti, e questo si applica all'output strutturato e guidato da funzioni esattamente come alla chat semplice.
