ID ▾
Dapatkan kunci API

API Character AI di Python: Pengaturan SDK OpenAI

Untuk menggunakan alur kerja Python API Character AI, instal paket openai resmi, arahkan base URL-nya ke endpoint yang kompatibel dengan OpenAI dan atur modelnya menjadi uncensored. Sisa halaman ini membangun obrolan persona kecil di atasnya, dengan riwayat, streaming, percobaan ulang, dan pelacakan biaya.

Terminal di platform yang menampilkan gelembung obrolan streaming ke kubus yang terhubung, mewakili klien obrolan Python

Poin utama

  1. Dua nilai berubah dalam SDK standar: base_url dan api_key.
  2. Perilaku karakter berasal dari pesan sistem ditambah riwayat yang Anda kirimkan ulang setiap giliran.
  3. Streaming, pemanggilan fungsi, dan mode JSON semuanya berfungsi melalui klien yang sama.
  4. Tangani HTTP 429 dengan jeda singkat dan batasi panggilan paralel hingga 8 pada kunci penuh.

Instal dan sambungkan

Tidak ada pustaka klien khusus. Aplikasi karakter di Python menggunakan paket openai yang sama seperti yang lain. Instal dan simpan kunci Anda dalam variabel lingkungan.

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

Dapatkan kunci dari halaman kunci API terlebih dahulu. Akun baru dapat mengklaim $0,50 kredit uji coba di sana dengan satu klik, tanpa kartu. Kemudian buat klien:

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)

Jika itu mencetak salam dan objek penggunaan, koneksi baik. Layanan mengekspos POST /v1/chat/completions dan GET /v1/models. Apa pun yang bukan obrolan teks, seperti gambar, embedding, atau fine-tuning, tidak tersedia.

Loop obrolan karakter dengan memori

API bersifat stateless. API tidak mengingat giliran terakhir, jadi program Anda harus mengirim seluruh percakapan setiap kali. Untuk persona, ini berarti system message diikuti oleh pesan user dan assistant yang bergantian. Loop ini menyimpannya dalam daftar.

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)

Pengaturan sampling diteruskan ke model: temperature, top_p, stop, seed dan penalti frekuensi serta kehadiran. Untuk roleplay, temperature antara 0,8 dan 1,0 biasanya memberikan dialog yang lebih hidup, sedangkan nilai yang lebih rendah cocok untuk tugas terstruktur. Atur seed ketika Anda ingin membandingkan dua versi prompt dalam kondisi serupa.

Simpan dan muat ulang percakapan

Obrolan yang hilang saat skrip keluar adalah demo, bukan aplikasi. Menyimpan riwayat sebagai file JSON adalah langkah terkecil yang membuatnya terasa persisten. Helper di bawah ini memuat pesan karakter yang disimpan jika ada, dan menulisnya kembali setelah setiap giliran.

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

Panggil load saat startup dan save setelah Anda menambahkan balasan assistant. Simpan satu file per karakter dan per pengguna, dan Anda sudah memiliki pengaturan multi-karakter. Setelah file tidak lagi memadai, daftar dict yang sama cocok untuk kolom database atau penyimpanan key-value tanpa perubahan, karena itu persis apa yang diharapkan API.

Pikirkan apa yang Anda simpan. Riwayat mungkin berisi detail pribadi yang diketik pengguna. Prompt yang dikirim ke API ini tidak digunakan untuk pelatihan, tetapi file dan log Anda sendiri adalah tanggung jawab Anda, jadi putuskan berapa lama Anda menyimpannya dan siapa yang dapat membacanya.

Potong riwayat sebelum menjadi mahal

Jendela konteks adalah 100.000 token, prompt plus completion. Roleplay panjang dapat mencapai itu seiring waktu, dan biaya meningkat karena Anda membayar token input untuk seluruh riwayat di setiap giliran. Pendekatan sederhana menjaga system message dan N pertukaran terakhir.

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

