Character AI API in Python: OpenAI SDK-instelling
Om een character ai api python-workflow te gebruiken, installeer je het officiële openai-pakket, wijs je de base URL naar een OpenAI-compatibele endpoint en stel je het model in op uncensored. De rest van deze pagina bouwt een kleine persona-chat bovenop die basis, met geschiedenis, streaming, retries en kostenbijhouding.
Bijgewerkt

Belangrijkste punten
- Twee waarden wijzigen in de standaard SDK: base_url en api_key.
- Het gedrag van het personage komt voort uit het system message plus de geschiedenis die je bij elke beurt opnieuw verstuurt.
- Streaming, function calling en JSON-modus werken allemaal via dezelfde client.
- Verwerk HTTP 429 met een korte wachttijd en beperk gelijktijdige aanroepen tot 8 met een volledige sleutel.
Installeren en verbinden
Er is geen speciale clientbibliotheek. Character-apps in Python gebruiken hetzelfde openai-pakket als alles anders. Installeer het en bewaar je sleutel in een omgevingsvariabele.
pip install openai
export API_KEY="paste-your-key-here"Haal eerst een sleutel op via de API-sleutelpagina. Nieuwe accounts kunnen daar met één klik $0,50 aan gratis proeftegoed claimen, zonder kaart. Maak vervolgens de client aan:
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)Als dat een begroeting en een usage-object afdrukt, is de verbinding goed. De dienst biedt POST /v1/chat/completions en GET /v1/models. Alles wat geen tekstchat is, zoals afbeeldingen, embeddings of fine-tuning, is niet beschikbaar.
Een personage-chatlus met geheugen
De API is stateless. Hij onthoudt de laatste beurt niet, dus jouw programma moet elke keer de hele conversatie versturen. Voor een persona betekent dit een system message gevolgd door afwisselende user en assistant messages. Deze lus houdt ze in een lijst.
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)Sampling-instellingen worden doorgegeven aan het model: temperature, top_p, stop, seed en de frequentie- en aanwezigheidsstraffen. Voor roleplay geeft een temperature tussen 0,8 en 1,0 meestal levendiger dialogen, terwijl een lagere waarde beter past bij gestructureerde taken. Stel seed in als je twee promptversies onder vergelijkbare omstandigheden wilt vergelijken.
Een gesprek opslaan en laden
Een chat die verdwijnt als het script stopt, is een demo, geen app. De geschiedenis opslaan als JSON-bestand is de kleinste stap die het persistent laat lijken. De helper hieronder laadt de opgeslagen berichten van een personage als die bestaan en schrijft ze na elke beurt terug.
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))Roep load aan bij het opstarten en save nadat je de assistant reply hebt toegevoegd. Houd één bestand per personage en per gebruiker aan, en je hebt al een multi-character setup. Zodra je bestanden ontgroeit, past dezelfde lijst van dicts in een databasekolom of een key-value store zonder wijziging, omdat dit precies is wat de API verwacht.
Denk na over wat je opslaat. De geschiedenis kan persoonlijke details bevatten die gebruikers hebben ingetypt. Prompts die naar deze API worden gestuurd, worden niet gebruikt voor training, maar je eigen bestanden en logs zijn jouw verantwoordelijkheid, dus beslis hoelang je ze bewaart en wie ze kan lezen.
Geschiedenis inkorten voordat het duur wordt
Het contextvenster is 100.000 tokens, prompt plus completion. Een lange roleplay kan dat na verloop van tijd bereiken, en de kosten stijgen omdat je input tokens betaalt voor de volledige geschiedenis bij elke beurt. Een eenvoudige aanpak houdt de system message en de laatste N uitwisselingen.
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),
)Een beter ontwerp voor lange verhalen is een rollende samenvatting. Vraag het model elke 30 berichten om het oudere deel samen te vatten in 200 woorden, vervang die berichten door de samenvatting in het system message en ga verder. Je verliest wat detail, maar behoudt de verhaallijnen, en de kosten per beurt blijven gelijk.
Hier is de wiskunde voor een chat die 8.000 tokens aan geschiedenis heeft bereikt met een antwoord van 300 tokens: input is 8.000 x $0,15 / 1.000.000 = $0,0012, output is 300 x $0,50 / 1.000.000 = $0,00015, dus $0,00135 per beurt. Die geschiedenis inkorten naar 2.000 tokens verlaagt de beurt naar $0,0003 + $0,00015 = $0,00045. Dat is een derde van de prijs voor de meeste gesprekken.
Antwoorden streamen terwijl ze worden geschreven
Voor een chatinterface wil je dat tekst verschijnt terwijl deze wordt gegenereerd. Stel stream=True in en itereer over de chunks. Streaming verloopt via server-sent events, en je kunt om gebruiksinformatie vragen in de laatste 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)Onthoud dat een gestreamd verzoek zijn concurrency-slot vasthoudt tot de stream eindigt. Met een volledige sleutel kun je er 8 tegelijk uitvoeren; met een proefsleutel slechts 2. Als een gebruiker het tabblad sluit, zorg er dan voor dat je server ook de upstream-stream sluit, anders blijft het slot bezet.
Veel chats tegelijk uitvoeren met asyncio
Een webservice die veel gebruikers tegelijk afhandelt, heeft de async client nodig. Het patroon is eenvoudig: één gedeelde AsyncOpenAI-client, één semaphore die groot is naar je concurrency limit, en een coroutine per gesprek.
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())Er zijn twintig taken aangemaakt, maar slechts acht worden tegelijk uitgevoerd. De rest wacht zijn beurt binnen de semaphore, zodat je de concurrency-fout niet triggert. Als je dienst gestreamde antwoorden afhandelt, onthoud dan dat elke open stream meetelt tot deze klaar is, wat betekent dat langzame lezers aan de clientkant langer slots kunnen vasthouden. Stel een timeout in op de client en annuleer streams waarvan de gebruikers zijn vertrokken.
De limiet per minuut is apart. Bij 300 verzoeken per minuut met een volledige sleutel is een burst van 20 korte aanroepen prima, maar een lus die duizenden aanroepen verstuurt, moet worden getimed. Een eenvoudige aanpak is een korte pauze tussen taakstarts, of gebruik een token bucket-bibliotheek die bij je stack past.
Tools en JSON-modus
Character bots hebben vaak gestructureerde output nodig: een stemmingsscore, een inventory-update, een lijst met keuzes voor de speler. JSON-modus maakt het antwoord tot geldige JSON, en je beschrijft de vorm in de 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"])Tool calling gebruikt de standaard tools- en tool_choice-velden. Het model retourneert een tool_calls-vermelding, je code voert de functie uit en je stuurt het resultaat terug als bericht met 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)Test dit tegen je eigen prompts voordat je erop vertrouwt. Open-weight models verschillen in hoe betrouwbaar ze een tool call genereren, dus houd een fallback-pad aan wanneer tool_calls leeg is.
Fouten en rate limits afhandelen
Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 verzoeken per minuut toe. Een proefsleutel staat 2 en 60 toe. Bij overschrijding krijg je HTTP 429 met de error code rate_limited (te veel per minuut) of concurrency (te veel tegelijk). Een tijdelijke overload retourneert ook 429, met een Retry-After: 5-header. De SDK gooit RateLimitError voor deze gevallen, en je kunt de aanroep in een retry wikkelen.
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")Als je veel gesprekken vanuit één proces uitvoert, beperk ze dan met een semaphore zodat je nooit meer dan 8 verzoeken tegelijk hebt. Met asyncio en AsyncOpenAI is asyncio.Semaphore(8) rond elke aanroep genoeg. De response headers X-RateLimit-Limit-Requests en X-RateLimit-Limit-Concurrency bevestigen de limieten die voor je sleutel gelden, en X-Balance-USD toont je resterende tegoed.
Mislukte of geweigerde verzoeken worden niet in rekening gebracht, dus opnieuw proberen bij fouten kost je niets. Als je saldo laag wordt, kun je opwaarderen met $20 tot $500; bedragen vanaf $50 krijgen een bonus van 5%, 10% of 15% op het niveau van $50, $100 en $200. Details staan op de prijspagina, en de volledige parameterlijst staat in de documentatie.
Bijhouden wat elke sessie kost
Elk niet-gestreamd antwoord bevat een usage object met prompt_tokens en completion_tokens. Als je streamt en om gebruik vraagt, bevat de laatste chunk het. Zet die cijfers om in dollars met een kleine functie en log het naast de session ID.
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}")Met deze cijfers kun je praktische vragen beantwoorden. Als een gemiddelde sessie 40 beurten heeft, met geschiedenis die groeit van 500 naar 6.000 input tokens en 250 output tokens per antwoord, is de gemiddelde input ongeveer 3.250 tokens. Inputkosten per beurt zijn ongeveer 3.250 x $0,15 / 1.000.000 = $0,00049 en output is 250 x $0,50 / 1.000.000 = $0,000125, dus ongeveer $0,00061 per beurt en $0,0245 voor de 40 beurten. Een gebruiker die 20 sessies per maand speelt, kost je ongeveer 49 cent. Dat is een cijfer waar je een product rond kunt prijzen.
Voer de verbindingscontrole uit binnen een virtuele omgeving zodat de pakketversie voor het project vast blijft, en lijst de modellen één keer op met client.models.list() bij het opstarten. Als die aanroep faalt, ontdek je een verkeerde sleutel of een verkeerde base URL voordat een gebruiker dat doet, en kun je een duidelijke melding afdrukken in plaats van een stack trace diep in een chatlus. Teams die deze code implementeren, voegen vaak dezelfde aanroep toe aan een health check-route.
Log de kosten per sessie en kijk naar de top vijf procent. Lange sessies die hun geschiedenis nooit inkorten, domineren meestal de rekening, en de oplossing is de eerder beschreven trim- of samenvattingsaanpak.