Превратите речь в текст
Отправляйте аудио через соединение WebSocket и получайте обновления транскрипции. В этом первом примере читается запись, поэтому вы можете изучить процесс, не настраивая микрофон.
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-miniВпервые знакомы с речевыми API? Начните с этих четырех терминов.
- WebSocket
- Соединение, которое остается открытым, поэтому ваша программа и сервер могут обмениваться сообщениями в обоих направлениях.
- Модель
- Двигатель, выполняющий поставленную задачу. Используйте модель tts для речи и модель asr для расшифровки; скопируйте его точный публичный идентификатор.
- Аудиовход
- Запись для расшифровки. В этом примере используется моно, 24 кГц, 16-бит PCM. Python читает аудио из файла WAV; Node.js читает файл PCM без заголовка.
- Ключ 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 на веб-странице или в общедоступном репозитории. Выполнение примера приводит к вызову оплачиваемой модели.
Подготовьте короткую запись
Поместите input.wav в ту же папку: mono, 24,000 Hz, 16-bit PCM WAV, не менее 100 мс речи. Вы также можете использовать файл output.wav из примера синтеза и переименовать его в input.wav.
Если ваша запись использует другой формат, установите FFmpeg, замените recording.mp3 на имя файла, а затем преобразуйте его: FFmpeg ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
Сохраните пример и запустите его
Скопируйте полный пример ниже в новый текстовый файл с именем speech.py в этой папке. Сохраните его, затем запустите эту команду в том же терминале.
.venv/bin/python speech.py
Как выглядит успехТерминал может распечатать обновления «Частичное:», затем «Окончательное:», после чего следует завершенная транскрипция. Некоторые модели могут выдавать только конечный результат.
Полный пример
Скопируйте весь файл. Он подключается, настраивает сессию, отправляет один ввод, ждет завершения и закрывает соединение. Он не повторяет попытку автоматически.
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 перед отправкой ввода.
- Получать
session.createdСервер открыл сессию. Теперь вы можете отправить его конфигурацию.
- Отправлять
session.updateУстановите сеанс транскрипции, формат входного аудио, модель распознавания и обнаружение поворота.
- Получать
session.updatedСервер принял конфигурацию. Теперь отправьте ввод.
- Отправлять
input_audio_buffer.appendОтправьте Base64 PCM в поле аудио. В этом примере используются фрагменты байтов 4,800, эквивалентные 100 мс в настроенном формате.
- Отправлять
input_audio_buffer.commitЗавершите входной поворот. При использовании turn_detection=null вы должны явно зафиксировать; не отправлять ответ.создать для распознавания.
- Получать
conversation.item.input_audio_transcription.deltaСчитайте дельту и text_mode; обновите соответствующие item_id и content_index.
- Получать
conversation.item.input_audio_transcription.completedПоле транскрипта представляет собой авторитетный окончательный текст. Сохраните его, затем закройте этот однооборотный пример.
Проверьте сообщение session.update.
{
"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-miniAuthorizationstringНеобходимыйЗаголовок подключения: 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-minisession.audio.input.turn_detectionobject | nullНеобязательныйВ примере явно задается значение null, чтобы отключить автоматическое обнаружение поворота (VAD). Отправьте input_audio_buffer.commit, когда весь входной звук будет отправлен. Это выбранная настройка, а не утверждение о настройках сервера по умолчанию.
Пример/настройкаnullaudiostringНеобходимый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 ↗