Превратите текст в речь
Отправляйте текст через соединение WebSocket и получайте аудио частями. Начните с полного примера, который сохраняет воспроизводимый файл WAV.
wss://api.starsg.ai/v1/realtime?model=tts-altair-v1-miniВпервые знакомы с речевыми API? Начните с этих четырех терминов.
- WebSocket
- Соединение, которое остается открытым, поэтому ваша программа и сервер могут обмениваться сообщениями в обоих направлениях.
- Модель
- Двигатель, выполняющий поставленную задачу. Используйте модель tts для речи и модель asr для расшифровки; скопируйте его точный публичный идентификатор.
- Голос
- Голос, используемый для синтеза. Выберите voice_id из каталога выбранной модели; для признания не нужен голос.
- Ключ API
- Ваши учетные данные доступа, созданные в консоли. Он попадает в заголовок Authorization при открытии соединения.
Ваше первое соединение
Выберите метод интеграции и среду, а затем выполните следующие действия.
Подготовьте папку и установите библиотеку
Используйте Python 3.10 или более позднюю версию. Откройте терминал в пустой папке и установите официальную OpenAI SDK. Он подключается к речевому шлюзу через WebSocket; пример был протестирован с версией ниже. Скачать ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
Установите ключ API
Создайте ключ в консоли, затем замените YOUR_API_KEY ниже своим собственным ключом. Запустите это в том же терминале, что и в примере. Управление ключами API ↗
export STARSG_API_KEY="YOUR_API_KEY"
Держите свой ключ в тайне. Это локальные/серверные примеры, а не код браузера. Не размещайте постоянный ключ API на веб-странице или в общедоступном репозитории. Выполнение примера приводит к вызову оплачиваемой модели.
Сохраните пример и запустите его
Скопируйте полный пример ниже в новый текстовый файл с именем speech.py в этой папке. Сохраните его, затем запустите эту команду в том же терминале.
.venv/bin/python speech.py
Как выглядит успехТерминал печатает «Сохранено:» и создает файл output.wav. Откройте его с помощью аудиоплеера. Чтобы запустить снова, сначала переименуйте или удалите этот файл; пример не перезапишет его.
Полный пример
Скопируйте весь файл. Он подключается, настраивает сессию, отправляет один ввод, ждет завершения и закрывает соединение. Он не повторяет попытку автоматически.
import asyncio
import base64
import json
import os
from pathlib import Path
import wave
from openai import AsyncOpenAI
API_KEY = os.environ["STARSG_API_KEY"]
BASE_URL = "https://api.starsg.ai/v1"
MODEL = "tts-altair-v1-mini"
SESSION = json.loads("{\"type\":\"realtime\",\"output_modalities\":[\"audio\"],\"audio\":{\"output\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000}}}}")
TEXT = "Привет! Это мой первый пример синтеза речи."
OUTPUT = Path("output.wav")
if OUTPUT.exists():
raise FileExistsError("output.wav exists; rename it before running again")
voice = os.environ.get("SPEECH_VOICE")
if voice:
SESSION["audio"]["output"]["voice"] = voice
async def main():
async with AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL,
max_retries=0) as client:
async with client.realtime.connect(model=MODEL) as connection:
async def receive():
event = (await connection.recv()).model_dump()
if event["type"] == "error" or event["type"].endswith(".failed"):
raise RuntimeError(json.dumps(event.get("error", event), ensure_ascii=False))
return event
async def wait_for(kind):
while True:
event = await receive()
if event["type"] == kind:
return event
await wait_for("session.created")
await connection.session.update(session=SESSION)
await wait_for("session.updated")
await connection.conversation.item.create(item={
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": TEXT}]
})
await connection.response.create()
audio = bytearray()
while True:
event = await receive()
if event["type"] == "response.output_audio.delta":
audio.extend(base64.b64decode(event["delta"], validate=True))
elif event["type"] == "response.done":
if event.get("response", {}).get("status") != "completed":
raise RuntimeError("Audio generation did not complete")
if not audio or len(audio) % 2:
raise ValueError("No valid PCM audio received")
with OUTPUT.open("xb") as target:
with wave.open(target, "wb") as wav:
wav.setparams((1, 2, 24000, 0, "NONE", "not compressed"))
wav.writeframes(audio)
print("Saved:", OUTPUT.resolve())
return
async def run():
await asyncio.wait_for(main(), timeout=90)
asyncio.run(run())
В примере используется общедоступный идентификатор модели. Доступность зависит от вашей учетной записи и среды; выберите модель, которая поддерживает эту задачу в реальном времени. Посмотреть модели ↗
Чтобы выбрать голос, найдите его voice_id в голосовом каталоге этой модели и перед запуском установите SPEECH_VOICE в своем терминале. Опустите его, чтобы использовать голос по умолчанию. Отображаемое имя, например «Alloy», не является voice_id. Замените VOICE_ID ниже значением из этого каталога.
export SPEECH_VOICE="VOICE_ID"
Поток событий
Каждое сообщение представляет собой событие JSON. Отправить означает вашу программу → сервер; получение означает сервер → ваша программа. Дождитесь session.updated перед отправкой ввода.
- Получать
session.createdСервер открыл сессию. Теперь вы можете отправить его конфигурацию.
- Отправлять
session.updateУстановите задачу, аудиоформат и дополнительный голос.
- Получать
session.updatedСервер принял конфигурацию. Теперь отправьте ввод.
- Отправлять
conversation.item.createСоздайте сообщение пользователя с content.type=input_text и content.text, содержащим ваш текст.
- Отправлять
response.createПопросите сервер сгенерировать аудио для текста.
- Получать
response.output_audio.deltaДекодируйте дельта-поле Base64 и соберите байты PCM по порядку. Эти фрагменты не являются отдельными файлами WAV.
- Получать
response.doneПроверьте ответ.статус завершен, затем добавьте заголовок WAV и сохраните собранный звук. Остальные статусы являются неудачными.
Проверьте сообщение session.update.
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}Справочник параметров
Имена с точками показывают, где находится поле в объекте JSON. «Обязательно» ниже относится к рабочему процессу в этом руководстве. Расширенная поддержка и ограничения зависят от модели.
Подключение и аутентификация
modelstringНеобходимыйОбязательный параметр запроса в WebSocket URL. Используйте точный общедоступный идентификатор модели из каталога реального времени. Модели ASR и TTS не являются взаимозаменяемыми.
Пример/настройкаtts-altair-v1-miniAuthorizationstringНеобходимыйЗаголовок подключения: Bearer, один пробел, затем ваш ключ API. Используйте ключ для целевой среды; не помещайте его в URL.
Пример/настройкаBearer <API_KEY>
Сессия и ввод
session.typestringНеобходимыйИспользуйте режим реального времени для сеанса преобразования текста в речь. Это рабочий процесс синтеза, а не общий разговор с голосовым агентом.
Пример/настройка"realtime"session.output_modalitiesstring[]НеобходимыйЗапросить аудиовыход для синтеза. Отправьте этот массив в session.update.
Пример/настройка["audio"]session.audio.output.formatobjectНеобходимыйКонфигурация звука: тип audio/pcm, скорость 24000. В этом примере используются монофонические выборки со знаком 16 с прямым порядком байтов: 48,000 байт в секунду. Заголовки WAV не передаются через сокет.
Пример/настройка{"type":"audio/pcm","rate":24000}session.audio.output.voicestringНеобязательныйДополнительный voice_id из голосового каталога выбранной модели. Это ограничено моделью. Опустите его для сервера по умолчанию; не используйте отображаемое имя поставщика. Установите его до начала вывода звука.
Просмотр голосовПо умолчанию/опущено Голос модели по умолчаниюitem.content[].textstringНеобходимыйТекст для синтеза внутри разговора.item.create → item → content. Установите тип элемента контента на input_text, item.type на message и item.role на user. Ограничения на текст зависят от модели.
Дополнительное голосовое управление
Начните без этих элементов управления. Прежде чем добавлять их, проверьте output_controls модели. Неподдерживаемые значения громкости или высоты тона вызывают ошибку; их не игнорируют молча. Блокировка голоса и скорости после первого аудиовыхода; громкость и высота звука могут быть обновлены позже.
session.audio.output.speednumberНеобязательныйМножитель скорости речи: 1.0 — нормальная скорость. Принятые мин/макс значения зависят от модели; проверьте каталог. Установите его перед первым выходным звуком.
Пример/настройка1.0session.audio.output.options.volumenumber | nullНеобязательныйРасширение платформы в опциях: множитель усиления, нейтральное значение 1.0. Диапазон протокола: 0 < объем ≤ 10, но модель должна его поддерживать. Опущенный или нулевой использует нейтральное значение; неподдерживаемые значения отклоняются.
По умолчанию/опущено1.0session.audio.output.options.pitchnumber | nullНеобязательныйРасширение платформы в опциях: сдвиг высоты звука в полутонах, нейтральное значение 0. Диапазон внешнего протокола: от 24 до 24; модель может позволить меньше. Используйте заявленные ограничения. Если значение опущено или равно нулю, используется нейтральный тон.
По умолчанию/опущено0
Поиск неисправностей
Сначала прочитайте возвращенное сообщение об ошибке. Открытие соединения или поступление аудиофрагмента не означает, что запрос выполнен успешно.
Команда не найдена или отсутствует модуль
Установите выбранную среду выполнения, снова откройте терминал и запустите команды установки в папке проекта. Для Python используйте интерпретатор .venv, показанный выше; установите websocket-client, а не пакет websocket с аналогичным названием. В примерах Node.js используется пакет ws и файл .mjs.
401 / 403 или отсутствует ключ API
Убедитесь, что в этом терминале установлена переменная среды, YOUR_API_KEY заменен и ключ принадлежит целевой среде. Подтвердите доступ к модели и статус учетной записи. Не допускайте попадания ключа на скриншоты и журналы.
Не удалось установить соединение, 404/503 или модель не найдена.
Проверьте имя хоста WSS, порт, путь /v1/realtime и точный общедоступный идентификатор модели. Используйте каталог моделей реального времени для целевой среды. Не следуйте перенаправлению на небезопасный HTTP URL. 503 может потребовать от оператора службы проверить доступность.
Нет расшифровки, неверный звук или искаженное воспроизведение.
Проверьте 24 кГц, моно, 16-битный PCM с прямым порядком байтов и не менее 100 мс речи. Используйте команду преобразования вместо переименования файла. При распознавании отправляется необработанный PCM, а не заголовок WAV. Для синтеза декодируйте Base64 и соедините фрагменты PCM перед созданием файла WAV.
invalid_value или неподдерживаемый элемент управления
Удалите дополнительные настройки скорости, громкости и высоты тона, затем проверьте output_controls для выбранной модели. Не используйте повторно voice_id или числовые ограничения другой модели. Отклоненный файл session.update не применяет эту конфигурацию.
Тайм-аут или соединение закрывается до завершения
Примеры прекращаются через 90 секунд. Попробуйте более короткий ввод и проверьте доступ к сети. Не считайте частичную расшифровку или частичную аудиозапись успехом. Прежде чем повторить попытку, проверьте, был ли выполнен предыдущий запрос, чтобы избежать дублирования вызовов.
output.wav уже существует или входной файл отсутствует
Запустите скрипт из папки, содержащей Speech.py или Speech.mjs. Поместите туда input.wav (Python) или input.pcm (Node.js). Переименуйте предыдущий файл output.wav перед повторной генерацией. Строка «Final:» — результат распознавания; он не создает аудиофайл.
Предыстория протокола: OpenAI WebSockets ↗