Configura la shell e verifica l'endpoint
Ottieni una chiave dalla pagina delle chiavi API, poi esportala insieme all'URL base così non devi incollare i segreti in ogni comando.
export API_KEY="paste-your-key-here"
export BASE="https://api.uncensoredllmapi.com/v1"
Ogni richiesta invia la chiave come bearer token nell'intestazione Authorization. I corpi delle richieste sono JSON, quindi aggiungi Content-Type: application/json quando fai un POST. La dimensione massima del corpo è 8 MB, il che conta solo se incolli documenti molto grandi nel prompt.
Gli esempi usano le virgolette singole di una shell Unix. Su Windows PowerShell, metti il JSON in un file e passalo con --data @body.json per evitare problemi di quoting.
Il controllo di integrità più economico è un GET che elenca i modelli. Conferma la chiave e l'URL e non costa nulla.
curl -s "$BASE/models" \
-H "Authorization: Bearer $API_KEY"
L'array data nella risposta dovrebbe includere l'ID uncensored. Un 401 significa che la chiave manca o è digitata male. Se curl non riesce a connettersi affatto, controlla l'host in $BASE e assicurati che finisca con /v1 senza percorsi extra.
1. Invia un completamento della chat
Questa è la richiesta che ogni client compatibile con OpenAI invia sotto il cofano.
curl -s "https://api.uncensoredllmapi.com/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Give me three names for a fantasy tavern."}
],
"temperature": 0.8,
"max_tokens": 200
}'
La risposta è JSON. Il testo si trova a choices[0].message.content e i conteggi dei token sono in usage. Fai pipe dell'output attraverso jq -r '.choices[0].message.content' se hai jq installato e vuoi solo il testo. Il campo max_tokens è opzionale; omettilo e il completamento potrebbe usare tutto ciò che resta della finestra da 100.000 token.
L'endpoint più recente POST /v1/responses è disponibile anche se il tuo client utilizza quel formato. Per l'elenco completo dei parametri, consulta la documentazione.
2. Esegui lo streaming della risposta
Aggiungi "stream": true e dì a curl di non fare buffering con -N. I token verranno stampati mentre vengono generati.
curl -N "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to ten in words."}]
}'
Ogni riga inizia con data: e contiene un piccolo chunk JSON con un delta. Gli eventi finali contengono l'uso e lo streaming termina con data: [DONE]. Senza -N curl attende un buffer completo e l'output sembra arrivare tutto insieme. Nota che una richiesta in streaming mantiene occupato uno slot di concorrenza fino alla fine.
3. Richiedi JSON
Per un output che uno script deve analizzare, attiva la modalità JSON con response_format. Indica la parola JSON nel prompt in modo che il modello sappia che forma ti aspetti.
curl -s "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [{"role": "user",
"content": "Return JSON with keys name and level for a fantasy character."}]
}' | jq -r '.choices[0].message.content | fromjson'
Il filtro finale fromjson analizza la stringa dentro content, quindi jq fallisce rumorosamente se il modello ha restituito qualcosa che non è JSON valido. Questo lo rende un test rapido utile. Altri pattern sono nella pagina sulla modalità JSON.
4. Prova una chiamata di funzione
La chiamata di funzioni permette al modello di chiedere al tuo codice di eseguire una funzione. Descrivi la funzione in un array tools e se il modello decide di usarla, la risposta contiene una voce tool_calls invece del testo.
curl -s "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is the weather in Oslo?"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}],
"tool_choice": "auto"
}' | jq '.choices[0].message.tool_calls'
Dovresti ottenere un nome di funzione e una stringa JSON di argomenti. Il tuo codice esegue la funzione, poi invia una seconda richiesta che ripete i messaggi precedenti, aggiunge il messaggio dell'assistant con la chiamata di funzione e aggiunge un messaggio con role: "tool" contenente il risultato. Il modello scrive poi la risposta finale.
5. Controlla intestazioni e saldo
Aggiungi -i per vedere le intestazioni di risposta insieme al corpo. Troverai X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency.
curl -s -i "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"ping"}],"max_tokens":5}' \
| grep -i "^x-"
curl -s "$BASE/balance" -H "Authorization: Bearer $API_KEY"
La seconda chiamata restituisce il tuo credito direttamente. Gli strumenti compatibili con OpenAI possono usare GET /v1/dashboard/billing/credit_grants invece. Una richiesta minuscola come quella sopra costa una frazione di centesimo: con 10 token di input e 5 token di output il prezzo è 10 x 0,15 / 1.000.000 + 5 x 0,50 / 1.000.000 = $0,000004. Vedi la pagina dei prezzi per i tassi.
Script di smoke-test riutilizzabile
Una volta che ti fidi delle chiamate singole, avvolgile in uno script breve che puoi eseguire dopo qualsiasi deploy, rotazione della chiave o modifica di rete. Fallisce al primo problema, così vedi esattamente quale passaggio si è rotto.
set -euo pipefail
BASE="https://api.uncensoredllmapi.com/v1"
echo "models:"
curl -sf "$BASE/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[].id'
echo "chat:"
curl -sf "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say ok."}],"max_tokens":5}' \
| jq -r '.choices[0].message.content'
echo "balance:"
curl -sf "$BASE/balance" -H "Authorization: Bearer $API_KEY"
Il flag -f fa uscire curl con un errore in caso di fallimenti HTTP, e set -e ferma lo script lì. Mettilo in un lavoro cron o in un passaggio CI se esegui un servizio sopra questa API e vuoi un avviso precoce quando qualcosa cambia. Tieni la chiave in un archivio segreti o variabile d'ambiente, mai nel file dello script stesso.
Quando vari la richiesta, prova un'impostazione alla volta: temperature per la casualità, top_p per il campionamento del nucleo, stop per sequenze di fine personalizzate e seed per output ripetibili. Tutti vengono passati al modello, così puoi confrontare il loro effetto dalla stessa cronologia del terminale.
Leggere gli errori da curl
| Codice | Causa probabile | Soluzione |
|---|---|---|
| 401 | Chiave mancante o errata | Controlla l'intestazione Authorization e che $API_KEY sia esportata |
| 400 | JSON malformato o campo errato | Convalida il corpo con jq . prima di inviare |
429, codice rate_limited | Più di 300 richieste al minuto (60 con una chiave di prova) | Rallenta il tuo loop |
429, codice concurrency | Più di 8 richieste simultanee (2 con una chiave di prova) | Esegui meno lavori in parallelo |
429 con Retry-After: 5 | Sovraccarico temporaneo | Attendi 5 secondi e ritenta |
Aggiungi -w "\n%{http_code}\n" per stampare il codice di stato dopo il corpo, così eviti di indovinare. I corpi di errore sono in JSON con un messaggio e un codice, quindi jq .error li mostra in modo pulito. Se vedi un 429 in un loop, non riprovare immediatamente; una pausa di pochi secondi permette alla finestra del minuto e agli slot di concorrenza di svuotarsi, e un loop di retry stretto ti mantiene solo sopra il limite. Una chiave di prova ha limiti più stretti rispetto a una chiave completa, quindi uno script che funziona dopo la tua prima ricarica potrebbe fallire con il credito di prova se esegue lavori in parallelo. Una volta che le richieste si comportano correttamente, passa a un SDK; lo stesso URL e il nome del modello vengono mantenuti invariati. I nuovi account possono richiedere $0,50 di credito di prova con un clic, sufficienti per centinaia di chiamate di test piccole. Le ricariche successive partono da $20 e sono pagate in cripto (USDT su TRC20 o USDC su Base).