Desain yang lebih baik untuk cerita panjang adalah ringkasan bergulir. Setiap 30 pesan, minta model untuk meringkas bagian yang lebih tua dalam 200 kata, ganti pesan-pesan itu dengan ringkasan di dalam system message, dan lanjutkan. Anda kehilangan beberapa detail tetapi menjaga alur cerita, dan biaya per giliran tetap datar.

Berikut adalah matematika untuk obrolan yang telah mencapai 8.000 token riwayat dengan balasan 300 token: input adalah 8.000 x $0,15 / 1.000.000 = $0,0012, output adalah 300 x $0,50 / 1.000.000 = $0,00015, jadi $0,00135 per giliran. Memotong riwayat itu menjadi 2.000 token menurunkan giliran menjadi $0,0003 + $0,00015 = $0,00045. Itu sepertiga harga untuk sebagian besar percakapan.

Alirkan balasan saat ditulis

Untuk antarmuka obrolan, Anda ingin teks muncul saat dihasilkan. Atur stream=True dan iterasi melalui chunk. Streaming berjalan di atas server-sent events, dan Anda dapat meminta penggunaan di chunk terakhir.

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)

Ingat bahwa permintaan yang dialirkan memegang slot konkurensinya hingga stream berakhir. Pada kunci penuh, Anda dapat menjalankan 8 sekaligus; pada kunci uji coba hanya 2. Jika pengguna menutup tab, pastikan server Anda menutup stream hulu juga, atau slot tetap sibuk.

Jalankan banyak obrolan sekaligus dengan asyncio

Layanan web yang menangani banyak pengguna secara bersamaan memerlukan klien async. Polanya sederhana: satu klien AsyncOpenAI bersama, satu semaphore yang ukurannya sesuai dengan batas konkurensi Anda, dan koroutine per percakapan.

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

Dua puluh pekerjaan dibuat, tetapi hanya delapan yang berjalan sekaligus. Sisanya menunggu giliran di dalam semaphore, jadi Anda tidak pernah memicu error concurrency. Jika layanan Anda menangani balasan streaming, ingat bahwa setiap stream terbuka dihitung hingga selesai, yang berarti pembaca lambat di sisi klien dapat menahan slot lebih lama dari yang Anda harapkan. Atur timeout pada klien dan batalkan stream yang penggunanya telah pergi.

Batas per menit terpisah. Pada 300 permintaan per menit pada kunci penuh, lonjakan 20 panggilan pendek tidak masalah, tetapi loop yang mengirim ribuan panggilan perlu penjadwalan. Pendekatan sederhana adalah memberi jeda sepersekian detik antara peluncuran tugas, atau gunakan pustaka token bucket yang sesuai dengan tumpukan Anda.

Alat dan mode JSON

Bot karakter sering membutuhkan output terstruktur: skor suasana hati, pembaruan inventaris, daftar pilihan untuk pemain. Mode JSON membuat balasan berupa JSON yang valid, dan Anda menggambarkan bentuknya dalam prompt.

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"])

Pemanggilan fungsi menggunakan bidang tools dan tool_choice standar. Model mengembalikan entri tool_calls, kode Anda menjalankan fungsi, dan Anda mengirim hasilnya kembali sebagai pesan dengan role: "tool".

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)

Uji ini terhadap prompt Anda sendiri sebelum mengandalkannya. Model bobot terbuka berbeda dalam seberapa andal mereka mengeluarkan panggilan alat, jadi jaga jalur cadangan ketika tool_calls kosong.

Tangani error dan batas laju

Kunci penuh memungkinkan 8 permintaan konkuren dan 300 permintaan per menit. Kunci uji coba memungkinkan 2 dan 60. Di atas batas, Anda mendapatkan HTTP 429 dengan kode error rate_limited (terlalu banyak per menit) atau concurrency (terlalu banyak sekaligus). Kelebihan beban sementara juga mengembalikan 429, dengan header Retry-After: 5. SDK menaikkan RateLimitError untuk ini, dan Anda dapat membungkus panggilan dalam retry.

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

