JA ▾
API キーを取得

JSでのCharacter AI API:NodeとWebアプリのセットアップ

Character AI API JSのセットアップは、公式のopenai npmパッケージ、ベースURL、キーをブラウザから隠すサーバールートで構成されます。このページではNodeコード、ストリーミングExpressエンドポイント、対応するフロントエンドfetchを示します。

チャットバブルを運ぶサーバーキューブに光るパイプでリンクされたブラウザパネル、JSプロキシデザインを示す

主要ポイント

  1. openai npmパッケージはそのまま動作します:baseURL、apiKey、モデルをuncensoredに変更します。
  2. キーをブラウザコードに配置しないでください。代わりに小さなサーバールートを呼び出してください。
  3. ストリーミングはサーバー送信イベントを使用し、1つのオープンストリームは1つの同時実行スロットを使用します。
  4. 依存関係なしを好む場合は、プレーンなfetchも機能します。

簡易版

JavaScriptからは3つの方法でエンドポイントにアクセスできます:openai npmパッケージ、プレーンなfetch、またはOpenAIチャット形式に対応したライブラリです。ベースURLはhttps://api.characteraiapi.com/v1、モデルIDはuncensored、すべてのリクエストにはAuthorization: Bearer <key>が付きます。キーをお持ちでない場合は、APIキーページでサインアップと1クリックの$0.50トライアルについて説明しています。

これは独立したサービスであり、Character.ai製品ではありません。成人による合法的な利用向けに、コンテンツ拒否なしで回答するように調整されたオープンウェイトモデルを1つ実行し、画像、音声、動画は生成しません。キャラクターアプリには十分です:ペルソナを記述し、会話を保存し、外観を決定します。

openaiパッケージを使用したNode.js

プロジェクトを作成し、パッケージをインストールして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オブジェクトは、呼び出しで使用されたプロンプトトークンとcompletionトークンの数を示しており、これを100万トークンあたり$0.15と$0.50で掛け算することで正確な価格を確認できます。

キーをブラウザコードに配置しない

キーをReactコンポーネントに貼り付け、ページからAPIを呼び出したくなりますが、そうしないでください。すべての訪問者がネットワークタブまたはバンドルされたソースを開いてコピーでき、残高を消費する可能性があります。解決策は、あなたが管理するサーバー上の薄いプロキシです。ブラウザはユーザーのメッセージをあなたのルートに送信し、あなたのルートは完全なメッセージリストを構築し、キーを追加して呼び出しを転送します。

これにより、APIが知らない事項を強制できる場所も得られます:ユーザーが上書きできないペルソナ、ユーザーごとのメッセージ制限、長い履歴のトリミングです。ブラウザは新しいユーザーテキストと会話IDのみを送信し、システムプロンプトは送信すべきではありません。

ストリーミングExpressエンドポイント

ここにルートが1つある小さなサーバーを示します。デモ用にセッションをメモリに保持しますが、実際の用途ではデータベースを使用してください。

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イベントを発行します。それをリッスンしてアップストリームリクエストを中止してください。そうしないと、サーバーは誰も読まないトークンを取得し続け、ストリームは同時実行スロットの1つを占有したままになります。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; });

応答がストリーミング中は送信ボタンを無効にします。これは二重送信を防ぎ、同時実行制限を尊重します。ストリーミングリクエストは、終了するまでスロットを占有するためです。

セッションを適切に保存する

メモリ内のマップはプロセス再起動時にすべてのデータを失い、2つのサーバーインスタンスを実行するとすぐに破綻します。プロトタイプが動作したら、すぐにセッションをデータベースまたはキーバリューストアに移動してください。メッセージリストをJSONカラムとして、ユーザーとキャラクターをキーとして保存します。リクエストが届いたら、リストを読み込み、新しいユーザーメッセージを追加し、APIを呼び出し、応答を追加してリストを書き戻します。

