KO ▾
API 키 받기

JS용 Character AI API: Node 및 웹 앱 설정

Character AI API JS 설정은 공식 openai npm 패키지, 기본 URL 및 키를 브라우저에서 숨기는 서버 라우트로 구성됩니다. 이 페이지에는 Node 코드, 스트리밍 Express 엔드포인트 및 관련 프런트엔드 fetch가 표시됩니다.

빛나는 파이프를 통해 서버 큐브에 연결된 브라우저 패널, 채팅 말풍선을 표시하며 JS 프록시 디자인을 보여줍니다

주요 포인트

  1. openai npm 패키지는 그대로 작동합니다: baseURL, apiKey 및 모델을 uncensored로 변경하세요.
  2. 브라우저 코드에 키를 포함하지 마세요. 대신 작은 서버 라우트를 호출하세요.
  3. 스트리밍은 서버 전송 이벤트를 사용하며, 하나의 열린 스트림은 하나의 동시성 슬롯을 사용합니다.
  4. 의존성을 원치 않으면 일반 fetch도 작동합니다.

간단 요약

자바스크립트에서 엔드포인트에 접근하는 세 가지 방법이 있습니다: openai npm 패키지, 일반 fetch, 또는 OpenAI 채팅 형식을 지원하는 라이브러리입니다. 베이스 URL은 https://api.characteraiapi.com/v1, 모델 ID는 uncensored이며 모든 요청에는 Authorization: Bearer <key>이 포함됩니다. 키가 없다면 API 키 페이지에서 가입과 $0.50 무료 체험을 확인하세요.

이것은 독립적인 서비스이며 Character.ai 제품이 아닙니다. 합법적인 성인 사용자를 위해 콘텐츠 거부 없이 답변하도록 조정된 하나의 오픈 웨이트 모델을 실행하며, 이미지, 오디오 또는 비디오를 생성하지 않습니다. 캐릭터 앱에는 충분합니다: 페르소나를 작성하고 대화를 저장하며 외관을 결정합니다.

openai 패키지로 Node 사용

프로젝트를 생성하고 패키지를 설치한 후 ES 모듈을 사용하세요. 예제는 Node 18 이상을 가정합니다.

mkdir persona-chat && cd persona-chat
npm init -y
npm pkg set type=module
npm install openai express
export API_KEY="paste-your-key-here"

chat.js의 첫 번째 스크립트:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.characteraiapi.com/v1",
  apiKey: process.env.API_KEY,
});

const completion = await client.chat.completions.create({
  model: "uncensored",
  messages: [
    { role: "system", content: "You are Juno, a sarcastic lighthouse keeper. Stay in character." },
    { role: "user", content: "A boat is signalling in the fog. Thoughts?" },
  ],
  temperature: 0.9,
});

console.log(completion.choices[0].message.content);
console.log(completion.usage);

node chat.js로 실행하세요. usage 객체는 호출에 사용된 프롬프트 및 완료 토큰 수를 알려주며, 이를 백만 토큰당 $0.15 및 $0.50에 곱하여 정확한 가격을 확인할 수 있습니다.

키를 브라우저 코드에 넣지 마세요

React 컴포넌트에 키를 붙여넣고 페이지에서 API를 호출하고 싶을 수 있습니다. 하지 마세요. 모든 방문자가 네트워크 탭이나 번들된 소스를 열어 복사할 수 있으며, 그러면 잔액을 사용할 수 있습니다. 해결책은 귀하가 제어하는 서버의 얇은 프록시입니다. 브라우저는 사용자의 메시지를 귀하의 라우트로 보내고, 귀하의 라우트는 전체 메시지 목록을 작성하고 키를 추가한 후 호출을 전달합니다.

이는 API가 알 수 없는 사항을 강제할 수 있는 위치도 제공합니다: 사용자가 덮어쓸 수 없는 페르소나, 사용자별 메시지 제한 및 긴 기록의 트리밍. 브라우저는 시스템 프롬프트가 아닌 새 사용자 텍스트와 대화 ID만 보내야 합니다.

