# Решения

`POST /v1/decisions` отвечает на типизированные вопросы о ваших данных вероятностями, а не
текстом. Используйте его для разметки, проверок и выбора ветки в коде. Формат совместим с
TypeSafe `POST /v1/systemone`: тот же запрос работает, если сменить адрес и ключ.

```bash tab="cURL"
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"]}
    }
  }'
```

```python tab="Python"
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"])
```

```ts tab="TypeScript"
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` описаны в
[Авто-роутинг](https://souz.ai/docs/routing.md). Ответ всегда синхронный, потока нет.

## Типы вопросов

| `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:`.

```json
{
  "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`.

## Ответ решений

```json
{
  "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` |

Остальные коды описаны в [Ошибки](https://souz.ai/docs/errors.md).

**Дальше**

- [Модели](https://souz.ai/docs/models.md) — типы вопросов и пределы в карточке.
- [Цены и списание](https://souz.ai/docs/pricing.md) — оплата за входные токены.
- [Повторы](https://souz.ai/docs/idempotency.md) — `Idempotency-Key` для безопасного повтора.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.
