RU ▾
Получить API-ключ

API Character AI на Python: настройка OpenAI SDK

Чтобы использовать рабочий процесс API Character AI на Python, установите официальный пакет openai, укажите его базовый URL на совместимый с OpenAI эндпоинт и установите модель в uncensored. Остальная часть этой страницы создает небольшой чат с личностью поверх этого, с историей, потоковой передачей, повторными попытками и отслеживанием затрат.

Терминал на платформе потокового чата: сообщения выводятся в связанные кубы, представляющие собой Python-клиент для чата

Ключевые моменты

  1. В стандартном SDK изменяются два значения: базовый URL и API-ключ.
  2. Поведение персонажа определяется системным сообщением плюс историей, которую вы отправляете каждый ход.
  3. Потоковая передача, вызов функций и JSON-режим работают через одного и того же клиента.
  4. Обрабатывайте HTTP 429 с короткой задержкой и ограничивайте параллельные вызовы до 8 для полного ключа.

Установка и подключение

Специальной клиентской библиотеки нет. Приложения Character на Python используют тот же пакет openai, что и все остальное. Установите его и храните свой ключ в переменной окружения.

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

Сначала получите ключ на странице API-ключей. Новые аккаунты могут одним кликом получить $0,50 бесплатного пробного баланса без привязки карты. Затем создайте клиент:

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)

Если выводится приветствие и объект использования, подключение работает. Сервис предоставляет POST /v1/chat/completions и GET /v1/models. Все, что не является текстовым чатом, например изображения, эмбеддинги или дообучение, недоступно.

Цикл чата с персонажем и памятью

API не имеет состояния. Он не запоминает последний ход, поэтому ваша программа должна отправлять весь разговор каждый раз. Для личности это означает системное сообщение, за которым следуют чередующиеся сообщения пользователя и помощника. Этот цикл хранит их в списке.

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)

Настройки сэмплирования передаются модели: temperature, top_p, stop, seed, а также штрафы за частоту и присутствие. Для ролевой игры температура в диапазоне 0,8–1,0 обычно даёт более живой диалог, а меньшие значения подходят для структурированных задач. Установите seed, когда хотите сравнить два варианта промпта в схожих условиях.

Сохранение и загрузка разговора

Чат, который исчезает при выходе из скрипта, — это демо, а не приложение. Хранение истории в файле JSON — это минимальный шаг, который делает его постоянным. Вспомогательная функция ниже загружает сохраненные сообщения персонажа, если они существуют, и записывает их обратно после каждого хода.

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

Вызывайте load при запуске и save после добавления ответа помощника. Храните один файл на персонажа и пользователя, и у вас уже есть настройка для нескольких персонажей. Как только вы перерастете файлы, тот же список словарей подойдет для столбца базы данных или хранилища ключ-значение без изменений, потому что это именно то, чего ожидает API.

Подумайте о том, что вы храните. История может содержать личные данные, которые ввели пользователи. Промпты, отправленные в этот API, не используются для обучения, но ваши собственные файлы и журналы — ваша ответственность, поэтому решите, как долго вы их храните и кто может их читать.

Обрезка истории до того, как она станет дорогой

Контекстное окно составляет 100 000 токенов, включая промпт и завершение. Длительная ролевая игра может достичь этого со временем, и стоимость растёт вместе с ней, потому что вы платите за входные токены за полную историю на каждом ходу. Простой подход сохраняет системное сообщение и последние N обменов.

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

Более удачный дизайн для длинных историй — скользящее суммирование. Каждые 30 сообщений просите модель суммировать предыдущую часть в 200 слов, замените эти сообщения суммаризацией внутри системного сообщения и продолжайте. Вы потеряете некоторые детали, но сохраните сюжетные линии, а стоимость за ход останется неизменной.

Вот математика для чата, который достиг 8000 токенов истории с ответом в 300 токенов: входные данные — 8000 x $0,15 / 1 000 000 = $0,0012, выходные данные — 300 x $0,50 / 1 000 000 = $0,00015, итого $0,00135 за ход. Обрезка этой истории до 2000 токенов снижает стоимость хода до $0,0003 + $0,00015 = $0,00045. Это треть цены для большинства разговоров.

Потоковая передача ответов по мере их написания

Для интерфейса чата вы хотите, чтобы текст появлялся по мере его генерации. Установите stream=True и итерируйтесь по чанкам. Потоковая передача работает через события, отправляемые сервером, и вы можете запросить использование в последнем чанке.

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)

Помните, что потоковый запрос удерживает слот параллельных запросов до завершения потока. Для полного ключа можно запустить 8 одновременно; для пробного — только 2. Если пользователь закрывает вкладку, убедитесь, что ваш сервер закрывает и upstream-поток, иначе слот останется занятым.

Запуск множества чатов одновременно с asyncio

Веб-сервис, обрабатывающий множество пользователей одновременно, нуждается в асинхронном клиенте. Схема проста: один общий клиент AsyncOpenAI, один семафор, размер которого соответствует вашему пределу параллелизма, и сопрограмма для каждого разговора.

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

Создано двадцать задач, но одновременно выполняется только восемь. Остальные ждут своей очереди внутри семафора, поэтому вы никогда не вызовете ошибку concurrency. Если ваш сервис обрабатывает потоковые ответы, помните, что каждый открытый поток считается до его завершения, что означает, что медленные читатели на стороне клиента могут удерживать слоты дольше, чем вы ожидаете. Установите тайм-аут на клиенте и отмените потоки, пользователи которых ушли.

