Character AI API in Python: OpenAI SDK-Einrichtung
Um einen Character-AI-API-Python-Workflow zu nutzen, installiere das offizielle openai-Paket, richte die Basis-URL auf einen OpenAI-kompatiblen Endpunkt ein und setze das Modell auf uncensored. Der Rest dieser Seite baut darauf einen kleinen Persona-Chat auf, mit Verlauf, Streaming, Wiederholungen und Kostenverfolgung.
Aktualisiert

Wichtige Punkte
- Zwei Werte ändern sich im Standard-SDK: base_url und api_key.
- Das Verhalten des Charakters ergibt sich aus der Systemnachricht plus dem Verlauf, den du bei jedem Zug erneut sendest.
- Streaming, Function Calling und JSON-Modus funktionieren alle über denselben Client.
- Behandle HTTP 429 mit einer kurzen Wartezeit und begrenze parallele Aufrufe auf 8 bei einem Voll-Key.
Installieren und verbinden
Es gibt keine spezielle Client-Bibliothek. Character-Apps in Python nutzen dasselbe openai-Paket. Installiere es und speichere deinen Schlüssel in einer Umgebungsvariable.
pip install openai
export API_KEY="paste-your-key-here"Hole dir zuerst einen Schlüssel über die API-Schlüssel-Seite. Neue Konten können dort mit einem Klick $0,50 an Prepaid-Guthaben beanspruchen, keine Karte nötig. Erstelle dann den 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)Wenn das eine Begrüßung und ein Nutzungsobjekt ausgibt, ist die Verbindung gut. Der Dienst stellt POST /v1/chat/completions und GET /v1/models bereit. Alles, was kein Text-Chat ist, wie Bilder, Embeddings oder Fine-Tuning, ist nicht verfügbar.
Ein Charakter-Chat-Loop mit Speicher
Die API ist zustandslos. Sie erinnert sich nicht an den letzten Zug, daher muss dein Programm jedes Mal die gesamte Unterhaltung senden. Für eine Persona bedeutet dies eine Systemnachricht, gefolgt von abwechselnden Benutzer- und Assistenten-Nachrichten. Diese Schleife hält sie in einer Liste.
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-Einstellungen werden an das Modell weitergegeben: temperature, top_p, stop, seed sowie die Häufigkeits- und Präsenzstrafen. Für Rollenspiele liefert eine Temperatur zwischen 0,8 und 1,0 normalerweise lebhaftere Dialoge, während ein niedrigerer Wert für strukturierte Aufgaben geeignet ist. Setze seed, wenn du zwei Prompt-Versionen unter ähnlichen Bedingungen vergleichen möchtest.
Eine Unterhaltung speichern und laden
Ein Chat, der beim Beenden des Skripts verschwindet, ist eine Demo, keine App. Das Speichern des Verlaufs als JSON-Datei ist der kleinste Schritt, der das Gefühl von Persistenz vermittelt. Der folgende Helper lädt gespeicherte Nachrichten eines Charakters, falls vorhanden, und schreibt sie nach jedem Zug zurück.
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))Rufe load beim Start auf und save nach dem Anhängen der Assistenten-Antwort. Halte eine Datei pro Charakter und pro Benutzer, und du hast bereits ein Multi-Charakter-Setup. Sobald Dateien nicht mehr ausreichen, passt dieselbe Liste von Dictionaries in eine Datenbankspalte oder einen Key-Value-Speicher ohne Änderung, weil es genau das ist, was die API erwartet.
Überlege dir, was du speicherst. Der Verlauf kann persönliche Details enthalten, die Benutzer eingegeben haben. Prompts, die an diese API gesendet werden, werden nicht zum Training verwendet, aber deine eigenen Dateien und Logs sind deine Verantwortung. Entscheide also, wie lange du sie aufbewahrst und wer sie lesen darf.
Verlauf kürzen, bevor es teuer wird
Das Kontextfenster hat 100.000 Token, Prompt plus Vervollständigung. Ein langes Roleplay kann das im Laufe der Zeit erreichen, und die Kosten steigen damit, weil du Eingabe-Token für die gesamte Historie bei jedem Zug zahlst. Ein einfacher Ansatz hält die Systemnachricht und die letzten N Austausche.
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),
)Ein besseres Design für lange Geschichten ist eine rollierende Zusammenfassung. Frage das Modell alle 30 Nachrichten, den älteren Teil in 200 Worten zusammenzufassen, ersetze diese Nachrichten durch die Zusammenfassung in der Systemnachricht und fahre fort. Du verlierst einige Details, behältst aber die Handlungsfäden, und die Kosten pro Zug bleiben gleich.
Hier ist die Rechnung für einen Chat, der 8.000 Token an Historie mit einer 300-Token-Antwort erreicht hat: Input ist 8.000 x $0,15 / 1.000.000 = $0,0012, Output ist 300 x $0,50 / 1.000.000 = $0,00015, also $0,00135 pro Zug. Das Kürzen dieser Historie auf 2.000 Token senkt den Zug auf $0,0003 + $0,00015 = $0,00045. Das ist ein Drittel des Preises für die meisten Gespräche.
Antworten streamen, während sie geschrieben werden
Für eine Chat-Schnittstelle möchtest du, dass Text erscheint, während er generiert wird. Setze stream=True und iteriere über die Chunks. Streaming läuft über Server-Sent Events, und du kannst die Nutzung im letzten Chunk anfordern.
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)Denke daran, dass eine gestreamte Anfrage ihren Concurrency-Slot hält, bis der Stream endet. Bei einem Voll-Key kannst du 8 gleichzeitig ausführen; bei einem Trial-Key nur 2. Wenn ein Benutzer den Tab schließt, stelle sicher, dass dein Server den Upstream-Stream ebenfalls schließt, sonst bleibt der Slot belegt.
Viele Chats gleichzeitig mit asyncio ausführen
Ein Webdienst, der viele Benutzer gleichzeitig bedient, benötigt den asynchronen Client. Das Muster ist einfach: ein gemeinsamer AsyncOpenAI-Client, ein Semaphore, das auf dein Concurrency-Limit skaliert ist, und eine Coroutine pro Unterhaltung.
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())Zwanzig Jobs werden erstellt, aber nur acht laufen gleichzeitig. Der Rest wartet im Semaphore, also löst du nie den concurrency-Fehler aus. Wenn dein Dienst gestreamte Antworten verarbeitet, denke daran, dass jeder offene Stream zählt, bis er fertig ist. Das bedeutet, dass langsame Leser auf der Client-Seite Slots länger belegen können als erwartet. Setze einen Timeout auf den Client und breche Streams ab, deren Benutzer verschwunden sind.
Das Limit pro Minute ist separat. Bei 300 Anfragen pro Minute bei einem Voll-Key ist ein Burst von 20 kurzen Aufrufen in Ordnung, aber eine Schleife, die Tausende von Aufrufen sendet, benötigt eine Drosselung. Ein einfacher Ansatz ist, den Bruchteil einer Sekunde zwischen dem Starten von Tasks zu schlafen oder eine Token-Bucket-Bibliothek zu verwenden, die zu deinem Stack passt.
Tools und JSON-Modus
Character-Bots benötigen oft strukturierte Ausgaben: einen Stimmungs-Score, eine Inventar-Aktualisierung, eine Liste von Auswahlmöglichkeiten für den Spieler. Der JSON-Modus macht die Antwort zu gültigem JSON, und du beschreibst die Form im 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"])Function Calling nutzt die Standardfelder tools und tool_choice. Das Modell gibt einen tool_calls-Eintrag zurück, dein Code führt die Funktion aus, und du sendest das Ergebnis als Nachricht mit role: "tool" zurück.
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)Teste dies gegen deine eigenen Prompts, bevor du dich darauf verlässt. Open-Weight-Modelle unterscheiden sich darin, wie zuverlässig sie einen Tool Call ausgeben. Halte daher einen Fallback-Pfad bereit, wenn tool_calls leer ist.
Fehler und Ratenlimits behandeln
Ein Voll-Key erlaubt 8 gleichzeitige Anfragen und 300 Anfragen pro Minute. Ein Trial-Key erlaubt 2 und 60. Über einem Limit erhältst du HTTP 429 mit dem Fehlercode rate_limited (zu viele pro Minute) oder concurrency (zu viele gleichzeitig). Eine temporäre Überlastung gibt ebenfalls 429 zurück, mit einem Retry-After: 5-Header. Das SDK löst für diese RateLimitError aus, und du kannst den Aufruf in eine Wiederholung einpacken.
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")Wenn du viele Unterhaltungen aus einem Prozess heraus ausführst, beschränke sie mit einem Semaphore, damit nie mehr als 8 Anfragen gleichzeitig laufen. Mit asyncio und AsyncOpenAI reicht asyncio.Semaphore(8) um jeden Aufruf herum. Die Response-Header X-RateLimit-Limit-Requests und X-RateLimit-Limit-Concurrency bestätigen die Limits, die für deinen Schlüssel gelten, und X-Balance-USD zeigt dein verbleibendes Guthaben an.
Fehlgeschlagene oder abgelehnte Anfragen werden nicht berechnet, daher kosten Wiederholungen bei Fehlern dich nichts. Wenn dein Guthaben niedrig wird, lade von $20 bis $500 auf; Beträge ab $50 erhalten einen Bonus von 5 %, 10 % oder 15 % bei den Stufen $50, $100 und $200. Details findest du auf der Preisliste, und die vollständige Parameterliste findest du in den Dokumenten.
Verfolgen, was jede Sitzung kostet
Jede nicht-gestreamte Antwort enthält ein usage-Objekt mit prompt_tokens und completion_tokens. Wenn du streamst und nach Nutzung fragst, enthält der letzte Chunk diese Informationen. Rechne diese Zahlen mit einer kleinen Funktion in Dollar um und protokolliere sie neben der Sitzungs-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}")Mit diesen Zahlen kannst du praktische Fragen beantworten. Wenn eine durchschnittliche Sitzung 40 Züge hat, mit Historie, die von 500 auf 6.000 Eingabe-Token und 250 Ausgabe-Token pro Antwort wächst, ist der durchschnittliche Input etwa 3.250 Token. Die Input-Kosten pro Zug sind etwa 3.250 x $0,15 / 1.000.000 = $0,00049 und Output ist 250 x $0,50 / 1.000.000 = $0,000125, also rund $0,00061 pro Zug und $0,0245 für die 40 Züge. Ein Benutzer, der 20 Sitzungen pro Monat spielt, kostet dich etwa 49 Cent. Das ist eine Zahl, an der du die Preisgestaltung eines Produkts ausrichten kannst.
Führe den Verbindungstest in einer virtuellen Umgebung aus, damit die Paketversion für das Projekt fest bleibt, und liste die Modelle einmal mit client.models.list() beim Start auf. Wenn dieser Aufruf fehlschlägt, erfährst du frühzeitig von einem falschen Schlüssel oder einer falschen Basis-URL, bevor ein Benutzer es merkt, und kannst eine klare Meldung ausgeben, anstatt einen Stack-Trace tief in einem Chat-Loop. Teams, die diesen Code bereitstellen, fügen denselben Aufruf oft zu einem Health-Check-Endpunkt hinzu.
Protokolliere die Kosten pro Sitzung und schaue dir die obersten fünf Prozent an. Lange Sitzungen, die den Verlauf nie kürzen, dominieren meist die Rechnung. Die Lösung ist der im vorherigen Abschnitt beschriebene Kürzungs- oder Zusammenfassungsansatz.