RU ▾
Получить API-ключ
API без цензуры, совместимый с OpenAI, для разработчиков.Обновлено

JSON-режим и вызов функций Uncensored LLM API

Переключатель JSON-режима в uncensored llm api — тот же, что вы уже знаете по клиентам OpenAI: отправьте response_format с типом json_object, и ответ вернётся в виде объекта JSON. На этой странице разобраны он и вызов инструментов, с кодом, который можно запустить на рабочем эндпоинте.

Светящиеся скобки, собранные из кубиков механической рукой, иллюстрируют структурированный вывод JSON и вызовы функций

Быстрый старт с curl

Самый простой рабочий запрос JSON-режима выглядит так. Он использует базовый URL https://api.uncensoredllmapi.com/v1, модель uncensored и ваш ключ в качестве Bearer-токена:

curl https://api.uncensoredllmapi.com/v1/chat/completions   -H "Authorization: Bearer $UNCENSORED_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Reply only with a JSON object."},
      {"role": "user", "content": "Create a tavern NPC with keys name, trade and rumour."}
    ]
  }'

Сообщение ассистента в choices[0].message.content — это строка, содержащая объект JSON. Вам нужно распарсить его самостоятельно. Не пропускайте инструкцию в промпте: JSON-режим ограничивает вывод объектом, но не может угадать, какие ключи вам нужны. Указание ключей и, желательно, примера в одну строку дает стабильную структуру.

Если у вас ещё нет ключа, на странице API-ключ можно одним кликом получить $0,50 пробного баланса после регистрации. Этот баланс не требует оплаты, действует 7 дней и выдаётся один раз на человека.

JSON-режим в Python с валидацией

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

import json, os
from openai import OpenAI
from pydantic import BaseModel, ValidationError

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

class Npc(BaseModel):
    name: str
    trade: str
    rumour: str

SYSTEM = (
    "Reply only with a JSON object with exactly these keys: "
    "name, trade, rumour. Each value is a string."
)

def make_npc(setting, tries=3):
    for _ in range(tries):
        r = client.chat.completions.create(
            model="uncensored",
            response_format={"type": "json_object"},
            messages=[
                {"role": "system", "content": SYSTEM},
                {"role": "user", "content": f"Setting: {setting}"},
            ],
            temperature=0.7,
            max_tokens=300,
        )
        choice = r.choices[0]
        if choice.finish_reason == "length":
            continue           # cut off, so the JSON is incomplete
        try:
            return Npc(**json.loads(choice.message.content))
        except (json.JSONDecodeError, ValidationError, TypeError):
            continue
    raise RuntimeError("no valid JSON after retries")

print(make_npc("a river port in a plague year"))

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

Типичные ошибки JSON-режима

  • Запрос JSON в промпте, но не в response_format. Модель часто выполнит это, но может обернуть объект в текст или блок кода. Укажите оба параметра.
  • Слишком низкий max_tokens. Оцените максимально возможный ответ и добавьте запас. Длинный список элементов легко превысит 300 токенов.
  • Ожидание массива верхнего уровня. JSON-режим требует объект. Если нужен список, запросите {"items": [...]}.
  • Стоп-последовательность, которая встречается в JSON. Параметр stop передаётся напрямую, и строка остановки, встречающаяся внутри значения, сократит ответ.
  • Использование JSON-режима с потоковой передачей и парсингом каждого чанка. Сначала соберите весь текст, затем распарсите его один раз в конце.

Параметры сэмплирования, такие как temperature, top_p, seed и штрафы, передаются напрямую. Для задач извлечения низкая температура около 0.2 и фиксированный seed дают наиболее воспроизводимый вывод. Для креативной генерации, как NPC выше, допустимо более высокое значение, если вы проводите валидацию.

Вызов функций: полный цикл

Вызов инструментов позволяет модели попросить ваш код что-то сделать, а затем продолжить работу с результатом. Поток состоит из четырёх шагов: вы объявляете инструменты, модель отвечает tool_calls, вы их выполняете и отправляете результаты обратно как сообщения с role: "tool".

import json, os
from openai import OpenAI

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

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_inventory",
        "description": "Return the stock count for an item in the shop.",
        "parameters": {
            "type": "object",
            "properties": {"item": {"type": "string"}},
            "required": ["item"],
        },
    },
}]

def lookup_inventory(item):
    stock = {"healing potion": 4, "rope": 12}
    return {"item": item, "count": stock.get(item.lower(), 0)}

messages = [{"role": "user", "content": "Do you still have healing potions?"}]

