Премини към основното съдържание
Български— Изберете език
Меню

Поточно предаване на TTS чрез WebSocket

Урок 9 от 14 Обновен 3 ноември 2026 г. Средно
На тази страница
  1. Защо поточното предаване променя усещането
  2. Отваряне на връзката
  3. Протокол за съобщения
  4. Пълна реализация
  5. Лимити, които трябва да знаете
  6. HTTP или WebSocket
  7. Ключови изводи

Обновено на 3 ноември 2026 г., въз основа на страницата Text to Speech на xAI. Източник: Text to Speech.

Защо поточното предаване променя усещането

В режим HTTP, TTS връща контрола едва след като целият аудио файл е генериран. За известие от две изречения никой не забелязва чакането. За блог пост, глава от книга или непрекъснато зареждащ се новинарски поток обаче това чакане се превръща в най-големия недостатък на Вашия продукт: потребителите кликват, а след това гледат въртящ се индикатор за зареждане в продължение на няколко секунди.

Режимът WebSocket премахва това чакане, като изпраща аудиото веднага щом то се синтезира. Възпроизвеждането започва с първите думи, докато краят на текста все още не е обработен. Това е разликата между страница, която изглежда замръзнала, и аудио, което се възпроизвежда незабавно.

Отваряне на връзката

Връзката се осъществява към wss://api.x.ai/v1/tts, като цялата конфигурация се предава в низа със заявка (query string) на URL адреса, а не в съобщение за инициализация.

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3&sample_rate=24000",
  {
    headers: {
      "Authorization": "Bearer " + XAI_API_KEY
    }
  }
);

Ето кои параметри се приемат:

  • language (задължителен): код по BCP-47 или auto
  • voice (по желание, по подразбиране: eve): идентификатор на гласа
  • codec (по желание, по подразбиране: mp3): изходен аудио формат
  • sample_rate (по желание, по подразбиране: 24000): честота на дискретизация в Hz
  • bit_rate (по желание, по подразбиране: 128000): битрейт в bps (само за MP3)

Тези настройки важат за цялата сесия: не можете да променяте гласа или кодека по време на работа. Ако Вашето приложение трябва да редува двама разказвачи, отворете две отделни връзки.

Протокол за съобщения

От страна на изпращането са Ви необходими само два вида съобщения, за да управлявате синтеза. Първото изпраща част от текста; второто обявява, че текстът е завършен.

{ "type": "text.delta", "delta": "Hello and welcome " }
{ "type": "text.done" }

Можете да изпратите толкова съобщения text.delta, колкото е необходимо, като всяко от тях може да съдържа до 60 000 знака. Въпреки това е по-добре да не достигате този лимит: разделянето на текста на части от по няколко изречения Ви осигурява много по-бързо получаване на първия аудио фрагмент, което е и целта на поточното предаване. Едно единствено delta съобщение от няколко хиляди знака ще Ви върне към поведението на HTTP режима.

От страна на получаването всяко съобщение audio.delta носи фрагмент от аудио данни, кодирани в base64, във формата, който сте задали при свързването. Декодирайте го и го добавете към буфера си за възпроизвеждане.

{ "type": "audio.delta", "delta": "<base64 audio>" }
{ "type": "audio.done", "trace_id": "trace-uuid" }

Събитието audio.done маркира края на синтеза. Неговият trace_id е идентификаторът, който трябва да предоставите на екипа за поддръжка или да запишете във Вашите логове, ако генерирането не работи правилно. Ако текстът е невалиден или сте надвишили квотата си, вместо това ще получите съобщение за грешка.

{ "type": "error", "message": "description of the error" }

Пълна реализация

Примерът по-долу разделя дълъг текст на абзаци, изпраща ги всички и след това сглобява получените аудио фрагменти в MP3 файл.

const WebSocket = require("ws");
const fs = require("fs");

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
  { headers: { "Authorization": "Bearer " + process.env.XAI_API_KEY } }
);

const audioChunks = [];

ws.on("open", () => {
  const paragraphs = longText.split("\n\n");
  for (const para of paragraphs) {
    ws.send(JSON.stringify({
      type: "text.delta",
      delta: para + " "
    }));
  }
  ws.send(JSON.stringify({ type: "text.done" }));
});

ws.on("message", (data) => {
  const msg = JSON.parse(data);
  if (msg.type === "audio.delta") {
    audioChunks.push(Buffer.from(msg.delta, "base64"));
  } else if (msg.type === "audio.done") {
    fs.writeFileSync("output.mp3", Buffer.concat(audioChunks));
    ws.close();
  }
});

Обърнете внимание на para + " ": без тази интервал краят на един абзац се слива с началото на следващия и двигателят прочита двете думи заедно, без да си поеме дъх.

Лимити, които трябва да знаете

МетрикаСтойност
Текст на deltaмаксимум 60 000 знака
Общ текстНеограничен
Едновременни сесии50 на екип
Разрешение за сесия600 секунди
Таймаут на връзкатаНяма

Страницата на xAI посочва, че връзката няма таймаут, и отделно споменава „разрешение за сесия“ от 600 секунди, без да обяснява какво се случва, когато то изтече. За сигурност се свързвайте, когато имате текст за изпращане, а не когато страницата се зареди, и планирайте повторно свързване. Планирайте работата си и спрямо лимита от 50 едновременни сесии на екип по същия начин: аудио библиотека, която конвертира каталога си във фонов режим, трябва да поставя задачите си на опашка, вместо да отваря двеста връзки паралелно.

HTTP или WebSocket

Режимът HTTP все още е правилният избор за кратки текстове, еднократни генерации и навсякъде, където простотата на интеграцията е от първостепенно значение: една заявка, един отговор, без състояние за управление. WebSocket е правилният път, когато текстът стане дълъг, когато аудиото трябва да се възпроизвежда докато се генерира, или когато самото съдържание пристига като поток – типично output от езиков модел, който озвучавате докато генерира.

Ключови изводи

  • WebSocket TTS Ви позволява да получавате поточно аудио, без да чакате генерирането да приключи
  • Параметрите за конфигурация се предават в низа със заявка на URL адреса за връзка
  • Протоколът е прост: text.delta за изпращане на текст, audio.delta за получаване на аудио
  • WebSocket сесиите са ограничени до 50 едновременни на екип; планирайте повторно свързване
  • Предпочитайте WebSocket за дълги текстове и преживявания за слушане в реално време