TR ▾
API anahtarı al

JS'de Character AI API: Node ve Web Uygulaması Kurulumu

Bir character ai api js kurulumu, resmi OpenAI npm paketine, bir base URL'e ve anahtarınızı tarayıcıdan uzak tutan bir sunucu rotasına indirgenir. Bu sayfa Node kodunu, bir akış Express uç noktasını ve buna karşılık gelen ön uç fetch'ini gösterir.

Bir sunucu küpüne, sohbet balonları taşıyan, parlayan bir boru ile bağlantılı bir tarayıcı paneli, bir JS proxy tasarımını gösteriyor

Temel noktalar

  1. openai npm paketi olduğu gibi çalışır: baseURL, apiKey ve modeli uncensored olarak değiştirin.
  2. API anahtarını tarayıcı koduna koymayın. Bunun yerine küçük bir sunucu rotasını çağırın.
  3. Akış, sunucu tarafından gönderilen olayları kullanır ve bir açık akış bir eşzamanlılık slotu kullanır.
  4. Bağımlılık istemiyorsanız saf fetch de çalışır.

Kısa özet

Uç noktaya JavaScript'ten üç yolla erişebilirsiniz: openai npm paketi, düz fetch veya zaten OpenAI sohbet formatını destekleyen herhangi bir kütüphane. Base URL https://api.characteraiapi.com/v1, model ID'si uncensored ve her istek Authorization: Bearer <key> taşır. Henüz bir anahtarınız yoksa, API anahtarı sayfası kayıt ve tek tıkla $0,50 deneme kredisi hakkında bilgi verir.

Bu bağımsız bir servistir, Character.ai ürünü değildir. Yetişkinlerin yasal kullanımı için içerik reddi olmadan yanıt verecek şekilde ayarlanmış tek bir açık ağırlıklı modeli çalıştırır ve görsel, ses veya video üretmez. Bir karakter uygulaması için bu yeterlidir: kişiliği siz yazar, konuşmayı saklarsınız ve nasıl görüneceğine siz karar verirsiniz.

openai paketi ile Node

Bir proje oluşturun, paketi yükleyin ve ES modüllerini kullanın. Örnekler Node 18 veya daha yenisi varsayar.

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"

İlk betik 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 ile çalıştırın. Usage nesnesi, çağrının kaç prompt ve completion token kullandığını gösterir; bu sayıları milyon başına $0,15 ve $0,50 ile çarparak tam fiyatı görebilirsiniz.

Anahtarı tarayıcı koduna koymayın

Anahtarı bir React bileşenine yapıştırıp sayfadan API'yi çağırmak cazip olabilir. Yapmayın. Her ziyaretçi ağ sekmesini veya paketlenmiş kaynağı açabilir ve anahtarı kopyalayabilir, ardından bakiyenizi harcayabilir. Çözüm, kontrolünüzdeki bir sunucuda ince bir vekildir. Tarayıcı, kullanıcının mesajını rotanıza gönderir; rotanız tam mesaj listesini oluşturur, anahtarı ekler ve çağrıyı iletir.

Bu aynı zamanda API'nin bilmediği şeyleri uygulamanız için bir yer de sağlar: kullanıcıların üzerine yazamayacağı bir kişilik, kullanıcı başına mesaj limiti ve uzun geçmişlerin kısaltılması. Bir tarayıcı yalnızca yeni kullanıcı metnini ve bir konuşma kimliğini göndermelidir, sistem istemini değil.

Bir akış Express uç noktası

İşte tek rotalı küçük bir sunucu. Oturumları demo için bellekte tutar; gerçek her şey için veritabanı kullanın.

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, sistem mesajını ve son 20 mesajı korur. Eski konuşmalar kaybolur, bu da maliyeti sabit tutar. Her chunk'ın düz metnini göndermek, tarayıcı tarafını basit tutar. Daha zengin olaylar istiyorsanız, bunun yerine server-sent events gönderin ve bunları istemcide ayrıştırın.

Daha zengin akış için sunucu tarafından gönderilen olaylar

