Справочник Uncensored API: поля с пояснениями

Конвенции и транспорт

Базовый URL — https://api.uncensoredapis.com/v1. Все тела запросов — JSON и UTF-8. Каждый запрос содержит Authorization: Bearer <key>; отсутствие или неверный ключ возвращает 401. Существует только два маршрута, любой другой путь возвращает 404.

Метод	Путь	Назначение
POST	/v1/chat/completions	Сгенерируйте сообщение ассистента, опционально с потоковой передачей
GET	/v1/models	Список доступных для запроса идентификаторов моделей

API работает только с текстом. Нет маршрутов для эмбеддингов, изображений, аудио или видео, нет дообучения, и доступна ровно одна модель, к которой обращаются по имени uncensored. Поскольку сетевой формат совместим с соглашением о завершении чата, официальные Python и Node SDK работают, если вы переопределите base_url. Документация на docs описывает настройку первого запуска; эта страница — справочник по уровням полей.

Поля тела запроса

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

Поле	Тип	Примечания
model	string	Всегда "uncensored".
messages	array	Упорядоченные объекты с role (system, user, assistant, tool) и content.
max_tokens	integer	Лимит на длину ответа. По умолчанию 2048, максимум 32 000.
temperature	number	Случайность. Меньше — более детерминированно.
top_p	number	Порог сэмплирования ядра.
stop	string or array	Последовательности, завершающие генерацию.
stream	boolean	true переключает ответ на серверные события.
tools	массив	Определения функций в формате JSON-схема.

Вот полный аннотированный запрос. Системное сообщение задаёт поведение, пользовательское сообщение содержит задачу, а stop завершает генерацию при первой пустой строке.

Copycurl https://api.uncensoredapis.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a terse release-notes writer."},
      {"role": "user", "content": "Summarize: fixed login bug, added dark mode."}
    ],
    "max_tokens": 120,
    "temperature": 0.4,
    "stop": ["\n\n"]
  }'

Важны два правила бюджета. Во-первых, промпт плюс генерация должны укладываться в 100 000 токенов, поэтому запрос, в котором количество токенов промпта плюс max_tokens превышает этот лимит, будет отклонён с кодом 400. Во-вторых, сериализованное тело запроса не должно превышать 8 МБ. Если вы отправляете длинные истории, обрезайте старые реплики на своей стороне, прежде чем они приблизятся к любому из этих лимитов.

Объект ответа

Вызов без потоковой передачи возвращает один объект JSON. Читайте его сверху вниз следующим образом.

Copy{
  "id": "chatcmpl-example123",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "v1.4: Login bug fixed. Dark mode added."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 14,
    "total_tokens": 52
  }
}

• id: уникальный идентификатор завершения. Записывайте его рядом с вашим собственным идентификатором запроса, когда вам нужно сопоставить события.
• object: константа chat.completion.
• created: временная метка Unix в секундах.
• model: повторяет значение uncensored.
• choices: массив. Вы получаете одну запись, поэтому choices[0] — это ответ. index указывает его позицию.
• choices[].message: role — это assistant; content содержит текст или равен null, когда модель вернула вызовы функций вместо текста.
• choices[].finish_reason: причина остановки генерации; см. следующий раздел.
• usage: учёт токенов для биллинга, рассмотрен ниже.

Значения finish_reason

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

Значение	Значение	Что должен делать ваш код
stop	Модель достигла естественного конца или сработала одна из ваших последовательностей stop.	Используйте содержимое как есть.
length	Был достигнут лимит max_tokens (или контекстное окно) в середине ответа.	Увеличьте max_tokens, сократите промпт или попросите модель продолжить.
tool_calls	Модель хочет, чтобы были выполнены одна или несколько функций.	Выполните их и отправьте результаты обратно в виде сообщений tool.

Когда значение равно tool_calls, сообщение выглядит следующим образом, с аргументами, переданными в виде JSON string, который вы должны распарсить самостоятельно:

