Распознавание в реальном времени

Realtime API распознаёт речь в реальном времени. Вы открываете WebSocket-соединение, отправляете аудио в формате PCM чанками и получаете слова обратно, как только модель их распознала (задержку можно настроить от 80 до 960 мс).

Быстрый старт

Замените nx-XXXXXXXXXXXXXXXXXXXXXXXX на свой API-ключ.

import asyncio
import soundfile as sf
import numpy as np
from nexara import AsyncNexara

async def main():
    audio, sr = sf.read("call.wav", dtype="float32")   # любая частота из поддерживаемых
    pcm = (np.clip(audio, -1, 1) * 32767).astype("<i2").tobytes()

    async def chunks():
        step = int(sr * 0.1) * 2                       # 100 мс int16
        for offset in range(0, len(pcm), step):
            yield pcm[offset:offset + step]            # для живого аудио — с паузами

    client = AsyncNexara()  # ключ из переменной окружения NEXARA_API_KEY
    async with client.realtime.connect(sample_rate=sr, diarize=True) as session:
        async for event in session.stream(chunks()):
            first = event.words[0]
            print(f"spk{event.speaker} {first.start / 1000:6.2f}s {event.text}")
        print("Полный текст:", session.ended.text)

asyncio.run(main())

import { readFileSync } from "node:fs";
import { Nexara } from "nexara-sdk";

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

// call.pcm — сырой int16 LE, 16 кГц, моно (см. пример websocat ниже)
const pcm = readFileSync("call.pcm");
async function* chunks() {
  for (let offset = 0; offset < pcm.length; offset += 3200) {
    yield pcm.subarray(offset, offset + 3200); // 100 мс
  }
}

const session = await client.realtime.connect({ sampleRate: 16000, diarize: true });
for await (const event of session.stream(chunks())) {
  const first = event.words[0]!;
  console.log(`spk${event.speaker} ${(first.start / 1000).toFixed(2)}s ${event.text}`);
}
console.log("Полный текст:", session.ended?.text);

import asyncio, json
import numpy as np, soundfile as sf, websockets