Ham metin göndermek bir demo için işe yarar, ancak gerçek sohbet arayüzleri genellikle metinden fazlasını gerektirir: yanıtın tamamlandığına dair bir sinyal, bir stream sırasında bir hata mesajı veya sonundaki token kullanımı. Server-sent events size aynı HTTP bağlantısı üzerinden adlandırılmış mesajlar sağlar. Rotanız SSE formatında satırlar yazar ve tarayıcı bunları küçük bir ayrıştırıcı ile okur.

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

Her tokenı JSON olarak kodlamak klasik bir hatadan kaçınır: satır sonu içeren bir token aksi halde SSE çerçevesini bozar. İstemcide yanıt gövdesini okuyun, boş bir satıra göre bölün, data: önekini kaldırın ve JSON'u ayrıştırın. done mesajı arayüze giriş kutusunu tekrar etkinleştirmesini ve gönder butonunu yeniden etkinleştirmesini söyler.

Bağlantı kopmalarını işleyin. Kullanıcı sekmeyi kapattığında sunucudaki yanıt nesnesi bir close olayı yayar. Bunu dinleyin ve yukarı akış isteğini iptal edin, aksi takdirde sunucunuz kimse okumadığı tokenları çekmeye devam eder ve akış eşzamanlılık slotlarınızdan birini meşgul tutar. OpenAI SDK, bu amaçla istek seçeneklerinde bir AbortSignal kabul eder.

Tarayıcı tarafı

Ön uç, kendi rotanızı çağırır, API sunucusunu değil. fetch ile akışlı bir yanıt okumak birkaç satır sürer:

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

Yanıt akarken gönder butonunu devre dışı bırakın. Bu çift göndermeyi önler ve eşzamanlılık sınırına saygı duyar, çünkü akışlı bir istek sona erene kadar slotunu işgal eder.

Oturumları düzgün saklayın

Bellekteki bir harita, işlem yeniden başladığında her şeyi kaybeder ve iki sunucu örneği çalıştırdığınızda bozulur. Prototip çalışır çalışmaz oturumları bir veritabanına veya anahtar-değer deposuna taşıyın. Mesaj listesini kullanıcı ve karaktere göre anahtarlayarak bir JSON sütunu olarak saklayın. Bir istek geldiğinde listeyi yükleyin, yeni kullanıcı mesajını ekleyin, API'yi çağırın, yanıtı ekleyin ve listeyi geri yazın.

Sistem isteminin kime ait olacağına erken karar verin. Bunu kodunuzda veya yapılandırmanızda tutun, tarayıcının etkileyebileceği saklanan listede değil. Kişilik geçmişle saklanırsa, bir kullanıcı bir istek oluşturarak onu üzerine yazmaya çalışabilir. Mesaj dizisini her seferinde sunucuda yeniden oluşturun: yapılandırmadan sistem mesajı, ardından saklanan dönüşler.

Ayrıca kullanıcı başına bir limit ayarlayın. Limiti olmayan herkese açık bir sohbet widget'ı, otomatikleştirilmiş istismarı davet eder ve her token size faturalandırılır. API çağrısından önce kontrol edilen, kullanıcı başına saatlik bir sayaç başlamak için yeterlidir. Bunu, bir isteğin bir megabayt metin gönderemeyeceği şekilde bir mesaj uzunluğu üst sınırı ile birleştirin. API, 8 MB'a kadar gövde kabul eder, ancak kendi limitiniz çok daha düşük olmalıdır; örneğin kullanıcı mesajı başına 4.000 karakter.

Sade fetch, araçlar ve JSON modu

Bağımlılık istemiyorsanız, ham çağrı aynı şekilde çalışır. Bunu bir sunucudan, bir worker'dan veya bir betikten çalıştırın, halka açık sayfa kodundan değil.

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

Araç çağırma, SDK'nın gönderdiği aynı tools ve tool_choice alanlarıyla çalışır. Model tool_calls döndürdüğünde, işlevi çalıştırın ve sonucu role: "tool" ve eşleşen tool_call_id ile bir mesaj olarak gönderin. Bir oyunda bu zar atma, envanter aramaları veya karakterin oyuncu hakkında ne hatırladığının bir araması için kullanışlıdır. Akış sırasında, araç çağrıları argümanları ayrıştırmadan önce birleştirmeniz gereken kısmi parçalar olarak gelir.

Barındırma, limitler ve maliyet

