> ## 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_diarize` (по умолчанию) | Диалоги, звонки и встречи | До 8; определяется автоматически |
| `palatine_diarize_multi` | Записи с большим числом участников или известным числом говорящих | Можно передать точное число или его границы; качество нужно проверить на ваших записях |

> [!NOTE]
>
> Если модель не указана или выбрано `auto`, используется `palatine_diarize`.
> Значение `auto` не выбирает другую модель при большем числе участников.

Модель `palatine_diarize_multi` позволяет указать точное число говорящих
(`num_speakers`) или его границы (`min_speakers`, `max_speakers`). Эти подсказки
влияют на обработку только у `palatine_diarize_multi`. Доступность модели зависит
от настроек вашего аккаунта; при отсутствии доступа API вернёт HTTP-статус `422`.

> [!WARNING]
>
> Стандартная модель `palatine_diarize` поддерживает до **8 говорящих**. Значение
> `max_speakers` больше 8 отклоняется с HTTP-статусом `422`. Подсказки числа говорящих
> не передаются этой модели при обработке: она определяет число самостоятельно.

## Входная запись

Загрузите запись в одном из [поддерживаемых аудио- или видеоформатов](https://docs2.speech.palatine.ru/documentation/technical_information/supported_files.md).
Предварительная конвертация не требуется: сервис сам подготавливает звук для обработки.

## Диаризация (только спикеры)

Разметка говорящих без распознавания текста доступна на
`/api/v1/diarization/do_diarize`. Обработка выполняется в фоне: первый ответ
содержит `task_id` — идентификатор задания. По нему запрашивайте статус до
завершения задания или ошибки.

В примерах замените `<API_KEY>` своим API-ключом, а `meeting.mp3` — путём к записи.

**1. Отправить файл**

> [tab] cURL
>
> ```bash theme={null}
> curl -X POST "https://api.palatine.ru/api/v1/diarization/do_diarize" \
>   -H "Authorization: Bearer <API_KEY>" \
>   -F "file=@meeting.mp3"
> # → {"status": "scheduled", "task_id": "..."}
> ```

> [tab] Python
>
> ```python theme={null}
> import requests
>
> with open("meeting.mp3", "rb") as audio:
>     response = requests.post(
>         "https://api.palatine.ru/api/v1/diarization/do_diarize",
>         headers={"Authorization": "Bearer <API_KEY>"},
>         files={"file": audio},
>     )
> response.raise_for_status()
> task_id = response.json()["task_id"]
> ```

**2. Получить результат**

```bash theme={null}
curl "https://api.palatine.ru/api/v1/diarization/task_status/<task_id>" \
  -H "Authorization: Bearer <API_KEY>"
```

В `data.segments` — интервалы речи с меткой говорящего (`SPEAKER_00`, `SPEAKER_01`, …).
Параметр `?merge_segments=true` объединяет соседние сегменты одного говорящего.
Подставьте полученный идентификатор вместо `<task_id>`.

Файл по ссылке (pre-signed S3 и т.п.) — те же параметры на `/diarization/do_diarize_by_url`
(передайте `source_url` в теле запроса).

## Текст и метки говорящих

Чтобы получить **текст и метки говорящих в одном результате**, добавьте параметр
`diarization_model=auto` к транскрипции на `/api/v1/transcribe/do_transcribe`.

> [tab] cURL
>
> ```bash theme={null}
> curl -X POST "https://api.palatine.ru/api/v1/transcribe/do_transcribe?diarization_model=auto" \
>   -H "Authorization: Bearer <API_KEY>" \
>   -F "file=@meeting.mp3"
> # → {"status": "scheduled", "task_id": "..."}
> ```

> [tab] Python
>
> ```python theme={null}
> import requests
>
> with open("meeting.mp3", "rb") as audio:
>     response = requests.post(
>         "https://api.palatine.ru/api/v1/transcribe/do_transcribe",
>         params={"diarization_model": "auto"},
>         headers={"Authorization": "Bearer <API_KEY>"},
>         files={"file": audio},
>     )
> response.raise_for_status()
> task_id = response.json()["task_id"]
> ```

Первый ответ содержит `task_id`. Для получения текста и меток говорящих
запрашивайте `/api/v1/transcribe/task_status/{task_id}` до завершения задания или
ошибки. Замените `{task_id}` полученным идентификатором.

Значения `diarization_model` и условия выбора описаны в [таблице моделей](#модели-диаризации).
**Без** параметра `diarization_model` эндпоинт распознаёт только текст, без меток
говорящих.

К распознаванию текста с метками говорящих можно подключить роли участников,
эмоции реплик и фильтр мата —
см. [Анализ звонка](https://docs2.speech.palatine.ru/documentation/quick_start/call_analytics.md).

> [!WARNING]
>
> Текст с метками говорящих тарифицируется как **две операции**: распознавание речи **и** диаризация.

### Формат ответа

`task_status` возвращает транскрипцию со спикерами:

```json theme={null}
{
  "status": "success",
  "data": {
    "text": "Добрый день, коллеги. ...",
    "language": "ru",
    "duration": 612.4,
    "segments": [
      { "id": 0, "speaker": "SPEAKER_00", "start": 0.6, "end": 8.9, "text": "Добрый день, коллеги." }
    ],
    "words": [
      { "word": " Добрый", "start": 0.6, "end": 1.1, "speaker": "SPEAKER_00",
        "confidence": 0.98, "speaker_confidence": 0.95 }
    ],
    "models": {
      "transcription": "palatine_large_highspeed",
      "diarization_requested": "auto",
      "diarization_resolved": "palatine_diarize"
    },
    "warnings": []
  }
}
```

| Поле | Значение |
| - | - |
| `segments[]` | Реплики, перегруппированные по смене говорящего |
| `words[]` | Слова с привязкой к говорящему |
| `words[].confidence` | Уверенность распознавания слова, `[0, 1]` |
| `words[].speaker_confidence` | Уверенность привязки к говорящему, `[0, 1]` |
| `models.diarization_resolved` | Фактически применённая модель диаризации |
| `warnings[]` | Предупреждения обработки (участки без надёжной привязки и т.п.) |

## Если доступна модель с подсказками числа говорящих

Если вашему аккаунту доступна `palatine_diarize_multi`, можно передать известное
число говорящих, например 8:

```bash theme={null}
curl -X POST "https://api.palatine.ru/api/v1/diarization/do_diarize?model=palatine_diarize_multi&num_speakers=8" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@meeting.mp3"
```

При распознавании текста с метками говорящих выберите эту модель через
`diarization_model=palatine_diarize_multi` и передайте `num_speakers` или границы
`min_speakers` / `max_speakers`. Эти параметры не включают доступ к модели сами по себе.

## OpenAI-совместимый эндпоинт

На `/api/v1/audio/transcriptions` текст с метками говорящих возвращается сразу
после обработки, без опроса статуса. Укажите `diarization_model=auto` и формат
ответа `diarized_json`:

```bash theme={null}
curl -X POST "https://api.palatine.ru/api/v1/audio/transcriptions" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@call.mp3" \
  -F "diarization_model=auto" \
  -F "response_format=diarized_json"
```

> [!NOTE]
>
> Синхронная обработка текста с метками говорящих ограничена по длительности аудио
> (до 30 минут). Для более длинных записей используйте асинхронный
> `/api/v1/transcribe/do_transcribe`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.