Prima di eseguire qualsiasi cosa
Ti serve solo una chiave. Creane una nella pagina delle chiavi API; i nuovi account possono richiedere $0,50 di credito di prova con un clic, senza carta. Esportala così gli esempi possono leggerla:
export API_KEY="YOUR_KEY"
pip install openai
npm install openai
L'API segue il formato delle chat completions di OpenAI. Espone POST /v1/chat/completions e GET /v1/models, accetta Authorization: Bearer e serve un singolo modello con l'ID uncensored. Questo modello è un modello a pesi aperti gestito da un provider indipendente e ottimizzato per rispondere senza rifiuti di contenuti per un uso adulto legale. Non è l'API ufficiale di alcun fornitore di modelli. Gestisce solo testo: nessuna immagine, audio, embedding o fine-tuning.
Gli esempi seguenti vanno dalla chiamata più semplice alla chiamata di funzioni. Se ti serve solo il controllo più breve possibile per verificare che la tua chiave funzioni, il primo comando curl è sufficiente.
Una prima richiesta con curl e i parametri rilevanti
curl https://api.glmapikey.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": "What is a mutex, in one sentence?"}
],
"temperature": 0.3,
"max_tokens": 80
}'
La risposta è un oggetto JSON con choices[0].message.content che contiene la risposta e un oggetto usage con prompt_tokens e completion_tokens. Le intestazioni di risposta includono X-Request-Id, X-Balance-USD e le due intestazioni X-RateLimit-Limit. Aggiungi -i a curl per vederle.
I campi temperature, top_p, stop, seed e le penalità di presenza e frequenza vengono passati al modello. max_tokens è facoltativo. Senza di esso, il completamento può utilizzare tutto ciò che rimane della finestra da 100.000 token dopo il tuo prompt.
Il corpo delle chat completions ha molti campi facoltativi, ma cinque fanno la maggior parte del lavoro. Tutti vengono passati al modello.
| Campo | Cosa fa | Uso tipico |
|---|---|---|
temperature | Valori più alti danno una formulazione più varia | 0,2 per l'estrazione, 0,8 per la narrativa |
top_p | Limita il campionamento ai token più probabili | Lascia al valore predefinito a meno che non lo regoli |
stop | Interrompe la risposta quando appare una stringa | Taglia a un delimitatore come una riga vuota |
seed | Rende il campionamento ripetibile su base best-effort | Confronto tra due versioni di prompt |
presence_penalty, frequency_penalty | Sconsiglia la ripetizione dei token | Valori piccoli come 0,3 quando il testo ripete |
Modifica un valore alla volta e mantieni lo stesso prompt, altrimenti non puoi sapere quale modifica ha aiutato. Per tutto ciò che alimenta il codice, come classificazione o estrazione, usa una temperatura bassa e un seed fisso in modo da poter rieseguire un test e vedere lo stesso risultato. Per la scrittura creativa, aumenta la temperatura e lascia che le penalità gestiscano la ripetizione.
Il campo max_tokens è facoltativo qui. Se lo lasci vuoto, la risposta potrebbe utilizzare tutto lo spazio rimasto nella finestra da 100.000 token, il che raramente è ciò che vuoi per una risposta di una riga. Impostalo ogni volta che sai quanto dovrebbe essere lunga la risposta.
Python: una conversazione con memoria
L'API è stateless, quindi gestisci tu la conversazione e inviala ogni volta. Questo ciclo mantiene un elenco di messaggi e aggiunge entrambi i lati:
from openai import OpenAI
client = OpenAI(
base_url="https://api.glmapikey.com/v1",
api_key="YOUR_KEY",
)
messages = [{"role": "system", "content": "You are a helpful assistant."}]
while True:
user = input("you> ")
if not user:
break
messages.append({"role": "user", "content": user})
resp = client.chat.completions.create(model="uncensored", messages=messages)
reply = resp.choices[0].message.content
messages.append({"role": "assistant", "content": reply})
print("bot>", reply)
Poiché ogni chiamata rispedisce l'elenco completo, i token di input crescono con la lunghezza della chat. A $0,15 per 1M token di input è economico, ma si accumula nelle sessioni lunghe, quindi elimina i messaggi vecchi una volta che la conversazione supera la dimensione che vuoi pagare. La pagina dei prezzi ha esempi funzionanti.
Streaming in Python e Node
Imposta stream: true e il server invia i token man mano che vengono prodotti, tramite eventi inviati dal server. In Python:
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write four lines about the sea."}],
stream=True,
)
text = ""
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
text += piece
print(piece, end="", flush=True)
if getattr(chunk, "usage", None):
print("\ntokens:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)
Lo streaming termina con le informazioni di utilizzo, motivo per cui il ciclo le controlla. La stessa cosa in Node:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.glmapikey.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Write four lines about the sea." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
Un dettaglio sui limiti: una richiesta in streaming mantiene il suo slot di concorrenza fino alla fine dello streaming. Se avvii uno streaming e non lo leggi fino alla fine, quello slot rimane occupato. Consuma o chiudi sempre lo streaming.
Modalità JSON per output strutturato
Quando il tuo codice deve analizzare la risposta, chiedi un oggetto JSON con response_format. Dichiara anche nel prompt la forma desiderata, perché il flag del formato garantisce la sintassi JSON valida, non il tuo schema particolare.
import json
resp = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply only with JSON: {\"title\": string, \"tags\": [string]}."},
{"role": "user", "content": "Suggest a title and three tags for a post about home espresso."},
],
temperature=0.2,
)
data = json.loads(resp.choices[0].message.content)
print(data["title"], data["tags"])
Verifica che le chiavi necessarie esistano prima di usarle e mantieni la temperatura bassa per il lavoro di estrazione. Se l'analisi fallisce, riprovare una volta con lo stesso input di solito funziona e le richieste fallite non vengono addebitate.
Chiamata di funzioni: un giro completo
La chiamata di funzioni permette al modello di chiedere al tuo codice di eseguire una funzione. Descrivi la funzione in tools, il modello risponde con una voce tool_calls, la esegui e invii il risultato indietro come messaggio con role: "tool".
import json
def get_weather(city: str) -> dict:
return {"city": city, "temp_c": 18, "sky": "cloudy"}
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
messages = [{"role": "user", "content": "Is it warm in Lisbon right now?"}]
first = client.chat.completions.create(
model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message
if msg.tool_calls:
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(get_weather(**args)),
})
final = client.chat.completions.create(
model="uncensored", messages=messages, tools=tools
)
print(final.choices[0].message.content)
else:
print(msg.content)
La funzione qui restituisce dati fissi, quindi sostituiscila con una ricerca reale. Gli argomenti della funzione arrivano come stringa JSON, quindi analizzali sempre e valida i valori prima di agire. Con stream: true, le tool_calls arrivano in pezzi che assembli prima dell'analisi. Usa tool_choice per forzare uno strumento specifico quando ne hai bisogno.
Quanto costano gli esempi e gli errori che fanno perdere un'ora
L'esecuzione degli esempi costa molto poco, ma è utile vedere i calcoli una volta. A $0,15 per 1M token di input e $0,50 per 1M token di output:
- Il ciclo di conversazione, con un prompt da 1.200 token e una risposta da 300 token: $0,00018 per l'input più $0,00015 per l'output fa $0,00033. Un migliaio di turni costano $0,33.
- Il giro completo dello strumento fa due chiamate. Se la prima usa 400 token in input e 60 in output, e la seconda 500 in input e 150 in output, i totali sono 900 in input e 210 in output: $0,000135 più $0,000105 fa $0,00024.
- Lo streaming costa quanto una chiamata normale con gli stessi conteggi di token. Cambia quando vedi il testo, non il costo.
Il credito di prova di $0,50 pagherebbe più di 1.500 turni del ciclo di conversazione a quella dimensione ($0,50 / $0,00033), quindi puoi sperimentare liberamente prima di ricaricare. Le richieste fallite e rifiutate non vengono addebitate, il che significa che un bug nell'analisi che ti fa rieseguire una chiamata non ti costa per i tentativi falliti.
- Un base URL sbagliata. Deve terminare con
/v1. Aggiungere/chat/completionsmanualmente alla base URL di un SDK restituisce un 404 perché l'SDK aggiunge il percorso. - Un nome di modello diverso. I nomi copiati da altre piattaforme non esistono qui. L'ID è
uncensored. - Contare sulla memoria. L'API non ricorda le chiamate precedenti. Invia la cronologia ogni volta.
- Analizzare il JSON del modello senza controllo. Avvolgi
json.loadsin un blocco try e prevedi un piano per una risposta errata. - Lasciare aperte le connessioni streaming. Uno streaming non terminato mantiene occupato uno slot di concorrenza, e una chiave di prova ne ha solo due.
- Inserire la chiave nel codice front-end. Tienila sul server.
Se qualcosa sembra ancora sbagliato, invia una richiesta con curl e confrontala con quanto produce il tuo codice. La richiesta curl elimina l'SDK dalla situazione e rende evidenti le differenze nel corpo della richiesta.
Lettura di utilizzo, saldo ed errori
Per vedere le intestazioni dall'SDK Python, usa il wrapper della risposta grezza:
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Say ok."}],
)
print("request id:", raw.headers.get("x-request-id"))
print("balance usd:", raw.headers.get("x-balance-usd"))
print("rpm limit:", raw.headers.get("x-ratelimit-limit-requests"))
completion = raw.parse()
print(completion.usage.total_tokens)
Registra l'ID della richiesta con ogni chiamata in modo da poter puntare a una singola richiesta in seguito. Usa l'intestazione del saldo per impostare un avviso prima che il credito si esaurisca.
Quando superi un limite, l'API restituisce HTTP 429 e il codice di errore ti dice quale:
| Codice o intestazione | Cosa fare | Cosa fare |
|---|---|---|
rate_limited | Troppe richieste al minuto (300 con una chiave completa, 60 con quella di prova) | Riduci il ritmo e distribuisci le chiamate |
concurrency | Troppe richieste simultanee (8 con una chiave completa, 2 con quella di prova) | Attendi che una richiesta in corso termini |
Retry-After: 5 | Sovraccarico temporaneo | Riprova dopo cinque secondi |
Le richieste fallite o rifiutate non vengono addebitate. Il corpo della richiesta può essere fino a 8 MB. Per il riferimento completo e per riutilizzare il codice client esistente, consulta la documentazione. Per una guida su come ottenere una chiave, vedi l'articolo sulla chiave API GLM.