Akış, saf JSON rotalarının sahip olmadığı birkaç dağıtım detayı ekler. Bazı barındırma platformları ve vekiller yanıtları arabelleğe alır veya bir isteğin ne kadar açık kalabileceğini sınırlar. Tokenlar tek tek değil, tek parça halinde sonda gelirse, sunucunuz ile tarayıcı arasında bir arabellek katmanı vardır. Bir rota için arabelleğe almayı kapatan seçeneği ve işlev yürütmeye uygulanan zaman sınırlarını öğrenmek için platformunuzun belgelerine bakın; uzun bir rol yapma yanıtı birçok saniye sürebilir.

nginx gibi bir ters vekil için yanıt arabellekleme yaygın bir nedendir ve konum başına devre dışı bırakmak için bir ayara sahiptir. Sunucusuz işlevler için platform belgelerinde akışlı yanıt moduna bakın. Barındırma sağlayıcınız akış yapamıyorsa, ucuz bir sunucudaki küçük bir her zaman açık Node işlemi güvenilir bir yedektir.

Son olarak, secret'ı ana makinenin ortam değişkeni deposuna yerleştirin ve build çıktısından uzak tutun. Ön uç build araçları genellikle public prefix taşıyan herhangi bir değişkeni tarayıcı paketine inline eder, bu nedenle bu prefix'i içermeyen bir ad kullanın ve bunu yalnızca sunucu kodunda okuyun. Hızlı bir kontrol, anahtarınızın ilk birkaç karakterini build edilmiş dosyalarınızda aramaktır.

Limitler, yeniden denemeler ve maliyet

Tam bir anahtar 8 eşzamanlı istek ve dakikada 300 izin verir. Bir deneme anahtarı 2 ve 60 izin verir. Bir limitin üzerinde API HTTP 429 ve rate_limited veya concurrency koduyla yanıt verir. Geçici bir aşırı yüklenme de bir 429'dır ve Retry-After: 5 içerir. JavaScript'te SDK status === 429 ile bir hata atar; yakalayın, bekleyin ve tekrar deneyin. SDK ayrıca varsayılan olarak birkaç kez yeniden dener, bunu istemcideki maxRetries seçeneğiyle ayarlayabilirsiniz.

Dönüş başına maliyet kolayca tahmin edilebilir. 2.000 girdi tokeni ve 250 çıktı tokeni olan bir sohbet, girdi için 2.000 x $0,15 / 1.000.000 = $0,0003 ve çıktı için 250 x $0,50 / 1.000.000 = $0,000125 maliyetinde olur, yani $0,000425. Bin dönüş $0,425 eder. Başarısız veya reddedilen istekler ücretlendirilmez. $20 ile $500 arasında bakiye yüklemeler ve bonus katmanları için fiyatlandırma sayfasına ve tam parametre listesi için belgelere bakın.

Sorular ve cevaplar

API'yi doğrudan bir React veya Vue uygulamasından çağırabilir miyim?

Teknik olarak evet, ancak anahtar her ziyaretçi için görünür olur. Anahtarı ekleyen ve isteği ileten küçük bir sunucu rotası kullanın.

Hangi npm paketini kullanmalıyım?

Resmi openai paketi çalışır. baseURL'i uç noktaya ayarlayın, anahtarınızı apiKey olarak kullanın ve modeli uncensored olarak seçin. Sade fetch de uygundur.

Deno, Bun veya Cloudflare Workers üzerinde çalışıyor mu?

Bearer başlığı ile HTTPS isteği yapabilen her çalışma zamanı bunu çağırabilir. openai paketi çeşitli çalışma zamanlarını destekler, bu yüzden kendi çalışma zamanınız için belgelerini kontrol edin.

Tokenları sayfaya nasıl akıtabilirim?

Sunucuda stream: true ayarını yapın, her parçayı tarayıcıya iletin ve bir fetch okuyucu ile okuyun. Her açık akış, bir eşzamanlı istek slotu tutar.

Bu, Character.ai'nin resmi API'si mi?

Hayır. Kendi API anahtarına ve tek bir modele sahip, kendi karakter uygulamalarınız için bir arka uç olarak sunulan bağımsız bir OpenAI uyumlu servistir.

Anahtarınız tek bir formun uzağında

Bir hesap oluşturun, anahtarı kopyalayın ve base URL'yi değiştirin. Kurulum bu kadar basit.

API anahtarı al