Решения
POST /v1/decisions отвечает на типизированные вопросы о ваших данных вероятностями, а не
текстом. Используйте его для разметки, проверок и выбора ветки в коде. Формат совместим с
TypeSafe POST /v1/systemone: тот же запрос работает, если сменить адрес и ключ.
curl https://api.souz.ai/v1/decisions \
-H "Authorization: Bearer $SOUZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "jev-1.14",
"state": {"ticket": "Checkout shows a blank page after I click Pay."},
"questions": {
"is_bug": {"type": "noul", "instructions": "Is the customer reporting a software defect?"},
"team": {"type": "choice", "instructions": "Which team should own this ticket?",
"criteria": {"payments": "Checkout and billing.", "frontend": "Layout and rendering."}},
"urgency": {"type": "score", "instructions": "How urgent is this ticket?",
"criteria": ["Can wait", "This week", "Blocking revenue"]}
}
}'import requests
r = requests.post(
"https://api.souz.ai/v1/decisions",
headers={"Authorization": f"Bearer {SOUZ_API_KEY}"},
json={
"model": "jev-1.14",
"state": {"ticket": "Checkout shows a blank page after I click Pay."},
"questions": {
"is_bug": {"type": "noul", "instructions": "Is the customer reporting a software defect?"},
"team": {"type": "choice", "instructions": "Which team should own this ticket?",
"criteria": {"payments": "Checkout and billing.", "frontend": "Layout and rendering."}},
},
},
)
answers = r.json()["answers"]
if answers["is_bug"]["noul"] > 0.8:
route_to(answers["team"]["choice"])const r = await fetch("https://api.souz.ai/v1/decisions", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
model: "jev-1.14",
state: { ticket: "Checkout shows a blank page after I click Pay." },
questions: {
is_bug: { type: "noul", instructions: "Is the customer reporting a software defect?" },
},
}),
});
const { answers } = await r.json();
console.log(answers.is_bug.noul);Поля решений
| Поле | Тип | По умолчанию | Что делает |
|---|---|---|---|
model | string | обязательно | Модель с modality: decision |
state | string, object или array | обязательно | Данные, о которых вопросы |
questions | object | обязательно | Вопросы по имени ответа, от одного |
questions.*.type | string | обязательно | noul, choice, score или box |
questions.*.instructions | string, object или array | обязательно | Сам вопрос |
questions.*.criteria | по типу | нет | Варианты, уровни шкалы или смысл «да» и «нет» |
assets | object | нет | Картинки по ключу: {"type": "image", "format": "png", "data_base64": "…"} |
Общие поля routing, routing_options, max_price_multiplier и store описаны в
Авто-роутинг. Ответ всегда синхронный, потока нет.
Типы вопросов
type | Вопрос | criteria | Ответ |
|---|---|---|---|
noul | Верно ли утверждение | Необязательно: {"true": "…", "false": "…"} | noul, вероятность «да» от 0 до 1 |
choice | Какой из вариантов | Объект от 1 до 255 вариантов: имя → описание или null | choice, confidence, probabilities |
score | Где на шкале | Массив от 1 до 10 уровней от низшего к высшему | score от 0 до n−1, confidence, legend, probabilities |
box | Где на картинке | Поля нет | box с top, bottom, left, right и confidence |
Какие типы принимает модель, указано в её карточке: params и input_schema. Тип box есть
не у всех моделей и требует картинку в запросе.
Картинки в решениях
Передайте картинку в assets под ключом и упомяните этот ключ в state или в вопросе.
Формат PNG или JPEG, байты в стандартном base64 без префикса data:.
{
"model": "jev-1.14",
"state": {"photo": "img-3f1c"},
"assets": {"img-3f1c": {"type": "image", "format": "png", "data_base64": "iVBORw0KGgo…"}},
"questions": {"product": {"type": "box", "instructions": "the product in img-3f1c"}}
}Ключ без упоминания получает 400. Сколько картинок принимает модель, указано в
limits.max_references карточки. Где модель читает ключ, указано в key_placement поля
assets в params. При state_item ключ должен стоять отдельным элементом массива state:
"state": ["Photo:", "img-3f1c"]. При anywhere ключ можно указать и внутри текста.
Размер картинки указан в min_side, max_side и max_pixels поля assets. Картинку вне этих
пределов мы масштабируем с сохранением пропорций. Рамка box задана долями ширины и высоты,
поэтому она относится и к исходной картинке. Слишком вытянутую картинку вписать нельзя, на неё
API отвечает 400 capability_mismatch с detail[].path вида assets.img-3f1c.
Ответ решений
{
"id": "job_1a2b…",
"model": "jev-1.14",
"channel": "blue",
"answers": {
"is_bug": {"type": "noul", "noul": 0.95},
"team": {"type": "choice", "choice": "payments", "confidence": 0.67,
"probabilities": {"payments": 0.78, "frontend": 0.22}}
},
"usage": {"input_tokens": 350, "output_tokens": 38, "cost": 2430, "currency": "RUB"}
}Оплачиваются только входные токены, выход бесплатен. usage.cost показывает списанное в
микроединицах; null значит, что цена ещё уточняется, итог появится в price задачи.
id открывает задачу в GET /v1/jobs/{id}. Некоторые модели считают state отдельно для
каждого вопроса, поэтому input_tokens растёт с числом вопросов.
Ошибки решений
| Код | Когда | Что делать |
|---|---|---|
400 invalid_request | Нет state или questions, тип вопроса неизвестен, criteria не по типу | Исправьте поле из detail[].path |
400 invalid_request | Ключ картинки не упомянут, формат не PNG или JPEG, base64 с префиксом | Исправьте assets |
400 invalid_request | Картинка частью state или вопроса ({"type": "image_url", …}) | Перенесите её в assets |
400 capability_mismatch | Модель не отвечает на box, не принимает картинки или столько вопросов | Возьмите модель по params карточки |
400 capability_mismatch | Картинку не вписать в min_side и max_side модели, detail[].path = assets.<ключ> | Обрежьте картинку ближе к квадрату |
400 capability_mismatch | state не помещается в limits.context_tokens модели, detail[].path = state | Сократите state или возьмите модель с окном больше |
400 invalid_request | Модель другой модальности (wrong_endpoint) | Отправьте запрос на адрес из detail[].allowed |
Остальные коды описаны в Ошибки.
Дальше
- Модели — типы вопросов и пределы в карточке.
- Цены и списание — оплата за входные токены.
- Повторы —
Idempotency-Keyдля безопасного повтора.