繁中 ▾
取得 API 金鑰

Python 版 Character AI API:OpenAI SDK 設定

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

平台上的終端機將聊天氣泡串流輸出至連結的方塊,代表 Python 聊天客戶端

重點摘要

  1. 標準 SDK 中有兩個值需要變更:base_url 與 api_key。
  2. 角色行為來自於 system message 加上你每輪重新傳送的歷史記錄。
  3. 串流輸出、函式呼叫與 JSON 模式均可透過同一個客戶端使用。
  4. 遇到 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% 的數據。從未截斷歷史記錄的長工作階段通常會佔據大部分帳單,解決方案就是前述的截斷或摘要方法。

問答

有官方的 Character.ai Python 函式庫嗎?

此服務並非 Character.ai,也沒有專屬程式庫。你只需使用標準的openai套件,搭配上述的base_url與模型 ID 即可。

如何讓角色在訊息間保持一致?

將人格設定放在 system 提示詞中,並在每次請求時重新傳送最近的對話歷史。API 不會為你儲存對話。

可以使用非同步(async)客戶端嗎?

可以。AsyncOpenAI接受相同的base_url與api_key。完整金鑰的並行請求上限為 8,試用金鑰為 2。

每次聊天輪次的成本是多少?

若輸入 1,500 個 token 且輸出 300 個 token,費用為 $0.000375(基於每 1M 個 token 輸入 $0.15、輸出 $0.50 計算)。較長的歷史記錄會增加輸入 token 的比例。

Python SDK 支援串流輸出嗎?

支援。設定 stream=True 並遍歷(iterate)回傳的區塊即可。用量資訊會在串流結束時傳送。

只差一張表單,即可取得金鑰

建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。

取得 API 金鑰