PT ▾
Obter chave de API

API Character AI em Python: configuração do SDK OpenAI

Para usar um fluxo de trabalho de API de IA de personagem em Python, instale o pacote oficial da OpenAI, aponte sua base URL para um endpoint compatível com OpenAI e defina o modelo como uncensored. O restante desta página cria um pequeno chat de persona com base nisso, com histórico, streaming, retentativas e rastreamento de custos.

Terminal em uma plataforma com streaming de bolhas de chat em cubos vinculados, representando um cliente de chat Python

Pontos principais

  1. Dois valores mudam no SDK padrão: base_url e api_key.
  2. O comportamento do personagem vem da mensagem do sistema mais o histórico que você reenvia a cada turno.
  3. Streaming, chamada de funções e modo JSON funcionam todos através do mesmo cliente.
  4. Trate HTTP 429 com uma breve espera e limite chamadas simultâneas para 8 em uma chave completa.

Instalar e conectar

Não há biblioteca de cliente especial. Apps de personagem em Python usam o mesmo pacote openai que tudo mais. Instale-o e mantenha sua chave em uma variável de ambiente.

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

Obtenha uma chave na página da chave de API primeiro. Contas novas podem reivindicar $0,50 de crédito de teste lá com um clique, sem necessidade de cartão. Depois crie o cliente:

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 isso imprimir uma saudação e um objeto de uso, a conexão está boa. O serviço expõe POST /v1/chat/completions e GET /v1/models. Qualquer coisa que não seja chat de texto, como imagens, embeddings ou fine-tuning, não está disponível.

Um loop de chat de personagem com memória

A API é stateless. Ela não lembra o último turno, então seu programa deve enviar toda a conversa cada vez. Para uma persona, isso significa uma mensagem do sistema seguida por mensagens alternadas de usuário e assistente. Este loop as mantém em uma lista.

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)

Configurações de amostragem são passadas para o modelo: temperature, top_p, stop, seed e as penalidades de frequência e presença. Para roleplay, uma temperatura entre 0,8 e 1,0 geralmente dá diálogos mais animados, enquanto um valor mais baixo é adequado para tarefas estruturadas. Defina seed quando quiser comparar duas versões de prompt sob condições semelhantes.

Salvar e recarregar uma conversa

Um chat que desaparece quando o script sai é uma demo, não um app. Armazenar o histórico como um arquivo JSON é o menor passo que o faz parecer persistente. O helper abaixo carrega as mensagens salvas de um personagem se existirem e as grava de volta após cada 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))

Chame load na inicialização e save depois de anexar a resposta do assistente. Mantenha um arquivo por personagem e por usuário, e você já tem uma configuração multi-personagem. Uma vez que você supere arquivos, a mesma lista de dicts cabe em uma coluna de banco de dados ou um armazenamento key-value sem mudança, porque é exatamente o que a API espera.

Pense no que você armazena. O histórico pode conter detalhes pessoais que os usuários digitaram. Prompts enviados para esta API não são usados para treinamento, mas seus próprios arquivos e logs são sua responsabilidade, então decida por quanto tempo os mantém e quem pode lê-los.

Corte o histórico antes que fique caro

A janela de contexto tem 100.000 tokens, prompt mais completion. Um roleplay longo pode atingir isso com o tempo, e o custo cresce com isso porque você paga tokens de entrada para o histórico completo em cada turno. Uma abordagem simples mantém a mensagem do sistema e as últimas N trocas.

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

Um design melhor para histórias longas é um resumo móvel. A cada 30 mensagens, peça ao modelo para resumir a parte mais antiga em 200 palavras, substitua essas mensagens pelo resumo dentro da mensagem do sistema e continue. Você perde alguns detalhes, mas mantém os fios da trama, e o custo por turno permanece plano.

Aqui está o cálculo para um chat que atingiu 8.000 tokens de histórico com uma resposta de 300 tokens: o input é 8.000 x $0,15 / 1.000.000 = $0,0012, o output é 300 x $0,50 / 1.000.000 = $0,00015, totalizando $0,00135 por turno. Reduzir esse histórico para 2.000 tokens reduz o turno para $0,0003 + $0,00015 = $0,00045. Isso é um terço do preço para a maioria das conversas.

Transmitir respostas conforme são escritas

Para uma interface de chat, você quer que o texto apareça conforme é gerado. Defina stream=True e itere sobre os chunks. Streaming roda sobre server-sent events, e você pode pedir uso no último 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)

Lembre-se de que uma requisição streaming mantém seu slot de concorrência até o stream acabar. Em uma chave completa você pode rodar 8 ao mesmo tempo; em uma chave de teste apenas 2. Se um usuário fechar a aba, certifique-se de que seu servidor feche o stream upstream também, ou ele manterá o slot ocupado.

Execute muitos chats ao mesmo tempo com asyncio

Um serviço web que lida com muitos usuários ao mesmo tempo precisa do cliente async. O padrão é simples: um cliente AsyncOpenAI compartilhado, um semaphore dimensionado para seu limite de concurrency, e uma coroutine por conversa.

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

