ID ▾
Dapatkan kunci API

API Character AI dalam JS: Penyiapan Node dan Aplikasi Web

Penyiapan api character ai js bergantung pada paket npm openai resmi, URL dasar, dan rute server yang menjaga kunci Anda tetap aman dari browser. Halaman ini menunjukkan kode Node, endpoint Express streaming, dan fetch sisi depan yang menyertainya.

Panel browser terhubung dengan pipa bercahaya ke kubus server yang membawa gelembung obrolan, menampilkan desain proxy JS

Poin utama

  1. Paket npm openai bekerja apa adanya: ubah baseURL, apiKey, dan model menjadi uncensored.
  2. Jangan kirimkan kunci dalam kode browser. Panggil rute server kecil sebagai gantinya.
  3. Streaming menggunakan peristiwa yang dikirim server, dan satu stream terbuka menggunakan satu slot konkurensi.
  4. Fetch biasa juga berfungsi jika Anda lebih suka tanpa dependensi.

Versi singkatnya

Anda dapat mengakses endpoint dari JavaScript dengan tiga cara: paket npm openai, fetch biasa, atau pustaka apa pun yang sudah mendukung format chat OpenAI. Base URL-nya adalah https://api.characteraiapi.com/v1, ID modelnya adalah uncensored, dan setiap permintaan menyertakan Authorization: Bearer <key>. Jika Anda belum memiliki kunci, halaman kunci API menjelaskan cara mendaftar dan uji coba seharga $0,50 dalam satu klik.

Ini adalah layanan independen, bukan produk Character.ai. Layanan ini menjalankan satu model bobot terbuka yang disesuaikan untuk menjawab tanpa penolakan konten untuk penggunaan dewasa yang sah, dan tidak menghasilkan gambar, audio, atau video. Untuk aplikasi karakter, ini sudah cukup: Anda menulis persona, menyimpan percakapan, dan memutuskan tampilannya.

Node dengan paket openai

Buat proyek, instal paket, dan gunakan modul ES. Contoh mengasumsikan Node 18 atau yang lebih baru.

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"

Skrip pertama di 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);

Jalankan dengan node chat.js. Objek penggunaan memberi tahu Anda berapa banyak token prompt dan completion yang digunakan panggilan, yang dapat Anda kalikan dengan $0,15 dan $0,50 per juta untuk melihat harga pastinya.

Jangan letakkan kunci dalam kode browser

Sangat menggoda untuk menempelkan kunci ke komponen React dan memanggil API dari halaman. Jangan lakukan itu. Setiap pengunjung dapat membuka tab jaringan atau sumber yang dibundel dan menyalinnya, lalu menghabiskan saldo Anda. Solusinya adalah proxy tipis di server yang Anda kendalikan. Browser mengirim pesan pengguna ke rute Anda; rute Anda membangun daftar pesan lengkap, menambahkan kunci, dan meneruskan panggilan.

Ini juga memberi Anda tempat untuk menerapkan hal-hal yang tidak diketahui API: persona yang tidak dapat ditimpa pengguna, batas pesan per pengguna, dan pemangkasan riwayat panjang. Browser seharusnya hanya mengirim teks pengguna baru dan ID percakapan, bukan prompt sistem.

Endpoint Express streaming

Berikut adalah server kecil dengan satu rute. Ini menyimpan sesi dalam memori untuk demo; gunakan database untuk apa pun yang sebenarnya.

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);

Slice menjaga pesan sistem ditambah 20 pesan terakhir. Giliran lama dibuang, yang menjaga biaya tetap stabil. Mengirim hanya teks polos dari setiap bagian menjaga sisi browser tetap sederhana. Jika Anda menginginkan event yang lebih kaya, kirimkan server-sent events dan uraikan di sisi klien.

Peristiwa yang dikirim server untuk streaming yang lebih kaya

