Быстрый старт с 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 токенов, включая ваши определения и результаты инструментов. Сексуальный контент с участием несовершеннолетних запрещён, и это относится к структурированному и инструментальному выводу так же, как и к обычному чату.