Vinte jobs são criados, mas apenas oito rodam ao mesmo tempo. O resto espera sua vez dentro do semaphore, então você nunca aciona o erro concurrency. Se seu serviço lida com respostas streaming, lembre-se de que cada stream aberto conta até terminar, o que significa que leitores lentos do lado do cliente podem segurar slots por mais tempo do que você espera. Defina um timeout no cliente e cancele streams cujos usuários foram embora.

O limite por minuto é separado. Com 300 requisições por minuto em uma chave completa, um burst de 20 chamadas curtas não é problema, mas um loop que envia milhares de chamadas precisa de controle de ritmo. Uma abordagem simples é pausar por uma fração de segundo entre o início de cada tarefa, ou usar uma biblioteca token bucket que se encaixe na sua stack.

Ferramentas e modo JSON

Bots de personagem muitas vezes precisam de output estruturado: uma pontuação de humor, uma atualização de inventário, uma lista de escolhas para o jogador. Modo JSON torna a resposta JSON válida, e você descreve a forma no 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"])

Chamada de funções usa os campos padrão tools e tool_choice. O modelo retorna uma entrada tool_calls, seu código executa a função, e você envia o resultado de volta como uma mensagem com 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)

Teste isso contra seus próprios prompts antes de confiar nele. Modelos de pesos abertos diferem em quão confiavelmente eles emitem uma chamada de função, então mantenha um caminho de fallback quando tool_calls estiver vazio.

Tratar erros e limites de taxa

Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Uma chave de teste permite 2 e 60. Ao ultrapassar o limite, você recebe HTTP 429 com o código de erro rate_limited (muitas por minuto) ou concurrency (muitas ao mesmo tempo). Uma sobrecarga temporária também retorna 429, com o cabeçalho Retry-After: 5. O SDK gera RateLimitError para esses casos, e você pode envolver a chamada em uma retentativa.

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 você executar muitas conversas de um único processo, limite-as com um semáforo para nunca exceder 8 requisições em andamento. Com asyncio e AsyncOpenAI, um asyncio.Semaphore(8) ao redor de cada chamada é suficiente. Os cabeçalhos de resposta X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency confirmam os limites aplicáveis à sua chave, e X-Balance-USD mostra seu crédito restante.

Requisições com falha ou recusadas não são cobradas, então novas tentativas após erros não custam nada. Quando seu saldo está baixo, recarregue de $20 a $500; valores a partir de $50 recebem um bônus de 5%, 10% ou 15% nos níveis $50, $100 e $200. Detalhes estão na página de preços, e a lista completa de parâmetros está na documentação.

Rastrear o custo de cada sessão

Toda resposta sem streaming inclui um objeto usage com prompt_tokens e completion_tokens. Quando você usa streaming e pede o uso, o último chunk o carrega. Converta esses números em dólares com uma pequena função e registre ao lado do ID da sessão.

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

Com esses números você pode responder perguntas práticas. Se uma sessão média tem 40 turnos, com histórico crescendo de 500 para 6.000 tokens de input e 250 tokens de output por resposta, a média de input é aproximadamente 3.250 tokens. Custo de input por turno é cerca de 3.250 x $0,15 / 1.000.000 = $0,00049 e output é 250 x $0,50 / 1.000.000 = $0,000125, então cerca de $0,00061 por turno e $0,0245 para os 40 turnos. Um usuário que joga 20 sessões por mês custa a você cerca de 49 centavos. Esse é um número em torno do qual você pode precificar um produto.

Rode a verificação de conexão dentro de um ambiente virtual para que a versão do pacote fique fixa para o projeto, e liste os modelos uma vez com client.models.list() na inicialização. Se essa chamada falhar, você aprende sobre uma chave errada ou uma base URL errada antes que qualquer usuário faça, e você pode imprimir uma mensagem clara em vez de um stack trace profundo dentro de um loop de chat. Equipes que deployam este código muitas vezes adicionam a mesma chamada a uma rota de health check.

Registre o custo por sessão e olhe para os cinco por cento superiores. Sessões longas que nunca cortam o histórico geralmente dominam a conta, e a correção é a abordagem de corte ou resumo descrita anteriormente.

Perguntas e respostas

Existe uma biblioteca Python oficial para Character.ai?

Este serviço não é o Character.ai e não possui biblioteca separada. Você usa o pacote openai padrão com a base URL e o ID do modelo fornecidos acima.

Como manter um personagem consistente entre as mensagens?

Coloque a persona na mensagem do sistema e reenvie o histórico recente com cada requisição. A API não armazena conversas para você.

Posso usar o cliente assíncrono?

Sim. AsyncOpenAI aceita o mesmo base_url e api_key. Limite as chamadas simultâneas a 8 em uma chave completa ou 2 em uma chave de teste.

Quanto custa uma rodada de chat?

Com 1.500 tokens de entrada e 300 tokens de saída, o custo é $0,000375, com base em $0,15 e $0,50 por 1M de tokens. Histórico mais longo aumenta a parcela de entrada.

O streaming funciona com o SDK Python?

Sim. Passe stream=True e itere sobre os chunks. O uso é enviado no final do streaming.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de API