Mengirim teks mentah berfungsi untuk demo, tetapi antarmuka obrolan nyata biasanya membutuhkan lebih dari teks: sinyal ketika balasan selesai, pesan kesalahan di tengah stream, atau penggunaan token di akhir. Peristiwa yang dikirim server memberi Anda pesan bernama di atas koneksi HTTP yang sama. Rute Anda menulis baris dalam format SSE, dan browser membacanya dengan parser kecil.

// 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();

Mengodekan setiap token sebagai JSON menghindari bug klasik: token yang mengandung baris baru akan merusak pembingkaian SSE. Di sisi klien, baca body respons, pisahkan pada baris kosong, hapus awalan data: , dan uraikan JSON. Pesan selesai memberi tahu antarmuka untuk mengaktifkan kotak input lagi dan mengaktifkan kembali tombol kirim.

Tangani koneksi terputus. Saat pengguna menutup tab, objek respons di server memancarkan event close. Dengarkan event itu dan batalkan permintaan upstream, jika tidak server Anda terus menarik token yang tidak dibaca siapa pun, dan stream terus menempati salah satu slot konkurensi Anda. SDK OpenAI menerima AbortSignal dalam opsi permintaan untuk tujuan ini.

Sisi browser

Front end memanggil rute Anda sendiri, bukan host API. Membaca respons streaming dengan fetch membutuhkan beberapa baris:

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; });

Nonaktifkan tombol kirim saat balasan sedang di-stream. Ini mencegah pengiriman ganda dan menghormati batas konkurensi, karena permintaan yang di-stream menempati slotnya hingga berakhir.

Simpan sesi dengan benar

Map di memori kehilangan semua data saat proses dimulai ulang dan rusak segera setelah Anda menjalankan dua instance server. Pindahkan sesi ke basis data atau penyimpanan key-value segera setelah prototipe berfungsi. Simpan daftar pesan sebagai kolom JSON, dikunci berdasarkan pengguna dan karakter. Saat permintaan tiba, muat daftar, tambahkan pesan pengguna baru, panggil API, tambahkan balasan, dan tulis daftar kembali.

Putuskan sejak awal siapa yang memiliki prompt sistem. Simpan di kode atau konfigurasi Anda, bukan di daftar yang disimpan yang dapat dipengaruhi browser. Jika persona disimpan dengan riwayat, pengguna dapat mencoba menimpanya dengan membuat permintaan. Bangun kembali array pesan di server setiap kali: pesan sistem dari konfigurasi, diikuti oleh giliran yang disimpan.

Atur juga batas per pengguna. Widget obrolan publik tanpa batas mengundang penyalahgunaan skrip, dan setiap token ditagih kepada Anda. Penghitung per pengguna per jam, diperiksa sebelum panggilan API, sudah cukup untuk memulai. Gabungkan dengan batas atas panjang pesan sehingga satu permintaan tidak dapat mengirim satu megabyte teks. API menerima body hingga 8 MB, tetapi batas Anda sendiri harus jauh lebih rendah, seperti 4.000 karakter per pesan pengguna.

Fetch biasa, alat, dan mode JSON

Jika Anda tidak ingin menggunakan dependensi, panggilan mentah berfungsi dengan cara yang sama. Jalankan ini dari server, pekerja, atau skrip, bukan dari kode halaman publik.

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));

Pemanggilan fungsi bekerja dengan bidang tools dan tool_choice yang sama yang dikirim SDK. Saat model mengembalikan tool_calls, jalankan fungsi dan kirimkan output kembali sebagai pesan dengan role: "tool" dan tool_call_id yang sesuai. Dalam game ini berguna untuk lemparan dadu, pencarian inventaris, atau pencarian apa yang diingat karakter tentang pemain. Saat streaming, panggilan alat tiba sebagai fragmen parsial yang harus Anda gabungkan sebelum menguraikan argumennya.

Hosting, batas, dan biaya

