> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.speech.palatine.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Анализ тональности речи

Palatine Speech позволяет определить эмоциональную окраску речи в аудио и видео.
Сервис агрегирует вероятности по классам тональности (Very Negative, Negative, Neutral, Positive, Very Positive) и выдаёт результат в удобном JSON.
Классы всегда отсортированы по убыванию вероятности: первый элемент — наиболее вероятная тональность.

<Steps>
  <Step title="Создание задачи">POST /analyze\_file — отправьте аудио/видео файл</Step>
  <Step title="Получение task_id">API вернёт task\_id для отслеживания</Step>
  <Step title="Polling статуса">GET /task\_status/{task_id} — опрашивайте до получения результата</Step>
  <Step title="Завершение">POST /task\_done/{task_id} — освободите ресурсы</Step>
</Steps>

***

### Анализ тональности через polling API

<Note>
  Все запросы требуют авторизации через токен в заголовке: `Authorization: Bearer <ваш_токен>`
</Note>

<AccordionGroup>
  <Accordion title="Создание задачи">
    Отправьте аудио/видео файл на эндпоинт `POST /sentiment_analysis/analyze_file`.

    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        import requests

        API_URL = "https://api.palatine.ru/api/v1/sentiment_analysis/analyze_file"
        TOKEN = "<YOUR_TOKEN>"
        headers = {"Authorization": f"Bearer {TOKEN}"}

        files = {"file": open("call.mp3", "rb")}
        response = requests.post(API_URL, files=files, headers=headers)

        print(response.json())
        ```
      </Tab>

      <Tab title="cURL">
        ```bash theme={null}
        curl -X POST "https://api.palatine.ru/api/v1/sentiment_analysis/analyze_file" \
          -H "Authorization: Bearer <YOUR_TOKEN>" \
          -F "file=@call.mp3"
        ```
      </Tab>
    </Tabs>

    Пример ответа:

    ```json theme={null}
    {
      "status": "scheduled",
      "task_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
    ```
  </Accordion>

  <Accordion title="Проверка статуса задачи">
    Получить статус асинхронной задачи и результат анализа.

    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        import requests

        task_id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        API_URL = f"https://api.palatine.ru/api/v1/sentiment_analysis/task_status/{task_id}"
        headers = {"Authorization": f"Bearer {TOKEN}"}

        response = requests.get(API_URL, headers=headers)
        print(response.json())
        ```
      </Tab>

      <Tab title="cURL">
        ```bash theme={null}
        curl "https://api.palatine.ru/api/v1/sentiment_analysis/task_status/{task_id}" \
          -H "Authorization: Bearer <YOUR_TOKEN>"
        ```
      </Tab>
    </Tabs>

    **Статусы задачи:**

    * `success` — задача выполнена успешно
    * `pending` — задача ещё в процессе выполнения
    * `error` — при выполнении задачи произошла ошибка

    Пример успешного ответа:

    ```json theme={null}
    {
      "id": "b9fcc4dd-0fb8-4900-b7f7-e6ac2a90cbe5",
      "created_at": "2025-08-26T20:47:17.856937Z",
      "data": {
        "sentiment": [
          {"label": "Very Positive", "score": 0.85},
          {"label": "Positive", "score": 0.08},
          {"label": "Neutral", "score": 0.04},
          {"label": "Negative", "score": 0.02},
          {"label": "Very Negative", "score": 0.01}
        ]
      },
      "status": "success",
      "error": null
    }
    ```

    <Tip>
      Список `sentiment` отсортирован по убыванию вероятности — первый элемент соответствует наиболее вероятной тональности. Значения `score` представляют уверенность модели для каждого класса.
    </Tip>
  </Accordion>

  <Accordion title="Завершение задачи">
    После получения результата пометьте задачу завершённой, чтобы освободить ресурсы.

    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        import requests

        task_id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        API_URL = f"https://api.palatine.ru/api/v1/sentiment_analysis/task_done/{task_id}"
        headers = {"Authorization": f"Bearer {TOKEN}"}

        response = requests.post(API_URL, headers=headers)
        print(response.json())
        ```
      </Tab>

      <Tab title="cURL">
        ```bash theme={null}
        curl -X POST "https://api.palatine.ru/api/v1/sentiment_analysis/task_done/{task_id}" \
          -H "Authorization: Bearer <YOUR_TOKEN>"
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Обработка ошибок">
    | HTTP код | Описание                         | Решение                                      |
    | -------- | -------------------------------- | -------------------------------------------- |
    | 401      | Неверный или отсутствующий токен | Проверьте токен авторизации                  |
    | 404      | Задача не найдена                | Проверьте task\_id или создайте новую задачу |
    | 500      | Внутренняя ошибка сервера        | Повторите запрос или обратитесь в поддержку  |

    **Ошибки в поле `error` ответа:**

    | Сообщение              | Причина                         | Решение                         |
    | ---------------------- | ------------------------------- | ------------------------------- |
    | No recognizable speech | В аудио нет распознаваемой речи | Используйте файл с чёткой речью |
    | Not enough balance     | Недостаточно средств на балансе | Пополните баланс                |
  </Accordion>
</AccordionGroup>

***