API Character AI in Python: configurazione SDK OpenAI
Per usare un workflow Python dell'API Character AI, installa il pacchetto openai ufficiale, punta il suo base URL a un endpoint compatibile con OpenAI e imposta il modello su uncensored. Il resto di questa pagina crea una piccola chat per personaggi basata su questo, con cronologia, streaming, ritentativi e tracciamento dei costi.
Aggiornato

Punti chiave
- Due valori cambiano nell'SDK standard: base_url e api_key.
- Il comportamento del personaggio deriva dal messaggio di sistema più dalla cronologia che invii ad ogni turno.
- Streaming, chiamata di funzioni e modalità JSON funzionano tutti attraverso lo stesso client.
- Gestisci l'HTTP 429 con una breve attesa e limita le chiamate parallele a 8 con una chiave completa.
Installa e connetti
Non esiste una libreria client speciale. Le app Character in Python usano lo stesso pacchetto openai di tutto il resto. Installalo e tieni la tua chiave in una variabile d'ambiente.
pip install openai
export API_KEY="paste-your-key-here"Ottieni prima una chiave dalla pagina delle chiavi API. I nuovi account possono richiedere $0,50 di credito di prova con un clic, senza carta. Poi crea il client:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.characteraiapi.com/v1",
api_key=os.environ["API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)
print(resp.usage)Se stampa un saluto e un oggetto usage, la connessione è buona. Il servizio espone POST /v1/chat/completions e GET /v1/models. Tutto ciò che non è chat testuale, come immagini, embedding o fine-tuning, non è disponibile.
Un ciclo di chat con memoria
L'API è stateless. Non ricorda l'ultimo turno, quindi il tuo programma deve inviare l'intera conversazione ogni volta. Per una personalità significa un messaggio di sistema seguito da messaggi alternati di utente e assistente. Questo ciclo li mantiene in un elenco.
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.characteraiapi.com/v1", api_key=os.environ["API_KEY"])
PERSONA = (
"You are Mara, a dry-witted ship engineer in a space opera. "
"Stay in character, answer in two to four sentences, and never mention being an AI."
)
history = [{"role": "system", "content": PERSONA}]
while True:
user = input("you> ").strip()
if user in {"quit", "exit"}:
break
history.append({"role": "user", "content": user})
resp = client.chat.completions.create(
model="uncensored",
messages=history,
temperature=0.9,
top_p=0.95,
)
text = resp.choices[0].message.content
history.append({"role": "assistant", "content": text})
print("mara>", text)Le impostazioni di campionamento vengono passate al modello: temperature, top_p, stop, seed e le penalità di frequenza e presenza. Per il roleplay, una temperatura tra 0,8 e 1,0 di solito dà dialoghi più vivaci, mentre un valore più basso si adatta a compiti strutturati. Imposta seed quando vuoi confrontare due versioni del prompt in condizioni simili.
Salva e carica una conversazione
Una chat che scompare quando lo script termina è una demo, non un'app. Memorizzare la cronologia come file JSON è il passo più piccolo che la fa sembrare persistente. La funzione di supporto qui sotto carica i messaggi salvati di un personaggio se esistono e li scrive di nuovo dopo ogni turno.
import json
from pathlib import Path
def load(name, persona):
path = Path(f"{name}.json")
if path.exists():
return json.loads(path.read_text())
return [{"role": "system", "content": persona}]
def save(name, history):
Path(f"{name}.json").write_text(json.dumps(history, indent=2))Chiama load all'avvio e save dopo aver aggiunto la risposta dell'assistente. Tieni un file per personaggio e per utente e avrai già una configurazione multi-personaggio. Quando i file non bastano più, lo stesso elenco di dizionari si adatta a una colonna di database o a un archivio chiave-valore senza modifiche, perché è esattamente ciò che l'API si aspetta.
Pensa a cosa memorizzi. La cronologia potrebbe contenere dettagli personali che gli utenti hanno digitato. I prompt inviati a questa API non vengono utilizzati per l'addestramento, ma i tuoi file e log personali sono tua responsabilità, quindi decidi per quanto tempo li conservi e chi può leggerli.
Riduci la cronologia prima che diventi costosa
La finestra di contesto è di 100.000 token, prompt più completamento. Un roleplay lungo può raggiungerla nel tempo e il costo cresce perché paghi i token di input per l'intera cronologia a ogni turno. Un approccio semplice mantiene il messaggio di sistema e le ultime N coppie di messaggi.
def trimmed(history, keep=20):
system = history[:1]
rest = history[1:]
return system + rest[-keep:]
# inside the loop
resp = client.chat.completions.create(
model="uncensored",
messages=trimmed(history),
)Un design migliore per le storie lunghe è un riepilogo scorrevole. Ogni 30 messaggi, chiedi al modello di riassumere la parte più vecchia in 200 parole, sostituisci quei messaggi con il riepilogo all'interno del messaggio di sistema e continua. Perdi alcuni dettagli ma mantieni i fili della trama e il costo per turno rimane piatto.
Ecco i calcoli per una chat con 8.000 token di cronologia e una risposta di 300 token: input è 8.000 x $0,15 / 1.000.000 = $0,0012, output è 300 x $0,50 / 1.000.000 = $0,00015, quindi $0,00135 per turno. Tagliando quella cronologia a 2.000 token il turno scende a $0,0003 + $0,00015 = $0,00045. È un terzo del prezzo per la maggior parte delle conversazioni.
Trasmetti le risposte mentre vengono scritte
Per un'interfaccia di chat vuoi che il testo appaia mentre viene generato. Imposta stream=True e itera sui chunk. Lo streaming funziona tramite eventi server-sent e puoi richiedere l'utilizzo nell'ultimo chunk.
stream = client.chat.completions.create(
model="uncensored",
messages=history,
stream=True,
stream_options={"include_usage": True},
)
parts = []
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
parts.append(piece)
print(piece, end="", flush=True)
print()
reply = "".join(parts)Ricorda che una richiesta in streaming mantiene il suo slot di concorrenza fino alla fine dello streaming. Con una chiave completa puoi eseguire 8 contemporaneamente; con una chiave di prova solo 2. Se un utente chiude la scheda, assicurati che il tuo server chiuda anche lo streaming upstream, altrimenti mantiene lo slot occupato.
Esegui molte chat contemporaneamente con asyncio
Un servizio web che gestisce molti utenti contemporaneamente ha bisogno del client asincrono. Il pattern è semplice: un client AsyncOpenAI condiviso, un semaforo dimensionato al tuo limite di concorrenza e una coroutine per conversazione.
import asyncio
import os
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://api.characteraiapi.com/v1", api_key=os.environ["API_KEY"])
gate = asyncio.Semaphore(8) # use 2 on a trial key
async def reply(messages):
async with gate:
r = await client.chat.completions.create(model="uncensored", messages=messages)
return r.choices[0].message.content
async def main():
jobs = [
reply([{"role": "user", "content": f"Give character {i} a one-line greeting."}])
for i in range(20)
]
for text in await asyncio.gather(*jobs):
print(text)
asyncio.run(main())Vengono creati venti job, ma solo otto girano contemporaneamente. Gli altri aspettano il loro turno nel semaforo, così non attivi mai l'errore concurrency. Se il tuo servizio gestisce risposte in streaming, ricorda che ogni stream aperto conta fino al termine, il che significa che lettori lenti sul client possono occupare slot più a lungo del previsto. Imposta un timeout sul client e interrompi gli stream degli utenti che se ne sono andati.
Il limite al minuto è separato. A 300 richieste al minuto con una chiave completa, un burst di 20 chiamate brevi va bene, ma un ciclo che invia migliaia di chiamate richiede una regolazione. Un approccio semplice è dormire per una frazione di secondo tra i lanci dei task, o usare una libreria token bucket che si adatta al tuo stack.
Strumenti e modalità JSON
I bot dei personaggi hanno spesso bisogno di output strutturato: un punteggio di umore, un aggiornamento dell'inventario, un elenco di scelte per il giocatore. La modalità JSON rende la risposta JSON valida e descrivi la forma nel prompt.
import json
resp = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply with JSON only: {\"mood\": string, \"choices\": [string, string, string]}"},
{"role": "user", "content": "Mara finds a sealed hatch in the cargo bay."},
],
)
data = json.loads(resp.choices[0].message.content)
print(data["mood"], data["choices"])La chiamata di strumenti usa i campi standard tools e tool_choice. Il modello restituisce una voce tool_calls, il tuo codice esegue la funzione e invii il risultato come messaggio con role: "tool".
tools = [{
"type": "function",
"function": {
"name": "roll_dice",
"description": "Roll an n-sided die",
"parameters": {
"type": "object",
"properties": {"sides": {"type": "integer"}},
"required": ["sides"],
},
},
}]
msgs = [{"role": "user", "content": "Mara tries to force the hatch. Roll a d20."}]
first = client.chat.completions.create(model="uncensored", messages=msgs, tools=tools)
call = first.choices[0].message.tool_calls[0]
msgs.append(first.choices[0].message)
msgs.append({"role": "tool", "tool_call_id": call.id, "content": "17"})
final = client.chat.completions.create(model="uncensored", messages=msgs, tools=tools)
print(final.choices[0].message.content)Prova questo con i tuoi prompt prima di affidarti ad esso. I modelli a pesi aperti differiscono nell'emettere in modo affidabile una tool call, quindi mantieni un percorso di fallback quando tool_calls è vuoto.
Gestisci errori e limiti di richiesta
Una chiave completa permette 8 richieste parallele e 300 richieste al minuto. Una chiave di prova ne permette 2 e 60. Superato un limite ottieni HTTP 429 con il codice di errore rate_limited (troppe al minuto) o concurrency (troppe contemporaneamente). Un sovraccarico temporaneo restituisce anche 429, con un'intestazione Retry-After: 5. L'SDK genera RateLimitError per questi casi e puoi avvolgere la chiamata in una logica di ritentativo.
import time
import openai
def chat(messages, tries=4):
for attempt in range(tries):
try:
return client.chat.completions.create(model="uncensored", messages=messages)
except openai.RateLimitError as err:
wait = 5
retry_after = err.response.headers.get("Retry-After")
if retry_after:
wait = int(retry_after)
time.sleep(wait * (attempt + 1))
raise RuntimeError("still rate limited")Se esegui molte conversazioni da un singolo processo, limitale con un semaforo in modo da non superare mai 8 richieste in corso. Con asyncio e AsyncOpenAI, asyncio.Semaphore(8) attorno a ogni chiamata è sufficiente. Le intestazioni di risposta X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency confermano i limiti applicabili alla tua chiave, e X-Balance-USD mostra il tuo credito residuo.
Le richieste fallite o rifiutate non vengono addebitate, quindi i ritentativi per gli errori non ti costano. Quando il tuo saldo è basso, ricarica da $20 a $500; gli importi da $50 in su hanno un bonus del 5%, 10% o 15% ai livelli $50, $100 e $200. I dettagli sono nella pagina dei prezzi, e l'elenco completo dei parametri è nella documentazione.
Traccia il costo di ogni sessione
Ogni risposta non in streaming include un oggetto usage con prompt_tokens e completion_tokens. Quando usi lo streaming e chiedi l'utilizzo, l'ultimo chunk lo contiene. Converti quei numeri in dollari con una piccola funzione e registrali accanto all'ID della sessione.
IN_PRICE = 0.15 / 1_000_000
OUT_PRICE = 0.50 / 1_000_000
def cost(usage):
return usage.prompt_tokens * IN_PRICE + usage.completion_tokens * OUT_PRICE
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Describe the engine room in three lines."}],
)
print(f"${cost(resp.usage):.6f}")Con questi numeri puoi rispondere a domande pratiche. Se una sessione media è di 40 turni, con la cronologia che cresce da 500 a 6.000 token di input e 250 token di output per risposta, la media di input è di circa 3.250 token. Il costo di input per turno è circa 3.250 x $0,15 / 1.000.000 = $0,00049 e l'output è 250 x $0,50 / 1.000.000 = $0,000125, quindi circa $0,00061 per turno e $0,0245 per i 40 turni. Un utente che gioca 20 sessioni al mese ti costa circa 49 centesimi. Questo è un numero intorno al quale puoi fissare il prezzo di un prodotto.
Esegui il controllo della connessione in un ambiente virtuale in modo che la versione del pacchetto rimanga fissa per il progetto e elenca i modelli una volta con client.models.list() all'avvio. Se quella chiamata fallisce, scopri una chiave errata o un base URL errato prima che lo faccia qualsiasi utente, e puoi stampare un messaggio chiaro invece di uno stack trace profondo in un ciclo di chat. I team che distribuiscono questo codice aggiungono spesso la stessa chiamata a un endpoint di health check.
Registra il costo per sessione e guarda il 5% più alto. Le sessioni lunghe che non tagliano mai la cronologia dominano di solito il conto, e la soluzione è l'approccio di taglio o riassunto descritto in precedenza.