Документация API

WebSocketOpenAI-совместимые события

Превратите текст в речь

Отправляйте текст через соединение WebSocket и получайте аудио частями. Начните с полного примера, который сохраняет воспроизводимый файл WAV.

Идентификатор модели
Текст вАудиовыход
WSSwss://api.starsg.ai/v1/realtime?model=tts-altair-v1-mini
Впервые знакомы с речевыми API? Начните с этих четырех терминов.
WebSocket
Соединение, которое остается открытым, поэтому ваша программа и сервер могут обмениваться сообщениями в обоих направлениях.
Модель
Двигатель, выполняющий поставленную задачу. Используйте модель tts для речи и модель asr для расшифровки; скопируйте его точный публичный идентификатор.
Голос
Голос, используемый для синтеза. Выберите voice_id из каталога выбранной модели; для признания не нужен голос.
Ключ API
Ваши учетные данные доступа, созданные в консоли. Он попадает в заголовок Authorization при открытии соединения.

Ваше первое соединение

Выберите метод интеграции и среду, а затем выполните следующие действия.

  1. Подготовьте папку и установите библиотеку

    Используйте Python 3.10 или более позднюю версию. Откройте терминал в пустой папке и установите официальную OpenAI SDK. Он подключается к речевому шлюзу через WebSocket; пример был протестирован с версией ниже. Скачать ↗

    bash
    python3 -m venv .venv
    .venv/bin/python -m pip install "openai[realtime]==3.35.1"
  2. Установите ключ API

    Создайте ключ в консоли, затем замените YOUR_API_KEY ниже своим собственным ключом. Запустите это в том же терминале, что и в примере. Управление ключами API ↗

    bash
    export STARSG_API_KEY="YOUR_API_KEY"

    Держите свой ключ в тайне. Это локальные/серверные примеры, а не код браузера. Не размещайте постоянный ключ API на веб-странице или в общедоступном репозитории. Выполнение примера приводит к вызову оплачиваемой модели.

  3. Сохраните пример и запустите его

    Скопируйте полный пример ниже в новый текстовый файл с именем speech.py в этой папке. Сохраните его, затем запустите эту команду в том же терминале.

    bash
    .venv/bin/python speech.py
    Как выглядит успех

    Терминал печатает «Сохранено:» и создает файл output.wav. Откройте его с помощью аудиоплеера. Чтобы запустить снова, сначала переименуйте или удалите этот файл; пример не перезапишет его.

Полный пример

Скопируйте весь файл. Он подключается, настраивает сессию, отправляет один ввод, ждет завершения и закрывает соединение. Он не повторяет попытку автоматически.

python
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 ниже значением из этого каталога.

bash
export SPEECH_VOICE="VOICE_ID"

Поток событий

Каждое сообщение представляет собой событие JSON. Отправить означает вашу программу → сервер; получение означает сервер → ваша программа. Дождитесь session.updated перед отправкой ввода.

  1. Получать
    session.created

    Сервер открыл сессию. Теперь вы можете отправить его конфигурацию.

  2. Отправлять
    session.update

    Установите задачу, аудиоформат и дополнительный голос.

  3. Получать
    session.updated

    Сервер принял конфигурацию. Теперь отправьте ввод.

  4. Отправлять
    conversation.item.create

    Создайте сообщение пользователя с content.type=input_text и content.text, содержащим ваш текст.

  5. Отправлять
    response.create

    Попросите сервер сгенерировать аудио для текста.

  6. Получать
    response.output_audio.delta

    Декодируйте дельта-поле Base64 и соберите байты PCM по порядку. Эти фрагменты не являются отдельными файлами WAV.

  7. Получать
    response.done

    Проверьте ответ.статус завершен, затем добавьте заголовок WAV и сохраните собранный звук. Остальные статусы являются неудачными.

Проверьте сообщение session.update.
json
{
  "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-mini
AuthorizationstringНеобходимый

Заголовок подключения: 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.0
session.audio.output.options.volumenumber | nullНеобязательный

Расширение платформы в опциях: множитель усиления, нейтральное значение 1.0. Диапазон протокола: 0 < объем ≤ 10, но модель должна его поддерживать. Опущенный или нулевой использует нейтральное значение; неподдерживаемые значения отклоняются.

По умолчанию/опущено 1.0
session.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 ↗