Python 版 Character AI API:OpenAI SDK 配置
要使用 Character AI API Python 工作流,请安装官方的 openai 包,将其 base URL 指向兼容 OpenAI 的接口,并将 model 设置为 uncensored。本页面其余部分将在此基础上构建一个带有历史记录、流式输出、重试机制和成本追踪的小型角色聊天应用。
已更新

要点
- 标准 SDK 中有两个值需要修改:base_url 和 api_key。
- 角色行为由 system message 和你每轮重新发送的历史记录决定。
- 流式输出、函数调用和 JSON 模式都通过同一个客户端工作。
- 处理 HTTP 429 时短暂等待,并在全量密钥上将并发调用限制为 8。
安装与连接
没有专门的客户端库。Python 中的 Character 应用与其他应用一样使用相同的 openai 包。安装它并将你的密钥保存在环境变量中。
pip install openai
export API_KEY="paste-your-key-here"首先从 API 密钥页面 获取密钥。新账户只需点击一次即可领取 $0.50 的免费试用额度,无需信用卡。然后创建客户端:
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)如果打印出问候语和使用量对象,说明连接正常。该服务提供 POST /v1/chat/completions 和 GET /v1/models。非文本聊天的功能(如图像、嵌入或微调)不可用。
带记忆的角色聊天循环
API 是无状态的。它不记得上一轮对话,因此你的程序必须每次发送完整的对话。对于角色设定,这意味着一个 system message 后跟交替的用户和助手消息。此循环将这些消息保存在列表中。
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)采样设置直接传递给模型:temperature、top_p、stop、seed 以及频率和存在惩罚。对于角色扮演,0.8 到 1.0 之间的 temperature 通常能产生更生动的对话,而较低的值适合结构化任务。当希望在相似条件下比较两个提示词版本时,请设置 seed。
保存和重新加载对话
脚本退出时消失的聊天只是演示,而非应用。将历史记录存储为 JSON 文件是使其具有持久感的最小步骤。下面的辅助函数会在存在时加载角色的已保存消息,并在每轮后写回。
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))在启动时调用 load,在追加助手回复后调用 save。为每个角色和用户保留一个文件,你就已经实现了多角色设置。一旦文件无法满足需求,相同的字典列表可直接适配数据库列或键值存储,无需更改,因为它完全符合 API 的预期格式。
思考你存储的内容。历史记录可能包含用户输入的个人信息。发送到该 API 的提示词不会用于训练,但你的文件和日志由你负责,因此请决定保留它们多久以及谁可以读取它们。
在成本过高前修剪历史记录
上下文窗口为 100,000 个 token,包括提示词和补全。长时间的对话可能会逐渐达到该限制,且成本会随之增长,因为每轮你都要为完整的历史记录支付输入 token 的费用。一种简单的方法是保留 system message 和最后 N 次交互。
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),
)对于长故事,更好的设计是滚动摘要。每 30 条消息,让模型以 200 字总结较早的部分,将这些消息替换为 system message 中的摘要,然后继续。你会丢失一些细节,但保留情节线索,且每轮成本保持平稳。
以下是历史记录达到 8,000 个 token 且回复为 300 个 token 时的计算:输入成本为 8,000 x $0.15 / 1,000,000 = $0.0012,输出成本为 300 x $0.50 / 1,000,000 = $0.00015,即每轮 $0.00135。将历史记录修剪至 2,000 个 token 可将每轮成本降至 $0.0003 + $0.00015 = $0.00045。对于大多数对话,这仅为原价的三分之一。
流式输出正在编写的回复
对于聊天界面,你希望文本在生成时显示。设置 stream=True 并遍历 chunks。流式输出通过服务器发送事件运行,你可以在最后一个 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)请记住,流式请求会占用并发槽位直到流结束。全量密钥可同时运行 8 个;试用密钥仅 2 个。如果用户关闭标签页,请确保你的服务器也关闭上游流,否则它会继续占用槽位。
使用 asyncio 同时运行多个聊天
同时处理许多用户的 Web 服务需要异步客户端。模式很简单:一个共享的 AsyncOpenAI 客户端,一个大小等于并发限制的信号量,以及每个对话一个协程。
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())创建了 20 个任务,但只有 8 个同时运行。其余任务在信号量中等待,因此你永远不会触发 concurrency 错误。如果你的服务处理流式回复,请记住每个打开的流在结束前都会计入并发限制,这意味着客户端的慢速读取者可能会比预期更久地占用槽位。在客户端设置超时,并取消已离开用户的流。
每分钟限制是独立的。全量密钥允许每分钟 300 次请求,20 次短调用突发没问题,但发送数千次调用的循环需要限速。一种简单的方法是在任务启动之间休眠几分之一秒,或使用适合你技术栈的令牌桶库。
工具与 JSON 模式
角色机器人通常需要结构化输出:心情评分、库存更新、玩家选项列表。JSON 模式使回复成为有效的 JSON,你可以在提示词中描述其结构。
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"])函数调用使用标准的 tools 和 tool_choice 字段。模型返回 tool_calls 条目,你的代码执行函数,然后将结果以 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)在依赖此功能前,请用你自己的提示词进行测试。开放权重模型在可靠发出函数调用方面存在差异,因此当 tool_calls 为空时,请保留备用路径。
处理错误与速率限制
全量密钥允许 8 个并发请求和每分钟 300 次请求。试用密钥允许 2 个和 60 个。超过限制时,你会收到 HTTP 429 错误,错误代码为 rate_limited(每分钟过多)或 concurrency(同时过多)。临时过载也返回 429,并带有 Retry-After: 5 头。SDK 会为此抛出 RateLimitError,你可以将调用包装在重试逻辑中。
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")如果从一个进程运行多个对话,请使用信号量限制它们,以确保处理中的请求不超过 8 个。使用 asyncio 和 AsyncOpenAI,在每个调用周围使用 asyncio.Semaphore(8) 即可。响应头 X-RateLimit-Limit-Requests 和 X-RateLimit-Limit-Concurrency 确认适用于你密钥的限制,X-Balance-USD 显示你的剩余额度。
失败或被拒绝的请求不会收费,因此错误重试不会产生费用。当余额不足时,可从 $20 充值至 $500;$50 及以上金额享有 5%、10% 或 15% 的奖金(分别在 $50、$100 和 $200 档位)。详情见 定价页面,完整参数列表见 文档。
追踪每次会话的成本
每个非流式响应都包含一个 usage 对象,其中包含 prompt_tokens 和 completion_tokens。当你流式输出并请求使用量时,最后一个 chunk 会携带该信息。通过一个小函数将这些数字转换为美元,并记录在会话 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}")通过这些数字,你可以回答实际问题。如果平均会话为 40 轮,历史记录从 500 个输入 token 增长到 6,000 个,每条回复 250 个输出 token,平均输入约为 3,250 个 token。每轮输入成本约为 3,250 x $0.15 / 1,000,000 = $0.00049,输出为 250 x $0.50 / 1,000,000 = $0.000125,即每轮约 $0.00061,40 轮为 $0.0245。每月玩 20 个会话的用户成本约为 49 美分。这是一个你可以据此定价产品的数字。
在虚拟环境中运行连接检查,以便包版本在项目期间保持固定,并在启动时使用 client.models.list() 列出模型。如果该调用失败,你可以在任何用户之前发现密钥错误或 base URL 错误,并打印清晰的错误消息,而不是在聊天循环深处出现堆栈跟踪。部署此代码的团队通常会将相同的调用添加到健康检查路由中。
记录每次会话的成本并查看前 5%。那些从不修剪历史记录的长会话通常会主导账单,解决方法是前述的修剪或摘要方法。