for _ in range(4):                      # hard cap on tool rounds
    r = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools, tool_choice="auto"
    )
    msg = r.choices[0].message
    if not msg.tool_calls:
        print(msg.content)
        break
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = lookup_inventory(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

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

Поле tool_choice позволяет управлять поведением. Оставьте его на значении "auto", и модель примет решение сама. Укажите конкретную функцию, чтобы принудительно вызвать её — это полезно, когда вам нужна извлечение структурированных данных через схему инструмента, а не JSON-режим.

Потоковая передача вызовов функций в Node

При stream: true вызовы инструментов приходят частями. Каждый чанк содержит фрагмент имени функции или строки аргументов, проиндексированный по позиции. Вам нужно склеить фрагменты по индексу и парсить только по завершении потока.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uncensoredllmapi.com/v1",
  apiKey: process.env.UNCENSORED_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Check stock for rope." }],
  tools: [{
    type: "function",
    function: {
      name: "lookup_inventory",
      description: "Return the stock count for an item.",
      parameters: {
        type: "object",
        properties: { item: { type: "string" } },
        required: ["item"],
      },
    },
  }],
});

const calls = [];
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta;
  for (const tc of delta?.tool_calls ?? []) {
    const slot = (calls[tc.index] ??= { id: "", name: "", args: "" });
    if (tc.id) slot.id = tc.id;
    if (tc.function?.name) slot.name += tc.function.name;
    if (tc.function?.arguments) slot.args += tc.function.arguments;
  }
}

for (const c of calls) {
  console.log(c.name, JSON.parse(c.args));
}

Помните, что потоковый запрос удерживает один из ваших слотов одновременных запросов до завершения потока. Полный ключ позволяет 8 одновременных запросов и 300 в минуту, пробный ключ — 2 и 60. Превышение любого лимита даёт HTTP 429 с кодом concurrency или rate_limited. Итоги использования сообщаются в конце потока, что удобно для логирования стоимости.

JSON-режим или схема инструмента

Оба способа дают структурированные данные, так какой же выбрать? Ключевой вопрос: модель генерирует данные или выбирает действие?

Используйте JSON-режим, когда сам вывод — это продукт: карточка NPC, список тегов, классификация с полем уверенности. Вы управляете всем промптом, получаете один объект и оплачиваете один запрос.

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

Практичный компромисс для извлечения: объявите один инструмент, параметры которого — поля, которые вам нужны, и установите tool_choice на эту функцию. Вы получите JSON аргументов, соответствующий форме вашей схемы, без добавления списка ключей в промпт. В любом случае проверяйте результат, прежде чем доверять ему, и логируйте значение X-Request-Id любого запроса, выдавшего неожиданный результат.

Сколько это стоит

JSON и вызовы инструментов оплачиваются как любые другие токены: $0,15 за 1M входных и $0,50 за 1M выходных токенов. Определения инструментов считаются входными данными при каждом запросе, и каждый результат инструмента, который вы отправляете обратно, добавляется к входным данным следующего запроса.

Пример: ход ассистента с использованием инструмента со схемой инструмента и промптом в 600 токенов, вызов модели в 150 токенов, затем второй запрос, содержащий 900 входных токенов (предыдущие сообщения плюс результат инструмента) и ответ в 200 токенов.

  • Запрос один: 600 входных и 150 выходных. Вход 600 x $0.15 / 1M = $0.00009. Выход 150 x $0.50 / 1M = $0.000075. Итого $0.000165.
  • Запрос два: 900 входных и 200 выходных. Вход 900 x $0.15 / 1M = $0.000135. Выход 200 x $0.50 / 1M = $0.0001. Итого $0.000235.
  • Итого за ход: $0.0004.

По этой цене 1000 ходов стоят $0,40. Баланс предоплачен целыми суммами от $20 до $500 (бонус: +5% от $50, +10% от $100, +15% от $200), оплачивается криптовалютой USDT по сети TRC20 или USDC на сети Base. См. страницу тарифов для актуальных цифр.

Куда двигаться дальше

Справочник по каждому полю запроса доступен в API-документации. Если вы готовите приложение к боевой среде, следующей страницей для чтения является чек-лист production, а поддержка поможет, если запрос ведёт себя неожиданно. Сохраняйте ID запроса, который возвращается в заголовке X-Request-Id, под рукой.

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

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

Гарантирует ли JSON-режим точное соответствие схеме?

Нет. Он превращает ответ в объект JSON, но ключи берутся из вашего промпта. Валидируйте результат с помощью библиотеки схем и повторите запрос при ошибке.

Как отправить результаты вызова инструмента обратно?

Добавьте сообщение ассистента, содержащее tool_calls, затем добавьте по одному сообщению на каждый вызов с role tool, соответствующим tool_call_id и результатом в виде строки.

Можно ли потоково передавать вызовы инструментов?

Да. При установке stream в true вызовы инструментов приходят фрагментами. Склеивайте строки имени и аргументов по индексу и парсите один раз после завершения потока.

Тарифицируются ли ответы с невалидным JSON?

Завершённый ответ оплачивается, даже если ваш парсер его отклоняет. Ошибочные или отклонённые запросы не оплачиваются.

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

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