Python 版 Character AI API:OpenAI SDK 設定
若要使用 Character AI Python API 工作流程,請安裝官方的openai套件,將其base_url指向相容於 OpenAI 的端點,並將model設為uncensored。本頁其餘內容將在此基礎上,建立具備歷史記錄、串流輸出、重試機制與成本追蹤的小型角色聊天應用。
更新

重點摘要
- 標準 SDK 中有兩個值需要變更:base_url 與 api_key。
- 角色行為來自於 system message 加上你每輪重新傳送的歷史記錄。
- 串流輸出、函式呼叫與 JSON 模式均可透過同一個客戶端使用。
- 遇到 HTTP 429 錯誤時稍作等待,並將完整金鑰的並行請求上限設為 8。
安裝與連接
沒有專屬的客戶端程式庫。Python 角色應用程式使用與其他程式碼相同的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 之間通常能產生更生動的對話,而較低的值則適合結構化任務。若想在類似條件下比較兩種提示詞版本,請設定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 費用,成本會隨之增加。一種簡單的做法是保留系統提示詞與最後 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 字摘要較舊的部分,並將這些訊息替換為系統提示詞中的摘要,然後繼續進行。你會失去部分細節,但能保留劇情線,且每次輪次的成本保持固定。
以下是歷史記錄達到 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並遍歷回傳的區塊。串流輸出透過伺服器發送事件(SSE)運行,你可以在最後一個區塊中請求用量資訊。
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 個短請求的突發流量沒問題,但發送數千個請求的迴圈需要控制節奏。簡單的做法是在啟動任務之間暫停一小部分秒數,或使用符合你技術堆疊的令牌桶(token bucket)程式庫。
工具與 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 及以上的金額享有獎金,在 $50、$100 與 $200 等級分別為 5%、10% 與 15%。詳情請見定價頁面,完整參數列表請見文件。
追蹤每個工作階段的成本
每個非串流回應都包含一個usage物件,內含prompt_tokens與completion_tokens。當你啟用串流並請求用量時,最終區塊會包含該資訊。透過一個小型函式將這些數字轉換為美元金額,並將其記錄在工作階段 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% 的數據。從未截斷歷史記錄的長工作階段通常會佔據大部分帳單,解決方案就是前述的截斷或摘要方法。