KO ▾
API 키 받기

파이썬용 Character AI API: OpenAI SDK 설정

Character AI API 파이썬 워크플로우를 사용하려면 공식 openai 패키지를 설치하고 base URL을 OpenAI 호환 엔드포인트에 지정한 후 모델을 uncensored로 설정하십시오. 이 페이지의 나머지는 기록, 스트리밍, 재시도 및 비용 추적이 포함된 작은 페르소나 채팅을 구축합니다.

터미널에서 스트리밍 채팅 말풍선이 연결된 큐브로 표시되는 플랫폼

주요 포인트

  1. 표준 SDK에서 두 가지 값이 변경됩니다: base_url 및 api_key입니다.
  2. 캐릭터 행동은 시스템 메시지와 매 턴마다 다시 보내는 기록에서 비롯됩니다.
  3. 스트리밍, 도구 호출 및 JSON 모드는 모두 동일한 클라이언트를 통해 작동합니다.
  4. HTTP 429를 짧은 대기 시간으로 처리하고 전체 키의 경우 동시 호출을 8로 제한하십시오.

설치 및 연결

특별한 클라이언트 라이브러리가 없습니다. 파이썬용 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는 상태가 없습니다. 마지막 턴을 기억하지 않으므로 프로그램이 매번 전체 대화를 보내야 합니다. 페르소나의 경우 시스템 메시지와 교대로 나오는 사용자 및 어시스턴트 메시지가 필요합니다. 이 루프는 이를 목록에 유지합니다.

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 토큰입니다. 긴 역할극은 시간이 지남에 따라 그 수준에 도달할 수 있으며, 매 턴마다 전체 기록에 대한 입력 토큰에 대해 지불하므로 비용이 증가합니다. 간단한 접근 방식은 시스템 메시지와 마지막 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 토큰에 도달하고 300 토큰의 응답이 있는 채팅의 계산: 입력은 8,000 x $0.15 / 1,000,000 = $0.0012, 출력은 300 x $0.50 / 1,000,000 = $0.00015이므로 턴당 $0.00135입니다. 해당 기록을 2,000 토큰으로 줄이면 턴이 $0.0003 + $0.00015 = $0.00045로 줄어듭니다. 대부분의 대화에서 이는 3분의 1의 가격입니다.

작성되는 대로 응답 스트리밍

채팅 인터페이스의 경우 텍스트가 생성되는 대로 표시되기를 원합니다. stream=True을 설정하고 청크를 반복하십시오. 스트리밍은 서버 전송 이벤트를 통해 실행되며 마지막 청크에서 사용량을 요청할 수 있습니다.

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로 여러 채팅 동시에 실행

동시에 많은 사용자를 처리하는 웹 서비스에는 비동기 클라이언트가 필요합니다. 패턴은 간단합니다: 하나의 공유 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개는 괜찮지만, 수천 개의 호출을 보내는 루프에는 페이싱이 필요합니다. 간단한 접근 방식은 작업 시작 사이에 1초 미만으로 잠시 대기(sleep)하거나 스택에 맞는 토큰 버킷 라이브러리를 사용하는 것입니다.

도구 및 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개를 허용합니다. 제한을 초과하면 오류 코드 rate_limited(분당 너무 많음) 또는 concurrency(동시에 너무 많음)과 함께 HTTP 429를 받습니다. 일시적인 과부하도 Retry-After: 5 헤더와 함께 429를 반환합니다. 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은 API 키에 적용되는 제한을 확인해 주며, 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에서 6,000 입력 토큰으로 증가하며 응답당 250 출력 토큰인 경우 평균 입력은 약 3,250 토큰입니다. 턴당 입력 비용은 약 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 파이썬 라이브러리가 있나요?

이 서비스는 Character.ai가 아니며 별도의 라이브러리를 제공하지 않습니다. 위에 명시된 Base URL과 모델 ID를 사용하여 표준 openai 패키지를 사용하십시오.

메시지 간에 캐릭터의 일관성을 유지하려면 어떻게 해야 하나요?

페르소나를 시스템 메시지에 넣고 매 요청마다 최근 이력을 다시 보내십시오. API는 대화를 저장하지 않습니다.

비동기 클라이언트를 사용할 수 있나요?

네. AsyncOpenAI는 동일한 base_url과 api_key를 허용합니다. 전체 키의 경우 동시 호출을 8개까지, 체험 키의 경우 2개까지 제한하십시오.

채팅 한 턴의 비용은 얼마인가요?

입력 토큰 1,500개와 출력 토큰 300개의 경우 토큰 100만 개당 $0.15와 $0.50을 기준으로 $0.000375입니다. 긴 이력은 입력 비율을 높입니다.

Python SDK에서 스트리밍이 작동하나요?

네. stream=True를 전달하고 청크를 반복하십시오. 사용량은 스트림 끝에 전송됩니다.

키는 양식 하나만 작성하면 받을 수 있습니다

계정을 생성하고 키를 복사한 후 base URL을 변경하십시오. 설정은 이것으로 끝입니다.

API 키 받기