Streaming menambahkan beberapa detail penyiapan yang tidak dimiliki rute JSON biasa. Beberapa platform hosting dan proxy melakukan buffer respons atau membatasi berapa lama permintaan dapat tetap terbuka. Jika token tiba dalam satu gumpalan di akhir bukan satu per satu, lapisan buffering berada di antara server Anda dan browser. Periksa dokumentasi platform Anda untuk opsi yang menonaktifkan buffering untuk rute, dan untuk batas waktu apa pun pada eksekusi fungsi, karena balasan roleplay panjang dapat berjalan selama beberapa detik.

Untuk proxy terbalik seperti nginx, buffering respons adalah penyebab umum dan memiliki pengaturan untuk mematikannya per lokasi. Untuk fungsi serverless, cari mode respons streaming dalam dokumentasi platform. Jika host Anda tidak dapat streaming, proses Node kecil yang selalu aktif di server murah adalah cadangan yang andal.

Akhirnya, masukkan rahasia ke penyimpanan variabel lingkungan host dan jauhkan dari output build. Alat build front-end sering menyematkan variabel apa pun yang membawa awalan publik ke bundel browser, jadi gunakan nama tanpa awalan itu, dan baca hanya dalam kode server. Pemeriksaan cepat adalah mencari file yang telah dibangun untuk beberapa karakter pertama kunci.

Batas, percobaan ulang, dan biaya

Kunci penuh mengizinkan 8 permintaan konkuren dan 300 per menit. Kunci uji coba mengizinkan 2 dan 60. Melebihi batas, API menjawab dengan HTTP 429 dan kode rate_limited atau concurrency. Beban berlebih sementara juga merupakan 429 dan mencakup Retry-After: 5. Dalam JavaScript, SDK melempar kesalahan dengan status === 429; tangkap, tunggu, dan coba lagi. SDK juga mencoba lagi beberapa kali secara default, yang dapat Anda atur dengan opsi maxRetries di sisi klien.

Biaya per giliran mudah diperkirakan. Obrolan dengan 2.000 token input dan 250 token output berbiaya 2.000 x $0,15 / 1.000.000 = $0,0003 untuk input dan 250 x $0,50 / 1.000.000 = $0,000125 untuk output, sehingga $0,000425. Seribu giliran adalah $0,425. Permintaan yang gagal atau ditolak tidak dikenakan biaya. Lihat halaman harga untuk isi saldo dari $20 hingga $500 dan tingkat bonus, dan dokumentasi untuk daftar parameter lengkap.

Tanya jawab

Bisakah saya memanggil API langsung dari aplikasi React atau Vue?

Secara teknis bisa, tetapi kunci akan terlihat oleh setiap pengunjung. Gunakan rute server kecil yang menambahkan kunci dan meneruskan permintaan.

Paket npm mana yang harus saya gunakan?

Paket openai resmi bekerja. Atur baseURL ke endpoint, gunakan kunci Anda sebagai apiKey dan model uncensored. Fetch biasa juga baik-baik saja.

Apakah ini berjalan di Deno, Bun, atau Cloudflare Workers?

Runtime apa pun yang dapat membuat permintaan HTTPS dengan header Bearer dapat memanggilnya. Paket openai mendukung beberapa runtime, jadi periksa dokumentasinya untuk runtime Anda.

Bagaimana saya melakukan streaming token ke halaman?

Setel stream: true di server, teruskan setiap chunk ke browser dan baca dengan pembaca fetch. Setiap stream terbuka menyita satu slot konkurensi.

Apakah ini API resmi Character.ai?

Tidak. Ini adalah layanan independen yang kompatibel dengan OpenAI, dengan kunci API sendiri dan satu model, yang ditawarkan sebagai backend untuk aplikasi karakter Anda sendiri.

Kunci Anda hanya selangkah lagi dari satu formulir

Buat akun, salin kunci, ubah URL dasar. Itu saja seluruh proses pengaturannya.

Dapatkan kunci API