스트리밍 Express 엔드포인트

라우트 하나가 있는 작은 서버입니다. 데모를 위해 세션을 메모리에 유지합니다. 실제 사용에는 데이터베이스를 사용하세요.

import express from "express";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.characteraiapi.com/v1",
  apiKey: process.env.API_KEY,
});

const PERSONA = "You are Juno, a sarcastic lighthouse keeper. Stay in character, two to four sentences.";
const sessions = new Map();

const app = express();
app.use(express.json({ limit: "100kb" }));
app.use(express.static("public"));

app.post("/api/chat", async (req, res) => {
  const { id, text } = req.body;
  if (!id || !text) return res.status(400).json({ error: "id and text required" });

  const history = sessions.get(id) ?? [{ role: "system", content: PERSONA }];
  history.push({ role: "user", content: text });

  res.setHeader("Content-Type", "text/plain; charset=utf-8");

  try {
    const stream = await client.chat.completions.create({
      model: "uncensored",
      messages: [history[0], ...history.slice(-20)],
      stream: true,
    });
    let reply = "";
    for await (const chunk of stream) {
      const piece = chunk.choices[0]?.delta?.content ?? "";
      if (piece) {
        reply += piece;
        res.write(piece);
      }
    }
    history.push({ role: "assistant", content: reply });
    sessions.set(id, history);
    res.end();
  } catch (err) {
    res.status(err.status === 429 ? 429 : 500).end("error");
  }
});

app.listen(3000);

슬라이스는 시스템 메시지 및 마지막 20개 메시지를 유지합니다. 오래된 턴은 사라져 비용이 일정하게 유지됩니다. 각 청크의 일반 텍스트만 보내면 브라우저 측이 단순해집니다. 더 풍부한 이벤트를 원한다면 서버 전송 이벤트를 보내고 클라이언트에서 구문 분석하세요.

더 풍부한 스트리밍을 위한 서버 전송 이벤트

원시 텍스트 전송은 데모에는 작동하지만 실제 채팅 인터페이스는 텍스트보다 더 많은 것을 필요로 합니다: 응답이 완료되었음을 알리는 신호, 스트리밍 중간에 오류 메시지 또는 끝에 토큰 사용량. 서버 전송 이벤트는 동일한 HTTP 연결을 통해 이름이 지정된 메시지를 제공합니다. 귀하의 라우트는 SSE 형식의 줄을 작성하고 브라우저는 작은 구문 분석기로 읽습니다.

// server: inside the route, after setting headers
res.setHeader("Content-Type", "text/event-stream");
res.setHeader("Cache-Control", "no-cache");

for await (const chunk of stream) {
  const piece = chunk.choices[0]?.delta?.content ?? "";
  if (piece) res.write(`data: ${JSON.stringify({ token: piece })}\n\n`);
}
res.write(`data: ${JSON.stringify({ done: true })}\n\n`);
res.end();

각 토큰을 JSON으로 인코딩하면 고전적인 버그를 피할 수 있습니다: 줄 바꿈을 포함하는 토큰은 그렇지 않으면 SSE 프레임을 깨뜨립니다. 클라이언트에서 응답 본문을 읽고, 빈 줄에서 나누고, data: 접두사를 제거한 후 JSON을 구문 분석합니다. done 메시지는 인터페이스에 입력 상자를 다시 활성화하고 보내기 버튼을 다시 활성화하도록 알립니다.

연결 끊김을 처리하세요. 사용자가 탭을 닫으면 서버의 응답 객체에 close 이벤트가 발생합니다. 이를 수신하고 업스트림 요청을 중단하세요. 그렇지 않으면 서버가 아무도 읽지 않는 토큰을 계속 가져오고 스트림이 동시성 슬롯 중 하나를 차지한 상태로 유지됩니다. OpenAI SDK는 이를 위해 요청 옵션에 AbortSignal을 허용합니다.

