TR ▾
API anahtarı al

Python ile Character AI API'si: OpenAI SDK Kurulumu

Bir Character AI API Python iş akışı kullanmak için resmi openai paketini yükleyin, base URL'sini OpenAI-uyumlu bir uç noktaya işaret edin ve modeli uncensored olarak ayarlayın. Bu sayfanın geri kalanı, geçmiş, akış, yeniden denemeler ve maliyet izleme ile bunun üzerine küçük bir kişilik sohbeti oluşturur.

Platformda terminal, bağlantılı küplere akış yapan sohbet balonlarını temsil eden bir Python sohbet istemcisi

Temel noktalar

  1. Standart SDK'de iki değer değişir: base_url ve api_key.
  2. Karakter davranışı, sistem mesajı ve her dönüşte yeniden gönderdiğiniz geçmişten gelir.
  3. Akış, fonksiyon çağırma ve JSON modu aynı istemci üzerinden çalışır.
  4. HTTP 429 hatalarını kısa bir bekleme süresiyle yönetin ve tam anahtarda eşzamanlı çağrıları 8 ile sınırlayın.

Kurulum ve bağlantı

Özel bir istemci kütüphanesi yoktur. Python'daki karakter uygulamaları, diğer her şey için kullanılan aynı openai paketini kullanır. Kurun ve anahtarınızı bir ortam değişkeninde tutun.

pip install openai
export API_KEY="paste-your-key-here"

Önce API anahtarı sayfasından bir anahtar alın. Yeni hesaplar tek tıkla, kart gerekmeden orada $0,50 deneme kredisi talep edebilir. Ardından istemciyi oluşturun:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.characteraiapi.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

Bu bir selamlama ve kullanım nesnesi yazdırıyorsa bağlantı iyidir. Hizmet POST /v1/chat/completions ve GET /v1/models uç noktalarını sunar. Görüntüler, gömme vektörler veya ince ayar gibi metin sohbeti dışındaki her şey mevcut değildir.

Belleği olan bir karakter sohbet döngüsü

API durum bilgisi tutmaz (stateless). Son dönüşü hatırlamaz, bu nedenle programınız her seferinde tüm konuşmayı göndermelidir. Bir kişilik için bu, bir sistem mesajı ve ardından art arda gelen kullanıcı ve asistan mesajları anlamına gelir. Bu döngü bunları bir listede tutar.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.characteraiapi.com/v1", api_key=os.environ["API_KEY"])

PERSONA = (
    "You are Mara, a dry-witted ship engineer in a space opera. "
    "Stay in character, answer in two to four sentences, and never mention being an AI."
)
history = [{"role": "system", "content": PERSONA}]

while True:
    user = input("you> ").strip()
    if user in {"quit", "exit"}:
        break
    history.append({"role": "user", "content": user})
    resp = client.chat.completions.create(
        model="uncensored",
        messages=history,
        temperature=0.9,
        top_p=0.95,
    )
    text = resp.choices[0].message.content
    history.append({"role": "assistant", "content": text})
    print("mara>", text)

Örneklem ayarları modele doğrudan iletilir: temperature, top_p, stop, seed ve frekans ile varlık cezaları. Rol yapma için 0,8 ile 1,0 arasındaki bir sıcaklık genellikle daha canlı diyaloglar sağlar, daha düşük bir değer yapılandırılmış görevler için uygundur. Benzer koşullar altında iki istem versiyonunu karşılaştırmak istediğinizde seed ayarlayın.

Bir konuşmayı kaydedin ve yeniden yükleyin

Komut dosyası sonlandığında kaybolan bir sohbet bir demo'dur, bir uygulama değil. Geçmişi bir JSON dosyası olarak depolamak, onu kalıcı hissettiren en küçük adımdır. Aşağıdaki yardımcı program, varsa bir karakterin kaydedilmiş mesajlarını yükler ve her dönüşün ardından bunları geri yazar.

import json
from pathlib import Path

def load(name, persona):
    path = Path(f"{name}.json")
    if path.exists():
        return json.loads(path.read_text())
    return [{"role": "system", "content": persona}]

def save(name, history):
    Path(f"{name}.json").write_text(json.dumps(history, indent=2))

