API Chat compatibile con OpenAI: Python, Node e curl
Una chiamata API chat compatibile con OpenAI è una singola POST con un elenco di messaggi e una risposta dal modello. Questa guida illustra la richiesta, le conversazioni multi-turno, lo streaming e gli errori che puoi incontrare, usando un endpoint uncensored come esempio.
Aggiornato

La richiesta in un minuto
Qualsiasi client che può parlare con il formato chat OpenAI può parlare con questo servizio. Modifichi due cose, l'URL di base e la chiave, e mantieni tutto il resto. Qui l'URL di base è https://api.mistralapikey.com/v1 e l'ID del modello è uncensored. L'autenticazione è un'intestazione standard Authorization: Bearer.
Una prima richiesta appare così:
curl https://api.mistralapikey.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Explain what an API key is in two sentences."}
]
}'
Questo è un servizio indipendente che esegue un modello a pesi aperti, ottimizzato per rispondere senza rifiuti di contenuti per l'uso adulto legale. Non è l'API ufficiale di Meta, Mistral, OpenAI o di qualsiasi altro fornitore. Espone due metodi, POST /v1/chat/completions e GET /v1/models, e gestisce solo testo. Se hai ancora bisogno di una chiave, la pagina chiave API spiega la registrazione e il credito di prova.
Leggere la risposta
Una risposta riuscita è un oggetto JSON nella forma usuale. Il testo è su choices[0].message.content, il motivo di arresto è in choices[0].finish_reason, e i conteggi dei token sono in usage.
{
"id": "chatcmpl-...",
"object": "chat.completion",
"model": "uncensored",
"choices": [
{
"index": 0,
"message": {"role": "assistant", "content": "An API key is a secret string..."},
"finish_reason": "stop"
}
],
"usage": {"prompt_tokens": 31, "completion_tokens": 48, "total_tokens": 79}
}
Un finish_reason di stop significa che il modello ha terminato la sua risposta. Un valore di length significa che ha raggiunto un limite di token, quindi aumenta max_tokens o lascialo non impostato. Le intestazioni contano anche: X-Request-Id identifica la chiamata per il supporto, X-Balance-USD mostra il tuo credito residuo, e X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency riportano i tuoi limiti.
Messaggi e ruoli
L'array messages è l'intera conversazione, in ordine. Ogni elemento ha un role e content.
- system imposta comportamento, tono e regole. Mettilo per primo.
- user è ciò che ha digitato la persona.
- assistant è ciò che ha detto il modello prima nella conversazione.
- tool trasporta il risultato di una chiamata di funzione, se usi la chiamata di funzioni.
Il modello conosce solo ciò che è nell'array. Non viene ricordato nulla tra le richieste, quindi il server non mantiene una sessione per te. Questa è la cosa più importante da capire sugli endpoint chat, e spiega perché una "chat" costa di più ad ogni turno: la cronologia che invii viene fatturata come input ogni volta.
Chat multi-turno in Python
Per mantenere una conversazione, tieni un elenco, aggiungi il messaggio dell'utente, chiama l'API, aggiungi la risposta dell'assistente e ripeti. Questa è una chat completa del terminale.
from openai import OpenAI
client = OpenAI(
base_url="https://api.mistralapikey.com/v1",
api_key="YOUR_API_KEY",
)
history = [{"role": "system", "content": "You are a friendly, direct assistant."}]
while True:
text = input("you> ").strip()
if not text:
break
history.append({"role": "user", "content": text})
resp = client.chat.completions.create(
model="uncensored",
messages=history,
temperature=0.7,
)
answer = resp.choices[0].message.content
history.append({"role": "assistant", "content": answer})
print("bot>", answer)
print(f" [{resp.usage.prompt_tokens} in / {resp.usage.completion_tokens} out]")
Tieni d'occhio i numeri tra parentesi quadre mentre chatti. Il conteggio "in" sale ad ogni turno perché include tutto ciò che è stato detto finora. Questa crescita è normale ed è anche la tua leva principale per il controllo dei costi, trattata di seguito.
Risposte in streaming in Node
Per un'interfaccia chat vuoi che il testo appaia mentre viene generato. Imposta stream: true e l'API invia eventi server-sent. L'SDK Node di OpenAI avvolge questo in un iteratore asincrono.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.mistralapikey.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Write a four-line poem about debugging." }],
stream: true,
});
for await (const chunk of stream) {
const piece = chunk.choices[0]?.delta?.content ?? "";
process.stdout.write(piece);
}
process.stdout.write("\n");
L'utilizzo viene riportato alla fine dello streaming, quindi puoi ancora registrare i conteggi dei token senza una seconda chiamata. Un dettaglio operativo: una richiesta in streaming mantiene il suo slot di concorrenza fino alla fine dello streaming. Se un utente chiude una scheda, annulla la richiesta dal tuo lato in modo che lo slot si liberi prima.
Parametri che puoi usare
I controlli di campionamento standard vengono passati al modello. Questi sono quelli che toccherai di più.
| Campo | Cosa fa | Suggerimento pratico |
|---|---|---|
temperature | Casualità della scelta delle parole | 0 a 0,3 per l'estrazione, 0,7 a 1,0 per il testo creativo |
top_p | Limita il campionamento alle parole più probabili | Modifica questo o la temperatura, raramente entrambi |
max_tokens | Limite superiore sulla lunghezza della risposta | Opzionale; impostalo per limitare i costi su prompt a lunghezza indeterminata |
stop | Sequenze che terminano la generazione | Utile per formati basati su riga |
seed | Campionamento ripetibile | Comodo per i test |
frequency_penalty, presence_penalty | Sconsiglia la ripetizione | Valori piccoli fanno molta strada |
response_format | Modalità JSON | Usa {"type":"json_object"} e descrivi le chiavi nel prompt |
La chiamata di funzioni è disponibile tramite tools e tool_choice. La guida quickstart copre la configurazione per gli SDK comuni.
Quanto costa una conversazione
I prezzi sono $0,15 per 1M token di input e $0,50 per 1M token di output, dal credito prepagato. La finestra di contesto è di 100.000 token per prompt e risposta insieme. Poiché la cronologia viene inviata di nuovo, il costo di una chat cresce più velocemente del numero di messaggi.
Prendi una chat in cui ogni messaggio dell'utente è di circa 100 token e ogni risposta di circa 200 token, più un messaggio di sistema di 200 token. Il turno 1 invia 300 token di input. Il turno 10 invia circa 200 + 10 x 100 + 9 x 200 = 3.000 token di input. Il turno 30 invia circa 200 + 30 x 100 + 29 x 200 = 9.000.
Somma tutti i 30 turni di input: il totale è 30 x 200 + 100 x (1 + 2 + ... + 30) + 200 x (0 + 1 + ... + 29) = 6.000 + 46.500 + 87.000 = 139.500 token di input. L'output è 30 x 200 = 6.000 token. Costo: 139.500 / 1M x $0,15 = $0,020925, più 6.000 / 1M x $0,50 = $0,003. L'intera chat a 30 turni costa circa $0,024. Economico, ma nota che l'input è 23 volte più grande dell'output e crescerebbe col quadrato della lunghezza se non lo tagliassi.
Modi per tenerla bassa: elimina o riassume i vecchi turni una volta che la cronologia supera una dimensione che scegli, mantieni breve il prompt di sistema e imposta max_tokens quando non hai bisogno di risposte lunghe. Le richieste fallite o rifiutate non vengono addebitate. Gli importi di ricarica e i livelli bonus sono elencati nella pagina prezzi.
Tagliare la cronologia senza interrompere la chat
Una volta che una conversazione diventa lunga hai due scelte: pagare per l'intera storia ad ogni turno o tagliarla. Una regola semplice è mantenere il messaggio di sistema e gli ultimi diversi turni. Questa funzione lo fa e lascia invariato il resto del tuo loop.
from openai import OpenAI
client = OpenAI(
base_url="https://api.mistralapikey.com/v1",
api_key="YOUR_API_KEY",
)
def trimmed(history, keep=8):
system = history[:1]
rest = history[1:]
return system + rest[-keep:]
resp = client.chat.completions.create(
model="uncensored",
messages=trimmed(history),
)
Il prezzo del taglio è che il modello dimentica ciò che non vede più. Per i bot di supporto va bene. Per le storie lunghe potresti preferire chiedere al modello di scrivere un breve riassunto dei vecchi turni una volta, archiviarlo come nota di sistema e scartare gli originali. Questo costa una chiamata extra ma mantiene la trama.
Scrivere un messaggio di sistema utile
Mantenilo breve e concreto: chi è l'assistente, quanto dovrebbero essere lunghe le risposte e eventuali regole di formato. "Sei un agente di supporto per un negozio di biciclette. Rispondi in al massimo tre frasi e fai una domanda se la richiesta non è chiara" fa più di una pagina di virtù generale. Ogni parola di esso viene fatturata come input ad ogni turno, quindi un messaggio di sistema da 1.000 token aggiunge $0.00015 a ogni richiesta.
Errori e limiti
Una chiave completa consente 8 richieste concorrenti e 300 richieste al minuto; una chiave di prova consente 2 e 60. Il corpo della richiesta massimo è 8 MB. Superi un limite e ricevi HTTP 429, con uno di questi significati:
- Codice di errore
rate_limited: troppe richieste al minuto. Spazia le richieste. - Codice di errore
concurrency: troppe richieste simultanee. Accodale. - Intestazione
Retry-After: 5: sovraccarico temporaneo. Attendi 5 secondi e riprova.
Un 401 indica che la chiave manca o è errata. Tieni le chiavi fuori dal codice front-end; chiama l'API dal tuo server. Se stai migrando da una configurazione Mistral, la pagina pagina della chiave API di Mistral spiega come accedere a questo servizio.
Per il codice di produzione, avvolgi le chiamate in un retry con una breve attesa, come fanno già gli SDK OpenAI per alcuni errori, e registra il valore X-Request-Id accanto a ogni errore. Quando qualcosa sembra errato, quell'ID è il modo più veloce per indicare a support la richiesta esatta. Imposta anche un timeout lato client: un completamento lungo su un prompt grande può richiedere tempo e non vuoi che una connessione bloccata occupi uno degli 8 slot di concorrenza.
Il servizio non produce contenuti sessuali che coinvolgono minorenni e i prompt non sono usati per l'addestramento.
Altre guide
Domande e risposte
Cosa significa compatibile con OpenAI?
Significa che l'endpoint accetta lo stesso formato di richiesta dell'API di chat completion di OpenAI, quindi gli SDK e gli strumenti OpenAI funzionano dopo aver modificato l'URL di base e la chiave.
Il server ricorda la conversazione?
No. Invia l'intera cronologia dei messaggi con ogni richiesta. Il server non mantiene sessioni tra le chiamate.
Quali endpoint sono disponibili?
POST /v1/chat/completions e GET /v1/models. Il servizio è solo testo, senza endpoint per immagini, audio o embedding.
Come faccio a ricevere la risposta in streaming?
Imposta stream su true. L'API invia eventi inviati dal server e riporta l'utilizzo alla fine dello streaming.
Che nome di modello devo usare?
Usa uncensored come ID del modello in ogni richiesta.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.