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

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

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

Отправляйте аудио через соединение WebSocket и получайте обновления транскрипции. В этом первом примере читается запись, поэтому вы можете изучить процесс, не настраивая микрофон.

Идентификатор модели
АудиовходВывод текста
WSSwss://api.starsg.ai/v1/realtime?model=asr-altair-v1-mini
Впервые знакомы с речевыми API? Начните с этих четырех терминов.
WebSocket
Соединение, которое остается открытым, поэтому ваша программа и сервер могут обмениваться сообщениями в обоих направлениях.
Модель
Двигатель, выполняющий поставленную задачу. Используйте модель tts для речи и модель asr для расшифровки; скопируйте его точный публичный идентификатор.
Аудиовход
Запись для расшифровки. В этом примере используется моно, 24 кГц, 16-бит PCM. Python читает аудио из файла WAV; Node.js читает файл PCM без заголовка.
Ключ 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. Подготовьте короткую запись

    Поместите input.wav в ту же папку: mono, 24,000 Hz, 16-bit PCM WAV, не менее 100 мс речи. Вы также можете использовать файл output.wav из примера синтеза и переименовать его в input.wav.

    Если ваша запись использует другой формат, установите FFmpeg, замените recording.mp3 на имя файла, а затем преобразуйте его: FFmpeg ↗

    bash
    ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
  4. Сохраните пример и запустите его

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

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

    Терминал может распечатать обновления «Частичное:», затем «Окончательное:», после чего следует завершенная транскрипция. Некоторые модели могут выдавать только конечный результат.

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

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

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 = "asr-altair-v1-mini"
SESSION = json.loads("{\"type\":\"transcription\",\"audio\":{\"input\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000},\"transcription\":{\"model\":\"asr-altair-v1-mini\"},\"turn_detection\":null}}}")
with wave.open("input.wav", "rb") as source:
    if (source.getnchannels(), source.getsampwidth(),
        source.getframerate(), source.getcomptype()) != (1, 2, 24000, "NONE"):
        raise ValueError("Expected mono, 24 kHz, 16-bit PCM WAV")
    pcm = source.readframes(source.getnframes())
if len(pcm) < 4800:
    raise ValueError("Audio must be at least 100 ms")

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")
            for offset in range(0, len(pcm), 4800):
                await connection.input_audio_buffer.append(
                    audio=base64.b64encode(pcm[offset:offset + 4800]).decode()
                )
            await connection.input_audio_buffer.commit()
            transcripts = {}
            while True:
                event = await receive()
                kind = event["type"]
                item = (event.get("item_id"), event.get("content_index", 0))
                if kind == "conversation.item.input_audio_transcription.delta":
                    mode = event.get("text_mode", "snapshot")
                    if mode == "snapshot":
                        transcripts[item] = event["delta"]
                    elif mode == "append":
                        transcripts[item] = transcripts.get(item, "") + event["delta"]
                    else:
                        raise ValueError("Unknown text_mode: " + str(mode))
                    print("Partial:", transcripts[item])
                elif kind == "conversation.item.input_audio_transcription.completed":
                    if not event.get("transcript", "").strip():
                        raise ValueError("Empty final transcript")
                    print("Final:", event["transcript"])
                    return


async def run():
    await asyncio.wait_for(main(), timeout=90)


asyncio.run(run())

В примере используется общедоступный идентификатор модели. Доступность зависит от вашей учетной записи и среды; выберите модель, которая поддерживает эту задачу в реальном времени. Посмотреть модели ↗

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

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

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

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

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

    Установите сеанс транскрипции, формат входного аудио, модель распознавания и обнаружение поворота.

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

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

  4. Отправлять
    input_audio_buffer.append

    Отправьте Base64 PCM в поле аудио. В этом примере используются фрагменты байтов 4,800, эквивалентные 100 мс в настроенном формате.

  5. Отправлять
    input_audio_buffer.commit

    Завершите входной поворот. При использовании turn_detection=null вы должны явно зафиксировать; не отправлять ответ.создать для распознавания.

  6. Получать
    conversation.item.input_audio_transcription.delta

    Считайте дельту и text_mode; обновите соответствующие item_id и content_index.

  7. Получать
    conversation.item.input_audio_transcription.completed

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

Проверьте сообщение session.update.
json
{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "asr-altair-v1-mini"
        },
        "turn_detection": null
      }
    }
  }
}

Справочник параметров

Имена с точками показывают, где находится поле в объекте JSON. «Обязательно» ниже относится к рабочему процессу в этом руководстве. Расширенная поддержка и ограничения зависят от модели.

Подключение и аутентификация

modelstringНеобходимый

Обязательный параметр запроса в WebSocket URL. Используйте точный общедоступный идентификатор модели из каталога реального времени. Модели ASR и TTS не являются взаимозаменяемыми.

Пример/настройка asr-altair-v1-mini
AuthorizationstringНеобходимый

Заголовок подключения: Bearer, один пробел, затем ваш ключ API. Используйте ключ для целевой среды; не помещайте его в URL.

Пример/настройка Bearer <API_KEY>

Сессия и ввод

session.typestringНеобходимый

Используйте транскрипцию только для распознавания. Он возвращает текст без генерации голосового ответа помощника.

Пример/настройка "transcription"
session.audio.input.formatobjectНеобходимый

Конфигурация звука: тип audio/pcm, скорость 24000. В этом примере используются монофонические выборки со знаком 16 с прямым порядком байтов: 48,000 байт в секунду. Заголовки WAV не передаются через сокет.

Пример/настройка {"type":"audio/pcm","rate":24000}
session.audio.input.transcription.modelstringНеобходимый

Используйте тот же идентификатор общедоступной модели ASR, что и в запросе URL. Не заменяйте название модели вышестоящего поставщика.

Пример/настройка asr-altair-v1-mini
session.audio.input.turn_detectionobject | nullНеобязательный

В примере явно задается значение null, чтобы отключить автоматическое обнаружение поворота (VAD). Отправьте input_audio_buffer.commit, когда весь входной звук будет отправлен. Это выбранная настройка, а не утверждение о настройках сервера по умолчанию.

Пример/настройка null
audiostringНеобходимый

Base64-encoded необработанные байты PCM в input_audio_buffer.append. Отправьте не менее 100 мс в зафиксированном повороте. Это поле не может быть заменено MP3, заголовком WAV, именем файла или URL.

Поиск неисправностей

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

Команда не найдена или отсутствует модуль

Установите выбранную среду выполнения, снова откройте терминал и запустите команды установки в папке проекта. Для 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 мс речи. Python читает PCM WAV; Node.js читает PCM без заголовка. Преобразуйте запись с помощью приведенной выше команды, а не просто переименовывайте ее расширение.

Тайм-аут или соединение закрывается до завершения

Примеры прекращаются через 90 секунд. Попробуйте более короткий ввод и проверьте доступ к сети. Не считайте частичную расшифровку или частичную аудиозапись успехом. Прежде чем повторить попытку, проверьте, был ли выполнен предыдущий запрос, чтобы избежать дублирования вызовов.

Невозможно найти input.wav или input.pcm.

Сохраните запись рядом с примером и запустите команду из этой папки. Python использует input.wav; Node.js использует input.pcm. Окончательный текст появится после «Final:»; распознавание не создает аудиофайл.

Предыстория протокола: OpenAI WebSockets ↗