Başlangıçta load işlevini çağırın ve asistan yanıtını ekledikten sonra save işlevini çağırın. Her karakter ve kullanıcı için ayrı bir dosya tutun; çok karakterli kurulumunuz zaten mevcut. Dosyalar yetersiz kaldığında, aynı sözlük listesi, API'nin beklediği tam yapıda olduğu için değişiklik yapmadan bir veritabanı sütununa veya anahtar-değer deposuna uyar.

Ne depoladığınızı düşünün. Geçmiş, kullanıcıların girdiği kişisel ayrıntılar içerebilir. Bu API'ye gönderilen istemler eğitim için kullanılmaz, ancak kendi dosyalarınız ve günlükleriniz sizin sorumluluğunuzdadır, bu nedenle bunları ne kadar süreyle saklayacağınızı ve kimlerin okuyabileceğine karar verin.

Maliyet artmadan önce geçmişi kısaltın

Bağlam penceresi 100.000 token'dır; istem ve tamamlama metni birlikte. Uzun bir rol yapma oyunu zamanla buna ulaşabilir ve her adımda tam geçmiş için girdi token'ları için ödeme yaptığınız için maliyet artar. Basit bir yaklaşım sistem mesajını ve son N etkileşimi korur.

def trimmed(history, keep=20):
    system = history[:1]
    rest = history[1:]
    return system + rest[-keep:]

# inside the loop
resp = client.chat.completions.create(
    model="uncensored",
    messages=trimmed(history),
)

Uzun hikayeler için daha iyi bir tasarım kayan özettir. Her 30 mesajda, modelden daha eski kısmı 200 kelimede özetlemesini isteyin, bu mesajları sistem mesajının içindeki özetle değiştirin ve devam edin. Bazı ayrıntıları kaybedersiniz ancak hikaye ipliklerini korursunuz ve dönüş başına maliyet sabit kalır.

300 token'lık yanıtla 8.000 token geçmişe ulaşmış bir sohbet için matematik şöyledir: girdi 8.000 x $0,15 / 1.000.000 = $0,0012, çıktı 300 x $0,50 / 1.000.000 = $0,00015, yani adım başı $0,00135. Bu geçmişi 2.000 token'a kısaltmak, adımı $0,0003 + $0,00015 = $0,00045'e düşürür. Bu, çoğu konuşma için fiyatın üçte biridir.

Yanıtları yazılırken akış olarak gönderin

Bir sohbet arayüzü için metnin oluşturulurken görünmesini istersiniz. stream=True ayarlayın ve parçalar üzerinde döngüye girin. Akış, sunucu tarafından gönderilen olaylar üzerinden çalışır ve son parçada kullanım bilgisi isteyebilirsiniz.

stream = client.chat.completions.create(
    model="uncensored",
    messages=history,
    stream=True,
    stream_options={"include_usage": True},
)

parts = []
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        piece = chunk.choices[0].delta.content
        parts.append(piece)
        print(piece, end="", flush=True)
print()
reply = "".join(parts)

Akışlı bir isteğin, akış bitene kadar eşzamanlılık slotunu tuttuğunu unutmayın. Tam anahtarla aynı anda 8 çalıştırabilirsiniz; deneme anahtarında yalnızca 2. Bir kullanıcı sekmeyi kapatırsa, sunucunuzun da yukarı akışı kapattığından emin olun, aksi takdirde slotu meşgul etmeye devam eder.

asyncio ile birçok sohbeti eşzamanlı çalıştırın

Aynı anda birçok kullanıcıyı işleyen bir web hizmeti asenkron istemciye ihtiyaç duyar. Desen basittir: bir paylaşılan AsyncOpenAI istemcisi, eşzamanlılık sınırınıza göre boyutlandırılmış bir semafor (semaphore) ve her konuşma için bir coroutine (eş yordam).

import asyncio
import os
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://api.characteraiapi.com/v1", api_key=os.environ["API_KEY"])
gate = asyncio.Semaphore(8)  # use 2 on a trial key

async def reply(messages):
    async with gate:
        r = await client.chat.completions.create(model="uncensored", messages=messages)
        return r.choices[0].message.content