브라우저 측면

프론트엔드는 API 호스트가 아닌 자체 라우트를 호출합니다. fetch로 스트리밍 응답을 읽는 방법은 다음과 같습니다:

const id = crypto.randomUUID();

async function send(text, onToken) {
  const res = await fetch("/api/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id, text }),
  });
  if (!res.ok) throw new Error("request failed: " + res.status);

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    onToken(decoder.decode(value, { stream: true }));
  }
}

send("Is the lamp lit?", (t) => { document.querySelector("#out").textContent += t; });

응답이 스트리밍되는 동안 보내기 버튼을 비활성화하세요. 이는 중복 제출을 방지하고 스트리밍된 요청이 종료될 때까지 슬롯을 차지하므로 동시성 제한을 준수합니다.

세션을 적절히 저장하세요

메모리 맵은 프로세스가 다시 시작할 때 모든 것을 잃고 두 개의 서버 인스턴스를 실행하자마자 중단됩니다. 프로토타입이 작동하면 세션을 데이터베이스 또는 키-값 저장소로 이동하세요. 메시지 목록을 JSON 열로 저장하고 사용자 및 캐릭터별로 키를 지정하세요. 요청이 도착하면 목록을 로드하고 새 사용자 메시지를 추가하고 API를 호출하고 응답을 추가한 후 목록을 다시 작성합니다.

시스템 프롬프트의 소유자를 조기에 결정하세요. 브라우저가 영향을 줄 수 있는 저장된 목록이 아닌 코드나 구성에 유지하세요. 페르소나가 대화 기록과 함께 저장되면 사용자가 요청을 작성하여 이를 덮어쓰려고 시도할 수 있습니다. 서버에서 매번 메시지 배열을 다시 빌드하세요: 구성에서 가져온 시스템 메시지 다음에 저장된 턴을 붙입니다.

또한 사용자별 제한을 설정하세요. 제한이 없는 공개 채팅 위젯은 스크립트 남용을 유도하며 모든 토큰은 귀하에게 청구됩니다. API 호출 전에 확인되는 시간당 사용자당 카운터로 시작하기에 충분합니다. 메시지 길이에 대한 상한과 결합하여 하나의 요청이 메가바이트의 텍스트를 보낼 수 없도록 하세요. API는 최대 8 MB의 본문을 허용하지만 자체 제한은 사용자 메시지당 4,000자처럼 훨씬 낮아야 합니다.

일반 fetch, 도구 및 JSON 모드

의존성을 원치 않으면 원시 호출도 동일한 방식으로 작동합니다. 이것을 서버, 워커 또는 스크립트에서 실행하고 공개 페이지 코드에서는 실행하지 마세요.

const r = await fetch("https://api.characteraiapi.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "uncensored",
    response_format: { type: "json_object" },
    messages: [
      { role: "system", content: "Reply with JSON only: {\"mood\": string, \"line\": string}" },
      { role: "user", content: "Juno sees a light on the water." },
    ],
  }),
});
const data = await r.json();
console.log(JSON.parse(data.choices[0].message.content));

함수 호출은 SDK가 보내는 동일한 tools 및 tool_choice 필드로 작동합니다. 모델이 tool_calls을 반환하면 함수를 실행하고 role: "tool" 및 일치하는 tool_call_id과 함께 메시지를 보내 결과를 전달합니다. 게임에서는 주사위 굴리기, 인벤토리 조회 또는 캐릭터의 플레이어 기억 조회에 유용합니다. 스트리밍 중 함수 호출은 인수를 파싱하기 전에 결합해야 하는 부분 단위로 전달됩니다.

호스팅, 제한 사항 및 비용