Jika Anda menjalankan banyak percakapan dari satu proses, batasi dengan semaphore sehingga Anda tidak pernah melebihi 8 permintaan yang sedang berlangsung. Dengan asyncio dan AsyncOpenAI, asyncio.Semaphore(8) di sekitar setiap panggilan sudah cukup. Header respons X-RateLimit-Limit-Requests dan X-RateLimit-Limit-Concurrency mengonfirmasi batas yang berlaku untuk kunci Anda, dan X-Balance-USD menunjukkan sisa kredit Anda.

Permintaan yang gagal atau ditolak tidak dibebankan biaya, sehingga percobaan ulang saat terjadi error tidak membebani Anda. Ketika saldo Anda rendah, isi saldo dari $20 hingga $500; jumlah dari $50 mendapatkan bonus 5%, 10%, atau 15% pada level $50, $100, dan $200. Detailnya ada di halaman harga, dan daftar parameter lengkap ada di dokumentasi.

Lacak biaya setiap sesi

Setiap respons non-streaming menyertakan objek usage dengan prompt_tokens dan completion_tokens. Saat Anda streaming dan meminta penggunaan, chunk terakhir membawanya. Ubah angka-angka itu menjadi dolar dengan fungsi kecil dan catat di samping ID sesi.

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

Dengan angka-angka ini Anda dapat menjawab pertanyaan praktis. Jika sesi rata-rata adalah 40 giliran, dengan riwayat yang tumbuh dari 500 menjadi 6.000 token input dan 250 token output per balasan, input rata-rata adalah sekitar 3.250 token. Biaya input per giliran adalah sekitar 3.250 x $0,15 / 1.000.000 = $0,00049 dan output adalah 250 x $0,50 / 1.000.000 = $0,000125, jadi sekitar $0,00061 per giliran dan $0,0245 untuk 40 giliran. Pengguna yang bermain 20 sesi sebulan membebani Anda sekitar 49 sen. Itu adalah angka yang dapat Anda gunakan untuk menentukan harga produk.

Jalankan pemeriksaan koneksi di dalam lingkungan virtual agar versi paket tetap untuk proyek tersebut, dan daftarkan model sekali dengan client.models.list() saat awal. Jika panggilan itu gagal, Anda mengetahui tentang kunci yang salah atau base URL yang salah sebelum pengguna apa pun melakukannya, dan Anda dapat mencetak pesan yang jelas alih-alih stack trace yang dalam di dalam loop obrolan. Tim yang menerapkan kode ini sering menambahkan panggilan yang sama ke rute pemeriksaan kesehatan.

Catat biaya per sesi dan lihat lima persen teratas. Sesi panjang yang tidak pernah memotong riwayat biasanya mendominasi tagihan, dan perbaikannya adalah pendekatan pemotongan atau ringkasan yang dijelaskan sebelumnya.

Tanya jawab

Apakah ada pustaka Python resmi untuk Character.ai?

Layanan ini bukan Character.ai dan tidak memiliki pustaka terpisah. Anda menggunakan paket openai standar dengan URL dasar dan ID model yang disebutkan di atas.

Bagaimana cara menjaga konsistensi karakter di seluruh pesan?

Masukkan persona ke dalam pesan sistem dan kirim ulang riwayat terbaru dengan setiap permintaan. API tidak menyimpan percakapan untuk Anda.

Bisakah saya menggunakan klien asinkron?

Ya. AsyncOpenAI menerima base_url dan api_key yang sama. Batasi panggilan paralel hingga 8 pada kunci penuh atau 2 pada kunci uji coba.

Berapa biaya satu giliran obrolan?

Dengan 1.500 token input dan 300 token output, biayanya adalah $0,000375, berdasarkan $0,15 dan $0,50 per 1 juta token. Riwayat yang lebih panjang meningkatkan porsi input.

Apakah streaming berfungsi dengan SDK Python?

Ya. Teruskan stream=True dan iterasi melalui potongan data. Penggunaan data dikirim di akhir aliran.

Kunci Anda hanya selangkah lagi dari satu formulir

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

Dapatkan kunci API