Character AI API 키: 얻는 방법과 사용법
Character AI API 키를 검색하셨다면, 먼저 알아야 할 점은 이 사이트가 Character.ai가 아니며 해당 키를 발급하지 않는다는 것입니다. 이 사이트는 캐릭터 채팅 앱의 대체 백엔드로 작동하는 독립적인 OpenAI 호환 텍스트 API용 키를 제공합니다.
업데이트됨

주요 포인트
- Google 또는 이메일과 비밀번호로 로그인한 후 API 키 페이지를 열면 키를 받을 수 있습니다.
- 신규 사용자는 카드 없이 한 번의 클릭으로 7일 동안 유효한 $0.50 무료 체험 크레딧을 받을 수 있습니다.
- Base URL https://api.characteraiapi.com/v1과 모델 ID
uncensored를 사용하여 모든 OpenAI SDK를 사용할 수 있습니다. - 키는 서버 또는 환경 변수에 보관하고, 공개적인 프론트엔드 코드에는 넣지 마세요.
실제로 제공하는 것
Character.ai는 소비자용 채팅 제품입니다. Character AI API 키를 검색하는 사람들은 보통 두 가지 중 하나를 원합니다: 자체 코드에서 캐릭터 챗봇을 호출하는 방법, 또는 호스팅된 제품의 규칙에 제한되지 않는 페르소나 앱용 백엔드입니다. 이 사이트는 두 번째 필요를 충족합니다. 가입하고 키를 받은 후 OpenAI 호환 엔드포인트로 요청을 보냅니다. 여기서는 Character.ai에 연결되거나 해당 캐릭터를 재사용하지 않습니다.
이 서비스는 독립적인 제공업체가 운영하는 단일 오픈 웨이트 모델 앞의 호스팅 텍스트 API이며, 합법적인 성인 사용에 대한 콘텐츠 거부 없이 답변하도록 조정되었습니다. 이는 어떤 모델 벤더의 공식 API가 아니며 벤더 간 라우터도 아닙니다. 모델 ID는 uncensored이며, Base URL은 https://api.characteraiapi.com/v1입니다. 두 가지 메서드가 있습니다: POST /v1/chat/completions 및 GET /v1/models.
인터페이스가 OpenAI와 일치하므로 캐릭터 구축 작업은 사용자 측에서 이루어집니다. 시스템 메시지로 페르소나를 작성하고 대화 기록을 유지한 후 각 요청에 함께 전송합니다. 이는 폐쇄형 제품에서 거의 제공하지 않는 목소리와 기억, 대화 흐름에 대한 제어권을 제공합니다. 모든 사용자에게 적용되는 하드 제한은 동일합니다: 미성년자가 관련된 성적인 콘텐츠는 절대 허용되지 않습니다.
5단계로 키 받기
전체 과정은 몇 분 정도 걸립니다. 시작하기 위해 카드가 필요하지 않습니다.
- 가입하기. Google을 사용하거나 이메일과 비밀번호로 등록하세요.
- 키 페이지 열기. 계정의 키가 표시되는 API 키 페이지로 이동하세요.
- 체험 크레딧 받기. 해당 페이지에서 한 번의 클릭으로 무료 체험 크레딧 $0.50이 추가됩니다. 이는 사람당 한 번으로 제한되며 7일 동안 유효합니다.
- 키 복사하기. 비밀번호 관리자나 시크릿 파일에 즉시 저장하세요.
- 테스트 요청 보내기. 앱 코드를 수정하기 전에 아래 curl 명령을 사용하세요.
키를 비밀번호처럼 취급하세요. 키를 가진 사람은 잔액을 사용할 수 있습니다. 누출된 것으로 생각되면 즉시 사용을 중지하고 모든 앱에서 제거한 후 예상치 못한 지출에 대해 잔액을 확인하세요.
curl로 키 테스트하기
키를 환경 변수로 설정하여 스크립트 내에서 평문으로 셸 히스토리에 남지 않도록 하세요. 그런 다음 모델을 나열합니다. 이렇게 하면 키가 작동하고 올바른 호스트에 도달했음을 확인할 수 있습니다.
export API_KEY="paste-your-key-here"
curl https://api.characteraiapi.com/v1/models \
-H "Authorization: Bearer $API_KEY"uncensored가 포함된 JSON 목록을 받아야 합니다. 이제 작은 페르소나로 첫 번째 채팅 요청을 보내세요. 시스템 메시지는 캐릭터를 설정하고, 사용자 메시지는 장면을 시작합니다.
curl https://api.characteraiapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are Mara, a dry-witted ship engineer in a space opera. Stay in character."},
{"role": "user", "content": "The reactor is humming wrong again. What do you do?"}
],
"temperature": 0.9
}'응답은 표준 채팅 완료 형태를 따릅니다. 응답 텍스트는 choices[0].message.content에 있습니다. 응답 헤더에는 X-Request-Id, X-Balance-USD 및 속도 제한 헤더도 포함되어 있어 자체 UI에 남은 잔액을 표시할 때 유용합니다.
Python 또는 Node에서 키 사용하기
Base URL과 키 두 가지 값을 변경하면 모든 OpenAI SDK가 작동합니다. 다음은 공식 openai 패키지를 사용한 Python 버전입니다.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.characteraiapi.com/v1",
api_key=os.environ["API_KEY"],
)
reply = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are Mara, a ship engineer. Stay in character."},
{"role": "user", "content": "Status report?"},
],
)
print(reply.choices[0].message.content)Node에서의 동일한 호출:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.characteraiapi.com/v1",
apiKey: process.env.API_KEY,
});
const reply = await client.chat.completions.create({
model: "uncensored",
messages: [
{ role: "system", content: "You are Mara, a ship engineer. Stay in character." },
{ role: "user", content: "Status report?" },
],
});
console.log(reply.choices[0].message.content);많은 채팅 프론트엔드에는 사용자 정의 OpenAI 호환 엔드포인트를 위한 필드가 있습니다. 이러한 도구에서는 Base URL을 붙여넣고, 키를 붙여넣으며, 모델 이름으로 uncensored를 입력합니다. 다른 변경 사항은 필요하지 않습니다. 문서 페이지에는 스트리밍, 함수 호출, JSON 모드 등 지원되는 매개변수가 나열되어 있습니다.
일반적인 키 문제 및 빠른 해결 방법
대부분의 초보자 실패는 몇 가지 작은 실수에서 비롯됩니다. 더 큰 문제를 의심하기 전에 이 순서대로 확인하세요.
- 키의 불필요한 공백 또는 따옴표. 파일에서 복사한 후행 줄바꿈도 인증 실패를 유발할 수 있습니다. 변수의 길이를 출력하고 복사한 내용과 비교하세요.
- 잘못된 Base URL. Base URL은
/v1로 끝나며, SDK는/chat/completions을 자체적으로 추가합니다. Base URL에/chat/completions을 추가하면 경로가 중복되어 요청이 실패합니다. - 잘못된 모델 이름. 모델 ID는
uncensored입니다. 다른 서비스에서 빌린 이름은 일치하지 않습니다. 서버가 보고하는 내용을 확인하려면GET /v1/models를 호출하세요. - 누락된 헤더. 원시 HTTP 호출에는
Authorization: Bearer뒤에 공백과 키가 필요하며, POST 요청에는Content-Type: application/json이 필요합니다. - 잔액이 없습니다.
X-Balance-USD응답 헤더에 남은 금액이 표시됩니다. 무료 체험 크레딧이 소진되거나 7일이 지나면 충전하지 않으면 요청이 더 이상 성공하지 않습니다. - 속도 제한. 체험 키는 분당 60회, 동시 2개의 요청을 허용합니다. 두 개의 오픈 스트림이 이미 두 슬롯을 모두 사용합니다.
잘못된 키는 일반적으로 모델 응답이 아니라 인증 오류를 반환합니다. 제한은 HTTP 429와 함께 rate_limited 또는 concurrency 코드를 생성합니다. 상태 코드뿐만 아니라 오류 본문도 읽으면 도달한 제한을 알려주는 코드로 인해 시간을 절약할 수 있습니다. 모든 응답에는 X-Request-Id이 포함됩니다. 실패한 호출을 나중에 특정 요청과 일치시키기 위해 로그에 보관하세요.
체험 제한 사항 및 체험의 혜택
체험 키는 일반 키보다 낮은 제한을 가집니다: 분당 60회, 동시 2개의 요청. 일반 키는 분당 300회, 동시 8개의 요청을 허용합니다. 단일 페르소나를 테스트하기에는 충분합니다. 테스트 스크립트에서 여러 채팅을 동시에 실행하면 HTTP 429 오류 코드 concurrency 또는 rate_limited을 보게 됩니다. 스트리밍 요청은 스트림이 끝날 때까지 동시 슬롯을 유지하므로, 체험 키에서 두 개의 오픈 스트림이 슬롯을 모두 채웁니다.
$0.50으로 얼마나 할 수 있나요? 가격은 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50입니다. 일반적인 채팅 턴을 고려하세요: 1,500개의 토큰이 히스토리와 페르소나로 입력되고 300개의 토큰이 출력됩니다.
- 입력: 1,500 토큰 x $0.15 / 1,000,000 = $0.000225
- 출력: 300 토큰 x $0.50 / 1,000,000 = $0.00015
- 한 턴: $0.000375
- $0.50 / $0.000375는 약 1,333 턴입니다.
여러 캐릭터를 제대로 테스트하기에 충분합니다. 실패하거나 거부된 요청은 요금이 부과되지 않으므로 오류가 발생한 요청은 크레딧을 소모하지 않습니다. 체험은 7일 후 만료됩니다. 나중에 구매한 크레딧은 만료되지 않습니다.
페르소나가 자연스럽게 느껴지도록 하는 설정
키가 연결을 가능하게 하지만, 캐릭터의 질은 프롬프트와 샘플링 설정에서 나옵니다. 몇 가지 습관이 기교적인 트릭보다 더 도움이 됩니다.
시스템 메시지를 평문으로 된 짧은 캐릭터 시트처럼 작성하세요: 캐릭터가 누구인지, 어떻게 말하는지, 무엇을 원하는지, 그리고 답변은 얼마나 길어야 하는지 명시하세요. 목소리가 중요하다면 대화 예시 줄을 한두 개 제공하세요. 모델은 형용사보다 구체적인 예시를 더 잘 따르므로, "마라는 짧고 건조한 문장으로 답변하며 긴장하면 농담을 한다"는 문장이 "마라는 재치 있고 매력적이다"라는 문장보다 더 효과적입니다.
temperature를 사용해 생동감을 설정하세요. 0.9에 가까운 값은 더 다양한 어휘를 생성하는 반면, 0.5에 가까운 값은 캐릭터의 일관성을 유지합니다. 앱에서 "User:"와 같은 화자 레이블을 사용하고 모델이 대화의 상대방 부분을 작성하는 것을 방지하려면 stop 시퀀스를 추가하세요. 빈도 패널티와 존재 패널티는 긴 채팅에서 반복되는 구문을 줄일 수 있지만, 너무 높은 값은 대화를 이상하게 만들 수 있으므로 부드럽게 조정하세요.
모델은 요청에 포함된 정보만 안다는 점을 기억하세요. 캐릭터가 200 메시지 전에 나온 플레이어의 이름을 기억해야 한다면, 해당 메시지를 컨텍스트 창에 유지하거나 핵심 사실을 시스템 메시지에 저장하세요. 이것이 직접 업데이트하는 메모리 리스트가 방대한 이력을 전송하는 것보다 더 나은 이유입니다.
무료 체험 크레딧이 소진될 때 충전하기
구독은 없습니다. 선불로 충전하고 토큰 단위로 사용합니다. 충전 금액은 $20부터 $500까지의 정수 금액으로 가능하며, 더 큰 금액에는 보너스가 적용됩니다: $50부터 +5%, $100부터 +10%, $200부터 +15%. 따라서 $50은 $52.50의 크레딧이 되고, $100은 $110, $200은 $230이 됩니다. 암호화폐(TRC20 기반 USDT, Base 기반 USDC)로 결제할 수 있습니다.
가격 책정 페이지에 전체 표가 있습니다. 계획을 세울 때, 1,500 입력 및 300 출력 턴당 비용은 $0.000375이므로 $20으로 약 53,000개의 턴을 처리할 수 있습니다. 장시간 역할극은 기록이 커지기 때문에 턴당 비용이 더 많이 들므로, 다시 보내는 기록의 양을 제한하세요. 컨텍스트 창은 프롬프트와 출력을 합쳐 100,000 토큰이지만, 실제로 채우려는 경우는 드뭅니다.
실제 앱에서 API 키 안전하게 보관하기
채팅 프로젝트에서 가장 흔한 실수는 브라우저 코드에서 API를 직접 호출하는 것입니다. 브라우저로 전송된 모든 것은 키를 포함해 모든 방문자가 읽을 수 있습니다. 프론트 엔드와 API 사이에 작은 서버를 두세요. 브라우저는 라우트로 통신하고, 라우트는 Authorization: Bearer 헤더를 추가한 후 요청을 전달합니다.
- 키는 저장소(repository)가 아닌 환경 변수나 시크릿 관리자에 저장하세요.
- 첫 커밋 전에
.env항목을.gitignore에 추가하세요. - 환경별로 하나의 키를 사용하세요. 이렇게 하면 개발 환경에서의 유출이 프로덕션에 영향을 미치지 않습니다.
X-Balance-USD헤더를 모니터링하여 초기에 무한 루프를 감지하세요.- HTTP 429 응답 시 짧은 대기 후 재시도하세요. 일시적인 과부하 응답에는
Retry-After: 5이 포함됩니다.
API로 전송된 프롬프트는 학습에 사용되지 않습니다. 그럼에도 불구하고, 자체 로그에 저장하는 것을 원치 않는 데이터를 전송하는 것은 피하세요. 이러한 API가 무엇을 하고 무엇을 하지 않는지에 대해 더 자세히 알고 싶다면, 오해와 사실 글에서 흔한 오해들을 다룹니다.