FR ▾
Obtenir une clé API

API Character AI en Python : configuration du SDK OpenAI

Pour utiliser un flux de travail API Character AI en Python, installez le package openai officiel, pointez son URL de base vers un endpoint compatible OpenAI et définissez le modèle sur uncensored. Le reste de cette page construit un petit chat de persona au-dessus, avec historique, streaming, tentatives et suivi des coûts.

Terminal sur une plateforme diffusant des bulles de chat dans des cubes liés, représentant un client de chat Python

Points clés

  1. Deux valeurs changent dans le SDK standard : base_url et api_key.
  2. Le comportement du personnage provient du prompt système plus l'historique que vous renvoyez à chaque tour.
  3. Le streaming, l'appel de fonctions et le mode JSON fonctionnent tous via le même client.
  4. Gérez le 429 HTTP avec une courte attente et limitez les appels simultanés à 8 sur une clé complète.

Installation et connexion

Il n'y a pas de bibliothèque cliente spéciale. Les applications Character en Python utilisent le même package openai que tout le reste. Installez-le et conservez votre clé dans une variable d'environnement.

pip install openai
export API_KEY="paste-your-key-here"

Obtenez une clé depuis la page clé API d'abord. Les nouveaux comptes peuvent réclamer 0,50 $ de crédit d'essai gratuit en un clic, sans carte. Ensuite, créez le 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)

Si cela affiche un message d'accueil et un objet d'utilisation, la connexion est bonne. Le service expose POST /v1/chat/completions et GET /v1/models. Tout ce qui n'est pas du chat textuel, comme les images, les embeddings ou le fine-tuning, n'est pas disponible.

Boucle de chat de personnage avec mémoire

L'API est sans état. Elle ne se souvient pas du dernier tour, donc votre programme doit envoyer toute la conversation à chaque fois. Pour un persona, cela signifie un message système suivi de messages alternés utilisateur et assistant. Cette boucle les conserve dans une 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)

Les paramètres d'échantillonnage sont transmis au modèle : temperature, top_p, stop, seed et les pénalités de fréquence et de présence. Pour le jeu de rôle, une température entre 0,8 et 1,0 donne généralement des dialogues plus animés, tandis qu'une valeur plus basse convient aux tâches structurées. Définissez seed lorsque vous souhaitez comparer deux versions de prompt dans des conditions similaires.

Sauvegarder et recharger une conversation

Une conversation qui disparaît à la fermeture du script est une démo, pas une application. Enregistrer l'historique dans un fichier JSON est la première étape pour le rendre persistant. La fonction utilitaire ci-dessous charge les messages sauvegardés d'un personnage s'ils existent et les réécrit après chaque tour.

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))

Appelez load au démarrage et save après avoir ajouté la réponse de l'assistant. Conservez un fichier par personnage et par utilisateur, et vous avez déjà une configuration multi-personnages. Une fois que vous dépassez les fichiers, la même liste de dictionnaires convient à une colonne de base de données ou à un magasin clé-valeur sans changement, car c'est exactement ce que l'API attend.

Réfléchissez à ce que vous stockez. L'historique peut contenir des détails personnels que les utilisateurs ont saisis. Les prompts envoyés à cette API ne sont pas utilisés pour l'entraînement, mais vos propres fichiers et journaux sont votre responsabilité, alors décidez combien de temps vous les conservez et qui peut les lire.

Réduire l'historique avant qu'il ne devienne coûteux

La fenêtre de contexte est de 100 000 tokens, prompt plus réponse. Un long jeu de rôle peut atteindre cette limite avec le temps, et le coût augmente car vous payez les tokens d'entrée pour tout l'historique à chaque tour. Une approche simple conserve le prompt système et les N derniers échanges.

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),
)

Une meilleure conception pour les longues histoires est un résumé roulant. Tous les 30 messages, demandez au modèle de résumer la partie plus ancienne en 200 mots, remplacez ces messages par le résumé dans le message système, et continuez. Vous perdez certains détails mais conservez les fils de l'intrigue, et le coût par tour reste plat.

Voici les calculs pour un chat ayant atteint 8 000 tokens d'historique avec une réponse de 300 tokens : l'entrée est 8 000 x 0,15 $ / 1 000 000 = 0,0012 $, la sortie est 300 x 0,50 $ / 1 000 000 = 0,00015 $, soit 0,00135 $ par tour. Réduire cet historique à 2 000 tokens abaisse le tour à 0,0003 $ + 0,00015 $ = 0,00045 $. C'est un tiers du prix pour la plupart des conversations.

Diffuser les réponses au fur et à mesure de leur rédaction

Pour une interface de chat, vous voulez que le texte apparaisse au fur et à mesure de sa génération. Définissez stream=True et itérez sur les chunks. Le streaming s'exécute via les événements envoyés par le serveur, et vous pouvez demander l'utilisation dans le dernier 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)

N'oubliez pas qu'une requête en streaming occupe son slot de concurrence jusqu'à la fin du flux. Avec une clé complète, vous pouvez en exécuter 8 simultanément ; avec une clé d'essai, seulement 2. Si un utilisateur ferme l'onglet, assurez-vous que votre serveur ferme également le flux amont, sinon il conserve le slot occupé.

Exécuter plusieurs chats simultanément avec asyncio

Un service web qui gère de nombreux utilisateurs simultanément a besoin du client asynchrone. Le modèle est simple : un client AsyncOpenAI partagé, un sémaphore de taille égale à votre limite de concurrence, et une coroutine par conversation.

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())