스트리밍은 일반 JSON 라우트에는 없는 몇 가지 배포 세부 사항을 추가합니다. 일부 호스팅 플랫폼과 프록시는 응답을 버퍼링하거나 요청이 열려 있을 수 있는 시간을 제한합니다. 토큰이 하나씩이 아닌 한 번에 도착하면 버퍼링 레이어가 서버와 브라우저 사이에 있습니다. 플랫폼 문서에서 라우트의 버퍼링을 끄는 옵션과 함수 실행 시간 제한을 확인하세요. 긴 역할극 응답은 몇 초 이상 걸릴 수 있습니다.

nginx와 같은 리버스 프록시의 경우 응답 버퍼링이 일반적인 원인이며 위치별로 끄는 설정이 있습니다. 서버리스 함수의 경우 플랫폼 문서에서 스트리밍 응답 모드를 찾으세요. 호스트가 스트리밍할 수 없다면 저렴한 서버의 작은 상시 실행 Node 프로세스가 신뢰할 수 있는 대체 수단입니다.

마지막으로 비밀을 호스트의 환경 변수 저장소에 넣고 빌드 출력에서 제외하세요. 프런트엔드 빌드 도구는 일반적으로 공개 접두어가 있는 모든 변수를 브라우저 번들에 인라인으로 포함하므로 해당 접두어가 없는 이름을 사용하고 서버 코드에서만 읽으세요. 빠른 확인 방법은 빌드된 파일에서 키의 첫 몇 문자를 검색하는 것입니다.

제한, 재시도 및 비용

전체 키는 동시 요청 8개와 분당 300개의 요청을 허용합니다. 체험 키는 각각 2개와 60개를 허용합니다. 제한을 초과하면 API는 HTTP 429와 코드 rate_limited 또는 concurrency로 응답합니다. 일시적인 과부하 역시 429이며 Retry-After: 5를 포함합니다. JavaScript에서 SDK는 status === 429 오류를 발생시키므로 이를 catch하고 대기 후 재시도하세요. SDK는 기본적으로 몇 번 자동으로 재시도하며, 이는 클라이언트의 maxRetries 옵션으로 조정할 수 있습니다.

턴당 비용은 쉽게 추정할 수 있습니다. 입력 토큰 2,000개와 출력 토큰 250개의 채팅은 입력에 2,000 x $0.15 / 1,000,000 = $0.0003, 출력에 250 x $0.50 / 1,000,000 = $0.000125가 들어 총 $0.000425가 듭니다. 천 번의 턴은 $0.425입니다. 실패하거나 거부된 요청은 요금이 부과되지 않습니다. 가격 책정 페이지에서 $20부터 $500까지의 충전과 보너스 등급을 확인하고, 문서에서 전체 매개변수 목록을 확인하세요.

질문과 답변

React 또는 Vue 앱에서 API를 직접 호출할 수 있나요?

기술적으로는 가능하지만 키가 모든 방문자에게 노출됩니다. 키를 추가하고 요청을 전달하는 작은 서버 라우트를 사용하세요.

어떤 npm 패키지를 사용해야 하나요?

공식 openai 패키지를 사용할 수 있습니다. baseURL을 엔드포인트에 설정하고, apiKey에 키를, 모델에 uncensored을 사용하세요. 일반 fetch도 가능합니다.

Deno, Bun 또는 Cloudflare Workers에서 실행되나요?

Bearer 헤더와 함께 HTTPS 요청을 생성할 수 있는 모든 런타임에서 호출할 수 있습니다. openai 패키지는 여러 런타임을 지원하므로 해당 런타임의 문서를 확인하세요.

토큰을 페이지에 스트리밍하려면 어떻게 하나요?

서버에서 stream: true를 설정하고 각 청크를 브라우저로 전달한 후 fetch reader로 읽으세요. 각 열린 스트림은 하나의 동시 요청 슬롯을 차지합니다.

이것은 Character.ai의 공식 API인가요?

아닙니다. 독립적인 OpenAI 호환 서비스로, 자체 API 키와 하나의 모델을 갖추고 있으며 사용자만의 캐릭터 앱용 백엔드로 제공됩니다.

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

계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.

API 키 받기