> ## 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.

# Транскрибация и диаризация

Этот API предоставляет удобный способ для автоматической транскрибации и диаризации аудио через облако Palatine Speech.
Поддерживаются такие задачи, как перевод аудио и видео в текст с таймкодами (транскрибация), а так же
сегментация по спикерам (диаризация), создание субтитров в формате SRT и VTT.

<Steps>
  <Step title="Загрузка файла">POST /do\_transcribe — отправьте аудио/видео файл</Step>
  <Step title="Получение task_id">API вернёт task\_id для отслеживания</Step>
  <Step title="Polling статуса">GET /task\_status/{task_id} — опрашивайте до получения результата</Step>
  <Step title="Скачивание результата (если нужен файл)">GET /download\_as\_file/{task_id} — экспорт в SRT, VTT, CSV, XLSX</Step>
  <Step title="Завершение">POST /task\_done/{task_id} — освободите ресурсы</Step>
</Steps>

***

### Транскрибация в формате OpenAI

Для получения результата в структуре, совместимой с OpenAI API.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.palatine.ru/api/v1",
        api_key="<YOUR_TOKEN>"
    )

    with open("audio.mp3", "rb") as f:
        result = client.audio.transcriptions.create(
            file=f,
            model="palatine_large_highspeed",
            # response_format="json" | "verbose_json" | "text" | "srt" | "vtt"
            # language="ru"  # опционально: указать язык аудио
        )

    print(result)
    ```
  </Tab>

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

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

| Модель                     | Описание                                     |
| -------------------------- | -------------------------------------------- |
| `palatine_large_highspeed` | Высокая точность, рекомендуется по умолчанию |
| `palatine_small`           | Быстрее, но менее точная                     |

Подробнее можно узнать в [документации OpenAI клиента](https://platform.openai.com/docs/api-reference/audio/createTranscription?lang=curl).

***

### Пример транскрибации с помощью polling API

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

<AccordionGroup>
  <Accordion title="Загрузка файла">
    Загрузите аудиофайл для получения текста.

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

        API_URL = "https://api.palatine.ru/api/v1/transcribe/do_transcribe"
        TOKEN = "<YOUR_TOKEN>"

        files = {"file": open("audio.mp3", "rb")}
        headers = {"Authorization": f"Bearer {TOKEN}"}
        params = {
            "model": "palatine_large_highspeed",  # или palatine_small
            "fast_inference": True  # ускоренный режим (по умолчанию включён)
        }

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

      <Tab title="cURL">
        ```bash theme={null}
        curl -X POST "https://api.palatine.ru/api/v1/transcribe/do_transcribe?model=palatine_large_highspeed&fast_inference=true" \
          -H "Authorization: Bearer <YOUR_TOKEN>" \
          -F "file=@audio.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/transcribe/task_status/{task_id}"
        headers = {"Authorization": f"Bearer {TOKEN}"}
        params = {"response_format": "json"}  # или "srt", "vtt"

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

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

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

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

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

    ```json theme={null}
    {
      "id": "ea7040ab-edbf-407f-9123-dc8033185a08",
      "created_at": "2025-08-26T20:47:17.856937Z",
      "data": {
        "duration": 16.431,
        "language": "ru",
        "text": "Говорит Москва, передаем сообщение ТАСС...",
        "segments": [
          {
            "id": 1,
            "start": 0.0,
            "end": 13.712,
            "text": " Говорит Москва, передаем сообщение ТАСС..."
          }
        ]
      },
      "status": "success",
      "error": null
    }
    ```

    <Tip>
      Параметр `response_format` поддерживает значения `json`, `srt` и `vtt` для получения результата в разных форматах.
    </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/transcribe/download_as_file/{task_id}"
        headers = {"Authorization": f"Bearer {TOKEN}"}
        params = {
            "file_format": "srt",    # srt, vtt, txt, csv, xlsx
            "export_type": "segments"  # segments или words (для csv/xlsx)
        }

        response = requests.get(API_URL, headers=headers, params=params)
        if response.ok:
            with open(f"transcription.{params['file_format']}", "wb") as f:
                f.write(response.content)
        ```
      </Tab>

      <Tab title="cURL">
        ```bash theme={null}
        curl "https://api.palatine.ru/api/v1/transcribe/download_as_file/{task_id}?file_format=srt" \
          -H "Authorization: Bearer <YOUR_TOKEN>" \
          -o transcription.srt
        ```
      </Tab>
    </Tabs>

    **Форматы файлов:**

    | Формат        | Описание                                                 |
    | ------------- | -------------------------------------------------------- |
    | `srt`, `vtt`  | Субтитры с таймкодами                                    |
    | `txt`         | Только текст                                             |
    | `csv`, `xlsx` | Таблица (параметр `export_type`: `segments` или `words`) |
  </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/transcribe/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/transcribe/task_done/{task_id}" \
          -H "Authorization: Bearer <YOUR_TOKEN>"
        ```
      </Tab>
    </Tabs>
  </Accordion>

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

***