> ## Documentation Index
> Fetch the complete documentation index at: https://polza.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# POST Systemone

> Ответы на типизированные вопросы к тексту — да/нет, выбор из вариантов, оценка по шкале — с вероятностями

Ручка модели [Jev](/docs/gaidy/jev): вы отправляете текст (`state`) и вопросы с известными вариантами ответа (`questions`) — получаете значения и вероятности, готовые для кода. Текст модель не генерирует.

<Note>
  Впервые видите Jev? Начните с гайда [«Решения вместо текста»](/docs/gaidy/jev): там объяснено, что это за модель, и разобран первый запрос.
</Note>

Контракт совпадает с [TypeSafe API](https://docs.typesafe.ai/api.md): официальные SDK TypeSafe работают со сменой адреса на `https://polza.ai/api` (без `/v1`) и ключом Polza.AI.

## Доступные модели

| Модель       | ID             | Также принимаются                         |
| ------------ | -------------- | ----------------------------------------- |
| TypeSafe Jev | `typesafe/jev` | `jev-latest`, `jev-preview`, `jev-1.13.0` |

## Параметры запроса

| Параметр    | Тип                     | Обязательный | Описание                                                                                         |
| ----------- | ----------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
| `model`     | string                  | Да           | ID модели                                                                                        |
| `state`     | string / object / array | Да           | Оцениваемый текст. До 400 000 символов                                                           |
| `questions` | object                  | Да           | Вопросы: ключ — имя вопроса (придумываете сами), значение — объект вопроса. От 1 до 256 вопросов |
| `provider`  | object                  | Нет          | [Выбор провайдера](/docs/gaidy/provider-selection)                                                    |

### Объект вопроса

| Поле           | Тип                     | Обязательный           | Описание                     |
| -------------- | ----------------------- | ---------------------- | ---------------------------- |
| `type`         | string                  | Да                     | `noul`, `choice` или `score` |
| `instructions` | string / object / array | Да                     | Сам вопрос                   |
| `criteria`     | зависит от типа         | Для `choice` и `score` | Варианты ответа              |

| `type`   | `criteria`                                                                       | Поля ответа                                      |
| -------- | -------------------------------------------------------------------------------- | ------------------------------------------------ |
| `noul`   | Необязательно: `{ "true": "...", "false": "..." }`                               | `noul` — вероятность «да», от 0 до 1             |
| `choice` | Объект `{ "вариант": "описание" }`; описание может быть `null`. До 255 вариантов | `choice`, `probabilities`, `confidence`          |
| `score`  | Массив описаний уровней по возрастанию, от 2 до 10                               | `score`, `legend`, `probabilities`, `confidence` |

Как формулировать вопросы и критерии — в гайде [«Как задавать вопросы»](/docs/gaidy/jev-questions).

## Пример

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://polza.ai/api/v1/systemone" \
    -H "Authorization: Bearer $POLZA_AI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "typesafe/jev",
      "state": "Кроссовки пришли не того размера. Можно обменять на 43-й? Это срочно, у меня соревнования в субботу.",
      "questions": {
        "is_urgent": {
          "type": "noul",
          "instructions": "Клиент сообщает о срочной проблеме?"
        },
        "department": {
          "type": "choice",
          "instructions": "Какая команда должна заняться обращением?",
          "criteria": {
            "returns": "Обмен, возврат, не тот или повреждённый товар",
            "shipping": "Статус доставки, задержки, потерянные посылки",
            "billing": "Списания, счета, проблемы с оплатой",
            "other": "Ничего из перечисленного"
          }
        }
      }
    }'
  ```

  ```typescript TypeScript theme={null}
  import { TypeSafeClient, choice, noul } from '@typesafe-ai/sdk';

  const client = new TypeSafeClient({
    baseURL: 'https://polza.ai/api',
    apiKey: '<POLZA_AI_API_KEY>',
    defaultModel: 'typesafe/jev',
  });

  const response = await client.systemOne({
    state: 'Кроссовки пришли не того размера. Можно обменять на 43-й? Это срочно, у меня соревнования в субботу.',
    questions: {
      is_urgent: noul('Клиент сообщает о срочной проблеме?'),
      department: choice('Какая команда должна заняться обращением?', {
        returns: 'Обмен, возврат, не тот или повреждённый товар',
        shipping: 'Статус доставки, задержки, потерянные посылки',
        billing: 'Списания, счета, проблемы с оплатой',
        other: 'Ничего из перечисленного',
      }),
    },
  });
  ```

  ```python Python theme={null}
  from typesafe_sdk import Choice, Noul, TypeSafeClient

  client = TypeSafeClient(
      base_url="https://polza.ai/api",
      api_key="<POLZA_AI_API_KEY>",
      model="typesafe/jev",
  )

  response = client.system_one(
      state="Кроссовки пришли не того размера. Можно обменять на 43-й? Это срочно, у меня соревнования в субботу.",
      questions={
          "is_urgent": Noul(instructions="Клиент сообщает о срочной проблеме?"),
          "department": Choice(
              instructions="Какая команда должна заняться обращением?",
              criteria={
                  "returns": "Обмен, возврат, не тот или повреждённый товар",
                  "shipping": "Статус доставки, задержки, потерянные посылки",
                  "billing": "Списания, счета, проблемы с оплатой",
                  "other": "Ничего из перечисленного",
              },
          ),
      },
  )
  ```
</CodeGroup>

## Ответ

```json theme={null}
{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": { "type": "noul", "noul": 0.97 },
    "department": {
      "type": "choice",
      "choice": "returns",
      "confidence": 1.0,
      "probabilities": { "returns": 1.0, "shipping": 0.0, "billing": 0.0, "other": 0.0 }
    }
  },
  "usage": { "input_tokens": 548, "output_tokens": 64, "cost_rub": 0.0115 }
}
```

| Поле                  | Описание                                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `model`               | Версия модели, которая ответила                                                                                 |
| `answers`             | Ответы под именами ваших вопросов                                                                               |
| `usage.input_tokens`  | Входные токены — тарифицируются только они                                                                      |
| `usage.output_tokens` | Выходные токены — бесплатны                                                                                     |
| `usage.cost_rub`      | Стоимость запроса в рублях. Python SDK TypeSafe это поле отбрасывает; в TypeScript SDK и в HTTP-ответе оно есть |

К каждому запросу провайдер добавляет около 280 служебных входных токенов, поэтому несколько вопросов выгоднее отправлять одним запросом.

## Ошибки

Ошибки приходят в [стандартном формате Polza.AI](/docs/api-reference/introduction#формат-ошибок) (`error.code`, `error.message`, `trace_id`). Дополнительно в поле `detail` дублируется форма TypeSafe — `{ "error_type", "message" }`.

| Статус | Когда                                                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Запрос не прошёл проверку — нашу или провайдера (у TypeSafe это `422`); превышен контекст модели; модель не поддерживает эту ручку |
| `401`  | Неверный API-ключ                                                                                                                  |
| `402`  | Недостаточно средств (`detail.error_type`: `insufficient_balance`)                                                                 |
| `429`  | Превышен лимит запросов. SDK TypeSafe повторяют запрос сами                                                                        |
| `503`  | Провайдер недоступен или перегружен                                                                                                |

Тексты запросов и ответов на стороне Polza.AI не сохраняются и не логируются.


## OpenAPI

````yaml POST /v1/systemone
openapi: 3.0.0
info:
  title: Polza.ai API
  description: AI агрегатор — унифицированный доступ к сотням AI моделей
  version: '1.0'
  contact: {}
servers:
  - url: https://polza.ai/api
    description: Production
security: []
tags: []
paths:
  /v1/systemone:
    post:
      tags:
        - Классификация и оценка
      summary: Ответить на типизированные вопросы к тексту
      operationId: SystemOneController_evaluate[1]
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemOneRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemOneResponsePresenter'
        '400':
          description: Некорректный запрос. Проверьте параметры и тело
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '401':
          description: Ошибка авторизации. Проверьте ключ доступа
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '402':
          description: Недостаточно средств или достигнут лимит
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '403':
          description: Ошибка доступа. Проверьте права доступа ключа
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '404':
          description: Ресурс не найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '408':
          description: Истекло время ожидания ответа. Повторите запрос
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '409':
          description: Конфликт состояния. Перечитайте ресурс и повторите запрос
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '413':
          description: Размер тела запроса превышает допустимый предел
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '429':
          description: Слишком много запросов. Повторите позже
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '500':
          description: Ошибка сервера. Обратитесь к поставщику услуг
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '502':
          description: Поставщик услуг вернул некорректный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
        '503':
          description: Сервис временно недоступен. Повторите позже
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPresenter'
      security:
        - bearer: []
components:
  schemas:
    SystemOneRequestDto:
      type: object
      properties:
        state:
          description: >-
            Оцениваемый текст: строка, объект с именованными полями или массив
            сообщений
          example:
            message: Помогите! Выплаты не проходят уже 3 дня.
            order_id: A-104
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
            - type: array
              items: {}
        model:
          type: string
          description: Идентификатор модели
          example: jev-latest
        questions:
          type: object
          description: >-
            Вопросы по вашим идентификаторам; ответы приходят под теми же
            ключами. Типы: noul (да/нет), choice (выбор из вариантов criteria),
            score (оценка по уровням criteria). До 256 вопросов в запросе
          example:
            is_urgent:
              type: noul
              instructions: Does this convey urgency?
            department:
              type: choice
              instructions: Which team should handle this?
              criteria:
                billing: Payments, refunds
                technical: Bugs, outages
            frustration:
              type: score
              instructions: How frustrated is the customer?
              criteria:
                - Calm
                - Angry
          additionalProperties:
            type: object
            required:
              - type
              - instructions
            properties:
              type:
                type: string
                enum:
                  - noul
                  - choice
                  - score
              instructions: {}
              criteria: {}
        provider:
          description: Ограничения выбора провайдера
          allOf:
            - $ref: '#/components/schemas/ProviderDto'
      required:
        - state
        - model
        - questions
    SystemOneResponsePresenter:
      type: object
      properties:
        model:
          type: string
          description: Версия модели, обработавшей запрос
          example: jev-1.13.0
        answers:
          type: object
          description: >-
            Ответы под идентификаторами вопросов. noul: { type, noul }; choice:
            { type, choice, probabilities, confidence }; score: { type, score,
            legend, probabilities, confidence }
          example:
            is_urgent:
              type: noul
              noul: 0.95
            department:
              type: choice
              choice: billing
              confidence: 0.9
              probabilities:
                billing: 0.94
                technical: 0.06
          additionalProperties:
            type: object
            additionalProperties: true
        usage:
          description: Использование токенов и стоимость
          allOf:
            - $ref: '#/components/schemas/SystemOneUsagePresenter'
      required:
        - model
        - answers
        - usage
    ApiErrorPresenter:
      type: object
      properties:
        error:
          description: Информация об ошибке
          allOf:
            - $ref: '#/components/schemas/ApiErrorBodyPresenter'
        trace_id:
          type: string
          description: ID трассировки запроса
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - error
    ProviderDto:
      type: object
      properties:
        require_parameters:
          type: boolean
          description: Требовать от OpenRouter поддержку всех переданных параметров
          example: true
        allow_fallbacks:
          type: boolean
          description: Разрешить использование резервных провайдеров
          example: true
        order:
          description: Упорядоченный список slug провайдеров для использования
          example:
            - OpenAI
            - Anthropic
          type: array
          items:
            type: string
        only:
          description: Список разрешенных slug провайдеров
          example:
            - OpenAI
            - Google
          type: array
          items:
            type: string
        ignore:
          description: Список игнорируемых slug провайдеров
          example:
            - DeepInfra
          type: array
          items:
            type: string
        sort:
          type: string
          description: Критерий сортировки провайдеров
          enum:
            - price
            - throughput
            - latency
          example: price
        max_price:
          description: Максимальные цены для запроса
          allOf:
            - $ref: '#/components/schemas/ProviderMaxPriceDto'
    SystemOneUsagePresenter:
      type: object
      properties:
        input_tokens:
          type: number
          description: Входные токены — только они тарифицируются
          example: 394
        output_tokens:
          type: number
          description: Выходные токены (бесплатны)
          example: 68
        cost_rub:
          type: object
          description: Стоимость запроса в рублях
          example: 0.0083
          nullable: true
      required:
        - input_tokens
        - output_tokens
    ApiErrorBodyPresenter:
      type: object
      properties:
        code:
          type: string
          description: Код ошибки
          enum:
            - BAD_REQUEST
            - UNAUTHORIZED
            - api_key_revoked
            - INSUFFICIENT_BALANCE
            - FORBIDDEN
            - NOT_FOUND
            - REQUEST_TIMEOUT
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - TOO_MANY_REQUESTS
            - BAD_GATEWAY
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
          example: BAD_REQUEST
        message:
          type: string
          description: Описание ошибки
          example: Недопустимое значение параметра
        trace_id:
          type: string
          description: ID трассировки запроса
          example: 550e8400-e29b-41d4-a716-446655440000
        details:
          type: object
          description: Уточняющие поля ошибки. Отдаются только для 4xx
          additionalProperties: true
        metadata:
          description: Метаданные ошибки провайдера
          allOf:
            - $ref: '#/components/schemas/ApiErrorMetadataPresenter'
      required:
        - code
        - message
    ProviderMaxPriceDto:
      type: object
      properties:
        prompt:
          type: number
          description: Максимальная цена за промпт токены (RUB за миллион токенов)
          example: 10
        completion:
          type: number
          description: Максимальная цена за completion токены (RUB за миллион токенов)
          example: 20
        image:
          type: number
          description: Максимальная цена за изображение (RUB за штуку)
          example: 5
        audio:
          type: number
          description: Максимальная цена за аудио (RUB за миллион токенов)
          example: 15
        request:
          type: number
          description: Максимальная цена за запрос (RUB за запрос)
          example: 1
        video_per_second:
          type: number
          description: Максимальная цена за секунду видео (RUB за секунду)
          example: 50
        stt_per_minute:
          type: number
          description: Максимальная цена распознавания речи (RUB за минуту)
          example: 5
        tts_per_million_characters:
          type: number
          description: Максимальная цена синтеза речи (RUB за миллион символов)
          example: 1500
    ApiErrorMetadataPresenter:
      type: object
      properties:
        reason:
          type: string
          description: 'Машинная причина отказа: по ней можно ветвиться, не разбирая текст'
          example: noProvidersForModel
        raw:
          type: string
          description: Исходный текст ответа провайдера
          example: The parameter `duration` specified in the request is not valid
        provider_name:
          type: string
          description: Провайдер, вернувший ошибку
          example: openrouter
        attempts:
          description: Кого перебрали, прежде чем отказать
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorAttemptPresenter'
    ApiErrorAttemptPresenter:
      type: object
      properties:
        provider:
          type: string
          description: Провайдер, к которому обращались
          example: OpenRouter
        reason:
          type: string
          description: Машинная причина отказа провайдера
          example: RATE_LIMIT
      required:
        - provider
        - reason
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API Key
      type: http
      description: >-
        API ключ передаётся в заголовке: Authorization: Bearer
        <POLZA_AI_API_KEY>

````