Синхронная и асинхронная обработка

Nexara API предлагает два режима обработки аудио. Они принимают одни и те же параметры, но по-разному возвращают результат: синхронный режим возвращает готовую транскрипцию прямо в ответе, держа соединение открытым все время обработки, а асинхронный — сразу возвращает идентификатор задачи, результат которой вы забираете позже.

Синхронная обработка

Отправьте аудио на POST /v1/audio/transcriptions. Соединение удерживается до конца обработки, после чего в ответе возвращается готовый текст.

from nexara import Nexara

client = Nexara()  # ключ из переменной окружения NEXARA_API_KEY

result = client.transcriptions.create(file="audio.mp3")
print(result.text)

import { Nexara } from "nexara-sdk";

const client = new Nexara(); // ключ из переменной окружения NEXARA_API_KEY

const result = await client.transcriptions.create({ file: "audio.mp3" });
console.log(result.text);

curl https://api.nexara.ru/v1/audio/transcriptions \
  -H "Authorization: Bearer nx-XXXXXXXXXXXXXXXXXXXXXXXX" \
  -F "file=@audio.mp3" \
  -F "model=whisper-1"

Ответ содержит результат сразу:

{
  "text": "Привет! Это пример транскрибации."
}

Синхронный режим — это самый простой способ использовать API: один запрос, один ответ. Он оптимален для коротких записей, где время обработки невелико.

Асинхронная обработка

Асинхронный режим разбивает работу на два шага: постановку задачи и получение результата.

Шаг 1. Поставить задачу

Отправьте аудио на POST /v1/audio/transcriptions/async. Запрос принимает те же параметры, что и синхронный, но возвращается сразу, не дожидаясь обработки.

job = client.transcriptions.create_job(file="long-audio.mp3")
print(job.job_id, job.status)  # 5f1c2e3a-... in_progress

const job = await client.transcriptions.createJob({ file: "long-audio.mp3" });
console.log(job.job_id, job.status); // 5f1c2e3a-... in_progress

curl https://api.nexara.ru/v1/audio/transcriptions/async \
  -H "Authorization: Bearer nx-XXXXXXXXXXXXXXXXXXXXXXXX" \
  -F "file=@long-audio.mp3" \
  -F "model=whisper-1"

В ответ приходит идентификатор задачи и её статус:

{
  "job_id": "5f1c2e3a-...",
  "status": "in_progress",
  "created_at": "2026-07-13T10:00:00+00:00"
}

Сохраните job_id — по нему вы будете забирать результат.

Шаг 2. Опросить статус

Отправляйте запросы на GET /v1/audio/transcriptions/async/{job_id}, пока задача не завершится.

result = job.wait()
print(result.text)

const result = await job.wait();
console.log((result as { text: string }).text);

curl https://api.nexara.ru/v1/audio/transcriptions/async/5f1c2e3a-... \
  -H "Authorization: Bearer nx-XXXXXXXXXXXXXXXXXXXXXXXX"

Так выглядит ответ API пока задача выполняется:

{
  "job_id": "5f1c2e3a-...",
  "status": "in_progress",
  "created_at": "2026-07-13T10:00:00+00:00",
  "completed_at": null,
  "result": null,
  "error": null
}

А так — когда ответ получен:

{
  "job_id": "5f1c2e3a-...",
  "status": "complete",
  "created_at": "2026-07-13T10:00:00+00:00",
  "completed_at": "2026-07-13T10:01:12+00:00",
  "result": {
    "text": "Привет! Это пример транскрибации."
  },
  "error": null
}

После завершения в поле result появляется готовый текст расшифровки. Поле result может содержать любые форматы ответа.

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

• in_progress: задача поставлена в очередь или обрабатывается. Поле result пустое;
• complete: обработка завершена успешно. Результат находится в поле result, а время завершения — в completed_at.
• error: обработка завершилась ошибкой. Описание причины находится в поле error.

Что выбрать