システムプロンプトの所有者を早期に決定します。ブラウザが影響を与えることができる保存リストではなく、コードまたは設定に保持してください。ペルソナが履歴とともに保存されている場合、ユーザーはリクエストを構成することでそれを上書きしようとする可能性があります。サーバー上で毎回メッセージ配列を再構築します:設定からのシステムメッセージに続き、保存されたターンが続きます。

また、ユーザーごとの制限も設定してください。制限のない公開チャットウィジェットはスクリプトによる悪用を招き、すべてのトークンがあなたに請求されます。API呼び出しの前にチェックされるユーザーごとの時間あたりのカウンターで十分です。メッセージ長の上限と組み合わせ、1つのリクエストで1メガバイトのテキストを送信できないようにします。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ルートにはないいくつかのデプロイの詳細を追加します。一部のホスティングプラットフォームやプロキシはレスポンスをバッファリングしたり、リクエストがオープン状態になる時間を制限したりします。トークンが1つずつではなく、最後に一括して到着する場合、バッファリングレイヤーがサーバーとブラウザの間にあります。ルートのバッファリングを無効にするオプションと、関数実行の時間制限について、プラットフォームのドキュメントを確認してください。長いロールプレイ応答は数秒かかることがあるためです。

nginxなどのリバースプロキシの場合、レスポンスバッファリングは一般的な原因であり、場所ごとにオフにする設定があります。サーバーレス関数の場合、プラットフォームドキュメントでストリーミングレスポンスモードを探してください。ホストがストリーミングできない場合、安価なサーバー上の小さな常時稼働Nodeプロセスは信頼性の高いフォールバックです。

最後に、シークレットをホストの環境変数ストアに配置し、ビルド出力から除外してください。フロントエンドのビルドツールは、公開プレフィックスを持つ変数をブラウザバンドルにインライン化することが多いため、そのプレフィックスを持たない名前を使用し、サーバーコードでのみ読み取ってください。キーの最初の数文字をビルドファイル内で検索することで、簡単なチェックができます。

制限、リトライ、コスト

フルキーは8つの同時リクエストと1分あたり300を許可します。トライアルキーは2と60を許可します。制限を超えると、APIはHTTP 429とコードrate_limitedまたはconcurrencyで応答します。一時的な過負荷も429であり、Retry-After: 5を含みます。JavaScriptでは、SDKはstatus === 429を持つエラーをスローします。これをキャッチし、待機して再試行します。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かかります。1,000ターンは$0.425です。失敗または拒否されたリクエストは請求されません。$20から$500までのチャージとボーナスティアについては料金ページを、完全なパラメータリストについてはドキュメントを参照してください。

質問と回答

ReactやVueアプリからAPIを直接呼び出せますか?

技術的には可能ですが、キーはすべての訪問者に表示されます。キーを追加してリクエストを転送する小さなサーバールートを使用してください。

どのnpmパッケージを使用すべきですか?

公式のopenaiパッケージが動作します。baseURLをエンドポイントに設定し、apiKeyにキー、モデルにuncensoredを指定します。プレーンなfetchでも問題ありません。

Deno、Bun、Cloudflare Workersで動作しますか?

Bearer ヘッダー付きで HTTPS リクエストを実行できるランタイムであれば、すべて呼び出し可能です。openai パッケージは複数のランタイムをサポートしているため、ご自身の環境に合ったドキュメントをご確認ください。

トークンをページにストリーミングするにはどうすればよいですか?

サーバー側で stream: true を設定し、各チャンクをブラウザに転送して、fetch reader で読み取ります。各オープンストリームは 1 つの同時実行スロットを占有します。

これは Character.ai の公式 API ですか?

いいえ。これは独自の API キーと単一のモデルを備えた独立した OpenAI 互換サービスであり、ユーザー独自のキャラクターアプリ用のバックエンドとして提供されています。

キーはフォーム 1 つで手に入ります

アカウントを作成し、キーをコピーし、ベースURLを変更します。これでセットアップは完了です。

API キーを取得