Лимит по минуте отдельный. При 300 запросах в минуту для полного ключа всплеск из 20 коротких вызовов — это нормально, но циклу, отправляющему тысячи вызовов, нужна регулировка. Простой подход — делать паузу на долю секунды между запусками задач или использовать библиотеку token bucket (ведро токенов), подходящую для вашего стека.

Инструменты и JSON-режим

Боты персонажей часто нуждаются в структурированном выводе: оценка настроения, обновление инвентаря, список вариантов для игрока. JSON-режим делает ответ действительным JSON, и вы описываете форму в промпте.

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

Вызов функций использует стандартные поля tools и tool_choice. Модель возвращает запись tool_calls, ваш код выполняет функцию, и вы отправляете результат обратно как сообщение с 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)

Протестируйте это против своих собственных промптов, прежде чем полагаться на него. Модели с открытыми весами различаются по надежности выдачи вызова инструмента, поэтому сохраняйте резервный путь, когда tool_calls пуст.

Обработка ошибок и лимитов запросов

Полный ключ позволяет 8 одновременных запросов и 300 запросов в минуту. Пробный ключ позволяет 2 и 60. При превышении лимита вы получаете HTTP 429 с кодом ошибки rate_limited (слишком много в минуту) или concurrency (слишком много одновременно). Временная перегрузка также возвращает 429 с заголовком Retry-After: 5. SDK вызывает RateLimitError для этих случаев, и вы можете обернуть вызов в повторную попытку.

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

Если вы запускаете много бесед из одного процесса, ограничьте их семафором, чтобы никогда не превышать 8 запросов в работе. С asyncio и AsyncOpenAI достаточно обернуть каждый вызов в asyncio.Semaphore(8). Заголовки ответа X-RateLimit-Limit-Requests и X-RateLimit-Limit-Concurrency подтверждают лимиты, применимые к вашему ключу, а X-Balance-USD показывает оставшийся баланс.

Неудачные или отклонённые запросы не оплачиваются, поэтому повторные попытки при ошибках не стоят вам денег. Когда баланс иссякает, пополните его от $20 до $500; суммы от $50 получают бонус 5%, 10% или 15% на уровнях $50, $100 и $200. Подробности на странице цен, а полный список параметров — в документации.

Отслеживание стоимости каждой сессии

Каждый ответ без потоковой передачи содержит объект usage с полями prompt_tokens и completion_tokens. При потоковой передаче и запросе данных об использовании они содержатся в последнем чанке. Преобразуйте эти числа в доллары с помощью небольшой функции и запишите их рядом с ID сессии.

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

Имея эти числа, вы можете ответить на практические вопросы. Если средняя сессия составляет 40 ходов, а история растёт с 500 до 6 000 входных токенов и 250 выходных токенов на ответ, среднее количество входных токенов составляет примерно 3 250. Стоимость входных данных за ход — около 3 250 × $0,15 / 1 000 000 = $0,00049, а выходных — 250 × $0,50 / 1 000 000 = $0,000125, то есть около $0,00061 за ход и $0,0245 за 40 ходов. Пользователь, который играет 20 сессий в месяц, обходится вам примерно в 49 центов. Это число, вокруг которого можно сформировать цену продукта.

Запускайте проверку соединения в виртуальной среде, чтобы версия пакета оставалась фиксированной для проекта, и один раз выводите список моделей с помощью client.models.list() при запуске. Если этот вызов завершится ошибкой, вы узнаете о неверном ключе или базовом URL до того, как это заметит пользователь, и сможете вывести понятное сообщение вместо трассировки стека глубоко в цикле чата. Команды, которые разворачивают этот код, часто добавляют тот же вызов в маршрут проверки работоспособности.

Ведите журнал стоимости за сессию и смотрите на верхние пять процентов. Длинные сессии, которые никогда не обрезают историю, обычно доминируют в счете, и исправление — это подход к обрезке или суммаризации, описанный ранее.

Вопросы и ответы

Существует ли официальная Python-библиотека для Character.ai?

Этот сервис не является Character.ai и не имеет отдельной библиотеки. Вы используете стандартный пакет openai с указанным выше базовым URL и идентификатором модели.

Как обеспечить согласованность персонажа в разных сообщениях?

Добавьте описание персонажа в системное сообщение и отправляйте историю последних сообщений вместе с каждым запросом. API не сохраняет диалоги за вас.

Можно ли использовать асинхронный клиент?

Да. AsyncOpenAI принимает тот же базовый URL и API-ключ. Ограничьте параллельные вызовы до 8 для полного ключа или до 2 для пробного ключа.

Сколько стоит один ход в чате?

При 1 500 входных токенах и 300 выходных токенах стоимость составляет $0,000375, исходя из $0,15 и $0,50 за 1 млн токенов. Увеличение истории повышает долю входных токенов.

Работает ли потоковая передача с Python SDK?

Да. Передайте stream=True и перебирайте чанки. Информация об использовании отправляется в конце потока.

Ваш ключ — всего в одной форме

Создайте аккаунт, скопируйте ключ, измените базовый URL. Это вся настройка.

Получить API-ключ