async def transcribe(path, key):
    audio, sr = sf.read(path, dtype="float32")
    pcm = (np.clip(audio, -1, 1) * 32767).astype("<i2").tobytes()
    url = f"wss://streaming.nexara.ru/v1/transcribe?sample_rate={sr}&diarize=true"
    headers = {"Authorization": f"Bearer {key}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        print(await ws.recv())                            # session.created

        async def receive():
            async for raw in ws:
                ev = json.loads(raw)
                if ev["type"] == "transcript":
                    print(f"spk{ev.get('speaker')} {ev['words'][0]['start'] / 1000:7.2f}s {ev['text']}")
                elif ev["type"] == "session.ended":
                    print("Полный текст:", ev["text"])
                elif ev["type"] == "error":
                    print("Ошибка:", ev["code"], ev["message"])

        rx = asyncio.create_task(receive())
        chunk = int(sr * 0.1) * 2                          # 100 мс
        for off in range(0, len(pcm), chunk):
            await ws.send(pcm[off:off + chunk])           # для живого аудио — с паузами
        await ws.send(json.dumps({"type": "input_audio.end"}))
        await rx

asyncio.run(transcribe("call.wav", "nx-XXXXXXXXXXXXXXXXXXXXXXXX"))

const ctx = new AudioContext({ sampleRate: 16000 });
const url = `wss://streaming.nexara.ru/v1/transcribe?encoding=pcm_f32le&sample_rate=${ctx.sampleRate}`;
const ws = new WebSocket(url, ["nexara-key", apiKey]);
ws.binaryType = "arraybuffer";

ws.onmessage = (e) => {
  const ev = JSON.parse(e.data);
  if (ev.type === "transcript") transcriptEl.textContent += ev.text;
  if (ev.type === "session.ended") console.log("Готово:", ev.audio_duration_ms, "мс");
};
ws.onclose = (e) => console.log("Закрыто:", e.code, e.reason); // 1000 или код из таблицы ниже

// Захват: AudioWorklet, который отдаёт Float32-буферы по ~100 мс
node.port.onmessage = (e) => ws.readyState === 1 && ws.send(e.data);

// Остановка:
// ws.send(JSON.stringify({ type: "input_audio.end" }));

ffmpeg -i call.mp3 -f s16le -ac 1 -ar 16000 call.pcm

# аудио, затем 2 секунды тишины, чтобы модель отдала последние слова, затем EOF
( cat call.pcm; head -c 64000 /dev/zero ) | websocat -b \
  -H "Authorization: Bearer nx-XXXXXXXXXXXXXXXXXXXXXXXX" \
  "wss://streaming.nexara.ru/v1/transcribe?sample_rate=16000&diarize=true"

Подключение

GET wss://streaming.nexara.ru/v1/transcribe с WebSocket-апгрейдом. Параметры сессии передаются в строке запроса:

Неизвестный параметр или недопустимое значение сервер отклоняет: присылает событие error с кодом invalid_config и закрывает соединение с кодом 4000. Не рассчитывайте, что лишние параметры будут проигнорированы.

Те же параметры можно отправить текстовым сообщением session.update до первого куска аудио — сервер ответит session.updated в формате session.created. После начала аудио session.update отклоняется с invalid_config. Для большинства клиентов строка запроса проще.

Аутентификация

Ключ передаётся так же, как в REST API, — заголовком:

Authorization: Bearer nx-XXXXXXXXXXXXXXXXXXXXXXXX

Браузеры не умеют задавать заголовки у WebSocket. Передайте ключ в списке субпротоколов — сервер выберет nexara-key в качестве субпротокола соединения:

const ws = new WebSocket(url, ["nexara-key", "nx-XXXXXXXXXXXXXXXXXXXXXXXX"]);

В строке запроса ключ не принимается.

Ключ проверяется до апгрейда соединения, поэтому отказ приходит обычным HTTP-статусом, а сокет не открывается:

Первое сообщение

При успешном подключении первым всегда приходит session.created:

{
  "type": "session.created",
  "session_id": "ses_3e32dc553aca75d2",
  "model": "nexara-realtime",
  "delay_ms": 480,
  "audio": {
    "encoding": "pcm_s16le",
    "sample_rate": 16000,
    "channels": 1,
    "multichannel": false
  },
  "diarization": { "max_speakers": 4, "latency_ms": 1040 },
  "client_id": "my-app"
}

Объект diarization есть только при diarize=true, client_id — только если вы его передали.

Отправка аудио

Отправляйте бинарные WebSocket-фреймы с сырым PCM в объявленном формате. Подойдёт любой размер фрейма — от ~20 мс до 1 с аудио; 80 мс — хороший вариант по умолчанию. Фреймы не обязаны выравниваться по границам сэмплов: сэмпл может быть разрезан между двумя фреймами. Максимальный размер фрейма — 1 МиБ.

Для стерео чередуйте каналы посэмплово. При multichannel=false сервер усредняет каналы, при multichannel=true каждый канал распознаётся отдельно, и у каждого события появляется поле channel. Обратите внимание, что при использовании данного параметра каждый канал тарифицируется отдельно.

Служебные сообщения

Текстовые фреймы — это JSON с полем type:

{
  "type": "session.update",
  "sample_rate": 48000,
  "channels": 2,
  "multichannel": true
}

Те же ключи, что в строке запроса. Разрешено только до первого фрейма с аудио.

{ "type": "keepalive" }

Сбрасывает таймер простоя. Сессия без аудио и без keepalive в течение 30 секунд закрывается с idle_timeout (4008). Живому микрофону это не нужно; отправляйте keepalive, если ставите захват на паузу.

{ "type": "input_audio.end" }

Аудио больше не будет. Сервер распознаёт то, что у него накопилось, вытаскивает последние слова из линии задержки, присылает оставшиеся transcript, затем session.ended и закрывает соединение с кодом 1000. Пустой бинарный фрейм работает как синоним.

Получение результата

transcript

{
  "type": "transcript",
  "text": " Book me a table",
  "words": [
    { "text": "Book", "start": 12000, "end": 12160, "speaker": 1 },
    { "text": "me", "start": 12160, "end": 12240, "speaker": 1 },
    { "text": "table", "start": 12320, "end": 12480, "speaker": 1 }
  ],
  "speaker": 1,
  "channel": 0
}

• Финально. Текст никогда не пересматривается. Дописывайте text к транскрипции и не оглядывайтесь назад. Промежуточных результатов и флага is_final нет, потому что ничего не бывает «неокончательным».
• text — сырой вывод модели для этих слов, включая ведущий пробел, поэтому конкатенация text по всем событиям в точности воспроизводит транскрипцию. words[].text — без пробелов.
• words[].start и end — целые миллисекунды по часам аудио, то есть от первого отправленного сэмпла. Разрешение — 80 мс.
• Пунктуация прикреплена к предыдущему слову: "table.", а не отдельный элемент.
• speaker появляется у события и у каждого слова только при diarize=true. У всех слов одного события один спикер; смена спикера всегда начинает новое событие.
• channel появляется только при multichannel=true.
• turn появляется только при turn_detection=smart — номер реплики, к которой относятся слова.

Обычно в одном transcript одно слово, иногда несколько. События одной сессии приходят в порядке аудио.

session.ended

{
  "type": "session.ended",
  "audio_duration_ms": 61234,
  "channels_transcribed": 1,
  "billed_ms": 61234,
  "text": "Book me a table for two. ..."
}

Приходит после input_audio.end, когда всё распознано. text — полная транскрипция; при multichannel=true это массив с одной строкой на канал. audio_duration_ms считается по отправленным байтам, billed_ms — это audio_duration_ms, умноженное на channels_transcribed.

error

{ "type": "error", "code": "session_full", "message": "all slots are in use" }

За ним всегда следует закрытие соединения с соответствующим кодом. message — для людей, в коде ориентируйтесь на code.

Диаризация

При diarize=true у каждого слова есть поле speaker — целое число от 0 до 3 или null.

• Идентификаторы назначаются по порядку появления в сессии: спикер 0 — тот, кто заговорил первым. Между сессиями они ничего не значат.
• Максимум четыре спикера. Пятый будет отнесён к одному из существующих.
• null означает, что диаризатор оценил аудио этого слова как тишину, и никто не говорил в предыдущую секунду. Чаще всего это очень короткие слова в начале фразы после паузы. Считайте это «неизвестно», а не отдельным спикером.
• Слова придерживаются, пока спикер не определён, поэтому метки тоже финальные. Модель диаризации принимает решение каждые 1,04 секунды аудио, соответственно, при использовании диаризации рекомендуем использовать максимальную задержку на распознавание (960 мс), чтобы получить самое высокое качество распознавания.

При multichannel=true каждый канал диаризуется независимо, и идентификаторы спикеров локальны для канала: человека определяет пара (channel, speaker). Для телефонии, где на каждом канале один собеседник, диаризация не нужна — используйте channel как спикера.

Определение реплик

Голосовому агенту нужно знать не только что сказал пользователь, но и когда он закончил говорить. Параметр turn_detection=smart включает определение реплик: сервер сообщает, когда пользователь начал говорить, замолчал и когда его реплика закончена — вместе с её текстом.

wss://streaming.nexara.ru/v1/transcribe?turn_detection=smart

Или в session.update до первого фрейма аудио: {"type": "session.update", "turn_detection": "smart"}. Других параметров нет. Работает с любым delay_ms, с diarize=true и с multichannel=true (тогда у каждого события есть channel, а реплики нумеруются в каждом канале отдельно).

Добавляются три события, и у каждого transcript появляется поле turn. Все времена — целые миллисекунды по часам аудио, как у слов.

{ "type": "speech.started", "turn": 3, "start": 12340 }

{ "type": "speech.ended", "turn": 3, "end": 15200 }

{
  "type": "turn.end",
  "turn": 3,
  "start": 12340,
  "end": 15200,
  "confidence": 0.93,
  "text": "Book me a table for two tomorrow.",
  "words": [{ "text": "Book", "start": 12480, "end": 12560 }, ...]
}

{ "type": "transcript", "turn": 3, "text": " Book me", "words": [...] }

Как этим пользоваться:

• speech.started приходит примерно через 100 мс после того, как пользователь начал говорить. Используйте его, чтобы прервать агента. Может прийти раньше, чем turn.end предыдущей реплики, — номера turn их различают.
• speech.ended приходит примерно через 280 мс после того, как пользователь замолчал. Это «сейчас тишина», а не «реплика закончена»: speech.ended, за которым следует speech.started с тем же turn, — это пауза внутри реплики.
• turn.end — то, что нужно передать языковой модели. Порядок гарантирован в пределах канала: все transcript с turn: n приходят до turn.end для n, а все transcript с turn: n+1 — после него, так что text полон.

Задержка turn.end от момента, когда пользователь замолчал: около 720 мс при задержке выдачи 480 мс (p90 около 800), около 500 мс при 240, около 1200 мс при 960; около 1 с при 480 с diarize=true. Плюс сеть.

turn_detection с любым значением, кроме none и smart, отклоняется с invalid_config (код закрытия 4000) — так же, как smart на сервере, запущенном без определения реплик.

Задержка выдачи

delay_ms — сколько модель ждёт, прежде чем зафиксировать текст. Чем дольше ждет модель перед выдачей токена, тем точнее получается ответ. Допустимые значения задержки представлены в таблице с примерным Word Error Rate по записям:

Ошибки и коды закрытия

Сервер закрывает соединение с одним кодом на каждую причину. Клиентские библиотеки отдают его как код закрытия и строку причины.

Перед любым закрытием с кодом 4xxx или 1012 сервер отдаёт все финализированные слова, так что вы получили ровно то, за что заплатили. Переподключение — всегда новая сессия: идентификаторы спикеров начинаются с 0, возобновления нет.

Как эти ошибки выглядят в SDK — в разделах Python и TypeScript.

Лимиты

Тарификация

Сессия тарифицируется по отправленному аудио: billed_ms в session.ended — это audio_duration_ms, умноженное на число распознанных каналов. Стоимость минуты и надбавка за диаризацию — на странице тарифов.