中文 ▾
获取 API 密钥

Python 版 Character AI API:OpenAI SDK 配置

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

终端在平台上流式显示聊天气泡并链接到立方体,代表 Python 聊天客户端

要点

  1. 标准 SDK 中有两个值需要修改:base_url 和 api_key。
  2. 角色行为由 system message 和你每轮重新发送的历史记录决定。
  3. 流式输出、函数调用和 JSON 模式都通过同一个客户端工作。
  4. 处理 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%。那些从不修剪历史记录的长会话通常会主导账单,解决方法是前述的修剪或摘要方法。

问答

Character.ai 有官方的 Python 库吗?

该服务不是 Character.ai,也没有独立的库。你使用标准的 openai 包,并传入上方给出的 Base URL 和模型 ID。

如何在不同消息间保持角色一致性?

将角色设定放入 system 提示词,并在每次请求时重新发送最近的对话历史。API 不会为你存储对话。

可以使用异步客户端吗?

可以。AsyncOpenAI 接受相同的 base_url 和 API 密钥。全量密钥的并发请求限制为 8,试用密钥限制为 2。

一次对话轮次花费多少?

若输入 1,500 个 token,输出 300 个 token,费用为 $0.000375(基于每 1M token $0.15 和 $0.50 的定价)。更长的历史会增加输入 token 的占比。

Python SDK 支持流式输出吗?

支持。传入 stream=True 并遍历返回的 chunks。用量信息会在流结束时发送。

只差一张表单,即可获得密钥

创建账户,复制密钥,更改基础 URL。这就是全部设置。

获取 API 密钥