async def main():
    jobs = [
        reply([{"role": "user", "content": f"Give character {i} a one-line greeting."}])
        for i in range(20)
    ]
    for text in await asyncio.gather(*jobs):
        print(text)

asyncio.run(main())

Yirmi iş oluşturulur, ancak yalnızca sekizi aynı anda çalışır. Gerisi semafor içinde sırasını bekler, böylece concurrency hatasını tetiklemezsiniz. Hizmetiniz akış yanıtlarını işliyorsa, her açık akışın bitene kadar sayıldığını unutmayın; bu, istemci tarafındaki yavaş okuyucuların beklenenden daha uzun süre slotları tutabileceği anlamına gelir. İstemciye bir zaman aşımı ayarlayın ve kullanıcıları gitmiş olan akışları iptal edin.

Dakika başı limit ayrıdır. Tam anahtar için dakikada 300 istekle, 20 kısa çağrılık ani bir artış sorun olmaz, ancak binlerce çağrı gönderen bir döngü hız düzenlemesi gerektirir. Basit bir yaklaşım, görev başlatmaları arasında saniyenin bir kesri kadar beklemek veya yığınınıza uyan bir token bucket kütüphanesi kullanmaktır.

Araçlar ve JSON modu

Karakter botları genellikle yapılandırılmış çıktı gerektirir: bir ruh hali puanı, bir envanter güncellemesi, oyuncu için bir seçenek listesi. JSON modu, yanıtı geçerli JSON yapar ve şekli istemde tanımlarsınız.

import json

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON only: {\"mood\": string, \"choices\": [string, string, string]}"},
        {"role": "user", "content": "Mara finds a sealed hatch in the cargo bay."},
    ],
)
data = json.loads(resp.choices[0].message.content)
print(data["mood"], data["choices"])

Fonksiyon çağırma, standart tools ve tool_choice alanlarını kullanır. Model bir tool_calls girdisi döndürür, kodunuz fonksiyonu çalıştırır ve sonucu role: "tool" ile bir mesaj olarak geri gönderirsiniz.

tools = [{
    "type": "function",
    "function": {
        "name": "roll_dice",
        "description": "Roll an n-sided die",
        "parameters": {
            "type": "object",
            "properties": {"sides": {"type": "integer"}},
            "required": ["sides"],
        },
    },
}]

msgs = [{"role": "user", "content": "Mara tries to force the hatch. Roll a d20."}]
first = client.chat.completions.create(model="uncensored", messages=msgs, tools=tools)
call = first.choices[0].message.tool_calls[0]

msgs.append(first.choices[0].message)
msgs.append({"role": "tool", "tool_call_id": call.id, "content": "17"})
final = client.chat.completions.create(model="uncensored", messages=msgs, tools=tools)
print(final.choices[0].message.content)

Buna güvenmeden önce kendi istemlerinizle test edin. Açık ağırlıklı modeller, bir fonksiyon çağrısını ne kadar güvenilir şekilde ürettikleri konusunda farklılık gösterir; bu nedenle tool_calls boş olduğunda bir yedek yol bulundurun.

Hataları ve hız limitlerini yönetin

Tam anahtar 8 eşzamanlı istek ve dakikada 300 istek sağlar. Deneme anahtarı 2 ve 60 sağlar. Bir limitin üzerinde rate_limited (dakikada çok fazla) veya concurrency (aynı anda çok fazla) hata koduyla HTTP 429 alırsınız. Geçici bir aşırı yüklenme de Retry-After: 5 başlığıyla 429 döndürür. SDK bunlar için RateLimitError yükseltir ve çağrıyı bir yeniden deneme içine alabilirsiniz.

import time
import openai

def chat(messages, tries=4):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except openai.RateLimitError as err:
            wait = 5
            retry_after = err.response.headers.get("Retry-After")
            if retry_after:
                wait = int(retry_after)
            time.sleep(wait * (attempt + 1))
    raise RuntimeError("still rate limited")

Tek bir işlem üzerinden çok sayıda sohbet çalıştırıyorsanız, aynı anda 8 isteği aşmamak için onları bir semaförle sınırlayın. asyncio ve AsyncOpenAI ile, her çağrı etrafında asyncio.Semaphore(8) yeterlidir. Yanıt başlıkları X-RateLimit-Limit-Requests ve X-RateLimit-Limit-Concurrency, anahtarınız için geçerli limitleri doğrular ve X-Balance-USD kalan kredinizi gösterir.