Vingt tâches sont créées, mais seulement huit s'exécutent simultanément. Le reste attend son tour dans le sémaphore, donc vous ne déclenchez jamais l'erreur concurrency. Si votre service gère des réponses en streaming, n'oubliez pas que chaque flux ouvert compte jusqu'à sa fin, ce qui signifie que les lecteurs lents du côté client peuvent occuper des slots plus longtemps que prévu. Définissez un délai d'attente sur le client et annulez les flux dont les utilisateurs sont partis.

La limite par minute est distincte. Avec 300 requêtes par minute sur une clé complète, un pic de 20 appels courts est acceptable, mais une boucle qui envoie des milliers d'appels nécessite un rythme. Une approche simple consiste à faire une pause d'une fraction de seconde entre les lancements de tâches, ou à utiliser une bibliothèque de token bucket adaptée à votre pile.

Outils et mode JSON

Les bots de personnage ont souvent besoin de sorties structurées : un score d'humeur, une mise à jour d'inventaire, une liste de choix pour le joueur. Le mode JSON rend la réponse JSON valide, et vous décrivez la forme dans le 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"])

L'appel de fonctions utilise les champs standards tools et tool_choice. Le modèle retourne une entrée tool_calls, votre code exécute la fonction, et vous renvoyez le résultat en tant que message avec 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)

Testez cela avec vos propres prompts avant de vous y fier. Les modèles à poids ouverts diffèrent par leur fiabilité à émettre un appel de fonction, donc conservez un chemin de repli lorsque tool_calls est vide.

Gérer les erreurs et les limites de débit

Une clé complète permet 8 requêtes simultanées et 300 requêtes par minute. Une clé d'essai permet 2 et 60. Au-delà de la limite, vous obtenez un 429 HTTP avec le code d'erreur rate_limited (trop par minute) ou concurrency (trop en même temps). Une surcharge temporaire renvoie également un 429, avec l'en-tête Retry-After: 5. Le SDK lève une RateLimitError pour ces cas, et vous pouvez envelopper l'appel dans un réessai.

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")

Si vous exécutez de nombreuses conversations à partir d'un seul processus, limitez-les avec un sémaphore pour ne jamais dépasser 8 requêtes en vol. Avec asyncio et AsyncOpenAI, asyncio.Semaphore(8) autour de chaque appel suffit. Les en-têtes de réponse X-RateLimit-Limit-Requests et X-RateLimit-Limit-Concurrency confirment les limites applicables à votre clé, et X-Balance-USD affiche votre crédit restant.

Les requêtes échouées ou refusées ne sont pas facturées, donc les tentatives en cas d'erreur ne vous coûtent rien. Lorsque votre solde est faible, rechargez de 20 $ à 500 $ ; les montants à partir de 50 $ bénéficient d'un bonus de 5 %, 10 % ou 15 % aux niveaux 50 $, 100 $ et 200 $. Les détails sont sur la page de tarification, et la liste complète des paramètres est dans la documentation.

Suivre le coût de chaque session

Chaque réponse non-streaming inclut un objet usage avec prompt_tokens et completion_tokens. Lorsque vous utilisez le streaming et demandez l'utilisation, le dernier chunk le contient. Convertissez ces chiffres en dollars avec une petite fonction et journalisez-les à côté de l'ID de session.

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}")

Avec ces nombres, vous pouvez répondre à des questions pratiques. Si une session moyenne comporte 40 tours, avec un historique passant de 500 à 6 000 tokens d'entrée et 250 tokens de sortie par réponse, la moyenne d'entrée est d'environ 3 250 tokens. Le coût d'entrée par tour est d'environ 3 250 x 0,15 $ / 1 000 000 = 0,00049 $ et la sortie est 250 x 0,50 $ / 1 000 000 = 0,000125 $, soit environ 0,00061 $ par tour et 0,0245 $ pour les 40 tours. Un utilisateur qui joue 20 sessions par mois vous coûte environ 49 cents. C'est un chiffre autour duquel vous pouvez tarifier un produit.

Exécutez le test de connexion dans un environnement virtuel pour que la version du package reste fixe pour le projet, et listez les modèles une fois avec client.models.list() au démarrage. Si cet appel échoue, vous détectez une clé ou une base URL incorrecte avant qu'un utilisateur ne le fasse, et vous pouvez afficher un message clair au lieu d'une trace de pile au fond d'une boucle de chat. Les équipes qui déploient ce code ajoutent souvent le même appel à une route de vérification de santé.

Journalisez le coût par session et regardez les cinq pour cent supérieurs. Les sessions longues qui ne réduisent jamais l'historique dominent généralement la facture, et la solution est l'approche de réduction ou de résumé décrite plus tôt.

Questions et réponses

Existe-t-il une bibliothèque Python officielle pour Character.ai ?

Ce service n'est pas Character.ai et ne dispose pas de bibliothèque dédiée. Utilisez le package standard openai avec l'URL de base et l'ID de modèle indiqués ci-dessus.

Comment conserver la cohérence d’un personnage sur plusieurs messages ?

Placez le persona dans le message système et renvoyez l’historique récent à chaque requête. L’API ne conserve pas les conversations pour vous.

Puis-je utiliser le client asynchrone ?

Oui. AsyncOpenAI accepte la même base_url et clé API. Limitez les appels simultanés à 8 sur une clé complète ou 2 sur une clé d'essai.

Combien coûte un tour de chat ?

Avec 1 500 tokens d’entrée et 300 tokens de sortie, le coût est de 0,000375 $, basé sur 0,15 $ et 0,50 $ par 1 M de tokens. Un historique plus long augmente la part des tokens d’entrée.

Le streaming fonctionne-t-il avec le SDK Python ?

Oui. Passez stream=True et itérez sur les chunks. L’utilisation est envoyée à la fin du flux.

Votre clé n'est qu'à un formulaire d'ici

Créez un compte, copiez la clé, modifiez l'URL de base. C'est toute la configuration.

Obtenir une clé API