Copy{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc1",
        "type": "function",
        "function": {"name": "get_order", "arguments": "{\"order_id\": 8841}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Всегда оборачивайте json.loads или JSON.parse для arguments в блок обработки ошибок, потому что сгенерированный JSON иногда может быть некорректным.

Блок usage и его стоимость

usage сообщает о prompt_tokens, completion_tokens и total_tokens. Это числа, с которых списывается ваш баланс: ввод по $0,25 за миллион токенов и вывод по $1,00 за миллион. Предоплаченный баланс списывается за запрос, без подписки.

Пример расчёта при указанных предположениях: предположим, что запрос использует 2 000 токенов промпта и 500 токенов завершения. Стоимость ввода: 2 000 / 1 000 000 × $0,25 = $0,0005. Стоимость вывода: 500 / 1 000 000 × $1,00 = $0,0005. Итоговая стоимость запроса: $0,0010. Эти подсчёты токенов являются предположениями для арифметики, а не измерением реальной нагрузки. На странице цен указаны тарифы в одном месте.

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

Формат потокового чанка

Установите "stream": true, и ответ станет потоком text/event-stream. Каждое событие — это строка, начинающаяся с data: , за которой следует JSON, разделённые пустой строкой. Тип объекта меняется на chat.completion.chunk, а message заменяется на delta.

Copydata: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"v1.4: "},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Login bug fixed."},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":38,"completion_tokens":14,"total_tokens":52}}

data: [DONE]

1. Первый чанк обычно устанавливает delta.role в значение assistant с пустым содержимым.
2. Чанки содержимого несут фрагмент в delta.content. Склеивайте их в порядке поступления.
3. Завершающий чанк контента имеет пустой delta и непустой finish_reason.
4. Последний чанк с пустым массивом choices содержит usage. Вы не запрашиваете его явно; он добавляется автоматически.
5. Буквальный текст data: [DONE] завершает поток.

Защититесь от пустого массива choices: обращение к choices[0] в чанке usage вызывает ошибку в простых циклах. Пример SDK ниже обрабатывает это.

Copyimport os
from openai import OpenAI

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

reason, usage = None, None
for chunk in client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Name three uses of a rubber duck in debugging."}],
    stream=True,
):
    if chunk.choices:
        piece = chunk.choices[0].delta.content
        if piece:
            print(piece, end="", flush=True)
        if chunk.choices[0].finish_reason:
            reason = chunk.choices[0].finish_reason
    if getattr(chunk, "usage", None):
        usage = chunk.usage

print("\nfinish:", reason, "| tokens:", usage.total_tokens if usage else "n/a")

Для потоковых вызовов функций delta.tool_calls приходит фрагментами; накапливайте строку arguments для каждого индекса вызова и парсите её один раз, когда finish_reason равен tool_calls.

Эндпоинт моделей

GET /v1/models требует только заголовок Bearer и возвращает объект-список. Поскольку существует одна модель, data содержит одну запись, uncensored. Клиенты, которые заполняют выпадающий список моделей через этот маршрут, будут показывать один вариант.

Copycurl https://api.uncensoredapis.com/v1/models -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {"id": "uncensored", "object": "model"}
  ]
}

Это также самый дешёвый способ проверить ключ: 200 означает, что ключ действителен, 401 — что он неверен или был перегенерирован. Вызов этого эндпоинта не генерирует токены. По правилам обработки ошибок и повторных попыток см. руководство по ошибкам и лимитам запросов.

Чек-лист для авторов клиентов

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

1. Чистота заголовков. Передавайте ключ только в заголовке Authorization, никогда в строке запроса и никогда не логируйте значение заголовка.
2. Парсите с осторожностью. Относитесь к неизвестным дополнительным полям в ответах как к игнорируемым. Фиксируйте ваш парсер на полях, описанных здесь, а не на точном порядке ключей JSON.
3. Проверяйте finish_reason в каждом ответе. Отображайте видимый индикатор, когда он равен length, иначе пользователи будут читать обрезанный текст как полный ответ.
4. Оценивайте бюджет перед отправкой. Оцените количество токенов промпта, добавьте ваш max_tokens и сравните сумму с 100 000. Отклонение на стороне клиента быстрее, чем ожидание ответа 400.
5. Обработайте конец потока. Ожидайте чанк с пустым списком choices и объектом usage, затем [DONE]. Закройте соединение после сигнального значения.
6. Записывайте использование. Сохраняйте total_tokens за запрос, чтобы позже сверить собственную статистику с предоплаченным балансом.
7. Уважайте потолок. Аккаунт позволяет 300 запросов в минуту на ключ, поэтому шлюз, распределяющий запросы многим пользователям, должен иметь свою очередь.

Ни один из этих шагов не зависит от SDK поставщика. Достаточно обычного HTTP-клиента, который устанавливает заголовок Bearer и декодирует JSON, а примеры SDK на этой странице — это удобства, а не требования. Сопоставьте этот чек-лист с таблицей ошибок в playbook, и вы покроете весь жизненный цикл запроса: сбор, отправка, потоковая передача, разбор, учёт и восстановление.