Başarısız veya reddedilen istekler için ücret alınmaz, bu nedenle hatalarda yeniden denemeler size maliyet yaratmaz. Bakiyeniz azaldığında, $20 ile $500 arasında bakiye yükleyin; $50 ve üzeri tutarlara $50, $100 ve $200 seviyelerinde sırasıyla %5, %10 veya %15 bonus eklenir. Detaylar fiyatlandırma sayfasında yer alır ve tam parametre listesi dokümantasyonda bulunur.

Her oturumun maliyetini takip edin

Her akışsız yanıt, usage nesnesiyle prompt_tokens ve completion_tokens içerir. Akış yaparsanız ve kullanım isterseniz, son parça bunu taşır. Bu sayıları küçük bir işlevle dolara çevirin ve oturum kimliğinin yanına günlüğe kaydedin.

IN_PRICE = 0.15 / 1_000_000
OUT_PRICE = 0.50 / 1_000_000

def cost(usage):
    return usage.prompt_tokens * IN_PRICE + usage.completion_tokens * OUT_PRICE

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Describe the engine room in three lines."}],
)
print(f"${cost(resp.usage):.6f}")

Bu sayılarla pratik soruları yanıtlayabilirsiniz. Ortalama bir oturum 40 dönüş ise, geçmiş 500'den 6.000 girdi tokenına ve yanıt başına 250 çıktı tokenına ulaşıyorsa, ortalama girdi yaklaşık 3.250 token'dır. Dönüş başına girdi maliyeti yaklaşık 3.250 x $0,15 / 1.000.000 = $0,00049 ve çıktı 250 x $0,50 / 1.000.000 = $0,000125'tir, yani dönüş başına yaklaşık $0,00061 ve 40 dönüş için $0,0245. Ayda 20 oturum oynayan bir kullanıcı size yaklaşık 49 sent tutarına mal olur. Bu, bir ürün için fiyat belirlemenize olanak veren bir sayıdır.

Bağlantı kontrolünü bir sanal ortam içinde çalıştırın böylece paket sürümü proje için sabit kalır ve başlangıçta client.models.list() ile modelleri bir kez listeleyin. Bu çağrı başarısız olursa, yanlış anahtar veya yanlış base URL hakkında kullanıcıdan önce haberiniz olur ve bir sohbet döngüsünün derinliklerinde yığın izlemesi yerine net bir mesaj yazdırabilirsiniz. Bu kodu dağıtan ekipler, genellikle aynı çağrıyı bir sağlık kontrolü yoluna ekler.

Oturum başına maliyeti günlüğe kaydedin ve en üst yüzde beşe bakın. Geçmişi asla kısaltmayan uzun oturumlar faturayı genellikle domine eder ve düzeltme daha önce açıklanan kısaltma veya özet yaklaşımıdır.

Sorular ve cevaplar

Resmi bir Character.ai Python kütüphanesi var mı?

Bu hizmet Character.ai değildir ve ayrı bir kütüphanesi yoktur. Yukarıda verilen base URL ve model ID ile standart openai paketini kullanırsınız.

Karakter tutarlılığını mesajlar arasında nasıl koruyabilirim?

Kişiliği sistem istemine ekleyin ve her istekte güncel geçmişi yeniden gönderin. API, konuşmaları sizin için saklamaz.

Asenkron istemciyi kullanabilir miyim?

Evet. AsyncOpenAI aynı base_url ve api_key'i kabul eder. Tam anahtar için paralel çağrıları 8'e, deneme anahtarı için 2'ye kadar sınırlayın.

Bir sohbet dönüşü ne kadar tutar?

1.500 girdi token ve 300 çıktı token ile maliyet $0,000375'tir (1M token başına $0,15 ve $0,50 baz alınmıştır). Daha uzun geçmiş, girdi payını artırır.

Python SDK ile akış çalışır durumda mı?

Evet. stream=True parametresini iletin ve parçaları yineleyin. Kullanım bilgisi akışın sonunda gönderilir.

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