Convierte la voz en texto
Envíe audio a través de una conexión WebSocket y reciba actualizaciones de transcripción. Este primer ejemplo lee una grabación para que puedas aprender el flujo sin configurar un micrófono.
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-mini¿Nuevo en las API de voz? Comience con estos cuatro términos.
- WebSocket
- Una conexión que permanece abierta para que su programa y el servidor puedan intercambiar mensajes en ambas direcciones.
- Modelo
- El motor que realiza la tarea. Utilice un modelo tts para hablar y un modelo asr para transcribir; copie su identificación pública exacta.
- Entrada de audio
- La grabación a transcribir. Este ejemplo utiliza mono, 24 kHz, 16-bit PCM. Python lee el audio de un archivo WAV; Node.js lee un archivo PCM sin encabezado.
- Llave API
- Tu credencial de acceso, creada en la consola. Va en el encabezado Authorization cuando se abre la conexión.
Tu primera conexión
Elija su método de integración y entorno, luego siga los pasos a continuación.
Prepare una carpeta e instale la biblioteca.
Utilice Python 3.10 o posterior. Abra una terminal en una carpeta vacía e instale el OpenAI SDK oficial. Se conecta a la puerta de enlace de voz a través de WebSocket; El ejemplo fue probado con la versión siguiente. Descargar ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
Configure su clave API
Cree una clave en la consola, luego reemplace YOUR_API_KEY a continuación con su propia clave. Ejecute esto en la misma terminal que el ejemplo. Administrar claves API ↗
export STARSG_API_KEY="YOUR_API_KEY"
Mantenga su clave privada. Estos son ejemplos locales/de servidor, no código de navegador. No coloque una clave API permanente en una página web o en un repositorio público. Al ejecutar el ejemplo se genera una llamada de modelo facturable.
Prepara una breve grabación.
Coloque input.wav en la misma carpeta: mono, 24,000 Hz, 16-bit PCM WAV, al menos 100 ms de voz. También puedes usar output.wav del ejemplo de síntesis y cambiarle el nombre a input.wav.
Si su grabación usa otro formato, instale FFmpeg, reemplace recording.mp3 con su nombre de archivo y luego conviértalo: FFmpeg ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
Guarde el ejemplo y ejecútelo.
Copie el ejemplo completo a continuación en un nuevo archivo de texto sin formato llamado speech.py en esta carpeta. Guárdelo, luego ejecute este comando en la misma terminal.
.venv/bin/python speech.py
Cómo se ve el éxitoEl terminal puede imprimir actualizaciones “Parciales:”, luego “Final:” seguido de la transcripción completa. Algunos modelos pueden producir sólo el resultado final.
Ejemplo completo
Copie el archivo completo. Se conecta, configura la sesión, envía una entrada, espera a que finalice y cierra la conexión. No lo vuelve a intentar automáticamente.
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())
El ejemplo utiliza un ID de modelo público. La disponibilidad depende de su cuenta y entorno; Elija un modelo que admita esta tarea en tiempo real. Ver modelos ↗
Flujo de eventos
Cada mensaje es un evento JSON. Enviar significa su programa → servidor; recibir significa servidor → su programa. Espere a que se actualice la sesión antes de enviar la entrada.
- Recibir
session.createdEl servidor ha abierto una sesión. Ya puedes enviar su configuración.
- Enviar
session.updateConfigure la sesión de transcripción, el formato de audio de entrada, el modelo de reconocimiento y la detección de turnos.
- Recibir
session.updatedEl servidor aceptó la configuración. Ahora envía la entrada.
- Enviar
input_audio_buffer.appendEnvíe Base64 PCM en el campo de audio. Este ejemplo utiliza fragmentos de bytes 4,800, equivalentes a 100 ms en el formato configurado.
- Enviar
input_audio_buffer.commitTermina el turno de entrada. Con turn_detection=null, debes comprometerte explícitamente; no envíe respuesta.cree para reconocimiento.
- Recibir
conversation.item.input_audio_transcription.deltaLeer delta y text_mode; actualice los item_id y content_index correspondientes.
- Recibir
conversation.item.input_audio_transcription.completedEl campo de transcripción es el texto final autorizado. Guárdelo y luego cierre este ejemplo de un solo turno.
Inspeccionar el mensaje 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
}
}
}
}Referencia de parámetros
Los nombres con puntos muestran dónde pertenece un campo en el objeto JSON. "Obligatorio" a continuación se aplica al flujo de trabajo de esta guía. El soporte avanzado y los límites dependen del modelo.
Conexión y autenticación
modelstringRequeridoParámetro de consulta requerido en WebSocket URL. Utilice el ID de modelo público exacto del catálogo en tiempo real. Los modelos ASR y TTS no son intercambiables.
Ejemplo/escenarioasr-altair-v1-miniAuthorizationstringRequeridoEncabezado de conexión: Bearer, un espacio, luego su clave API. Utilice la clave para el entorno de destino; no lo pongas en el URL.
Ejemplo/escenarioBearer <API_KEY>
Sesión y entrada
session.typestringRequeridoUtilice la transcripción únicamente para reconocimiento. Devuelve texto sin generar una respuesta de voz del asistente.
Ejemplo/escenario"transcription"session.audio.input.formatobjectRequeridoConfiguración de audio: el tipo es audio/pcm, la velocidad es 24000. Este ejemplo utiliza muestras little-endian de bits 16 mono y firmados: 48,000 bytes por segundo. Los encabezados WAV no se envían a través del socket.
Ejemplo/escenario{"type":"audio/pcm","rate":24000}session.audio.input.transcription.modelstringRequeridoUtilice el mismo ID de modelo público ASR que la consulta URL. No sustituya el nombre del modelo del proveedor ascendente.
Ejemplo/escenarioasr-altair-v1-minisession.audio.input.turn_detectionobject | nullOpcionalEl ejemplo establece explícitamente null para deshabilitar la detección automática de giros (VAD). Envíe input_audio_buffer.commit cuando se haya enviado todo el audio de entrada. Esta es una configuración elegida, no una afirmación sobre la configuración predeterminada del servidor.
Ejemplo/escenarionullaudiostringRequeridoBase64-encoded bytes PCM sin procesar en input_audio_buffer.append. Envía al menos 100 ms en un turno comprometido. Un MP3, un encabezado WAV, un nombre de archivo o URL no pueden reemplazar este campo.
Solución de problemas
Lea primero el error devuelto. Una conexión abierta o una transcripción parcial no significa que este turno de reconocimiento haya completado. Espere la transcripción final.
Comando no encontrado o módulo faltante
Instale el tiempo de ejecución seleccionado, vuelva a abrir su terminal y ejecute los comandos de configuración en la carpeta del proyecto. Para Python, utilice el intérprete .venv que se muestra arriba; instale websocket-client, no el paquete websocket de nombre similar. Los ejemplos de Node.js utilizan el paquete ws y un archivo .mjs.
401 / 403 o falta la clave API
Verifique que la variable de entorno esté configurada en esta terminal, que YOUR_API_KEY haya sido reemplazada y que la clave pertenezca al entorno de destino. Confirme el acceso al modelo y el estado de la cuenta. Mantenga la clave fuera de capturas de pantalla y registros.
El protocolo de enlace falla, 404 / 503 o no se encontró el modelo
Verifique el nombre de host de WSS, el puerto, la ruta /v1/realtime y el ID del modelo público exacto. Utilice el catálogo de modelos en tiempo real para el entorno de destino. No sigas una redirección a un HTTP URL inseguro. Un 503 puede requerir que el operador del servicio verifique la disponibilidad.
No hay transcripción o hay un error de formato de audio
Utilice PCM little-endian mono, 24 kHz, con signo 16 bits y con al menos 100 ms de voz. Python lee PCM WAV; Node.js lee PCM sin encabezado. Convierta la grabación usando el comando anterior en lugar de simplemente cambiar el nombre de su extensión.
El tiempo de espera o la conexión se cierra antes de completarse
Los ejemplos se detienen después de 90 segundos. Pruebe una entrada más corta y verifique el acceso a la red. No trate una transcripción parcial o un audio parcial como un éxito. Compruebe si se ejecutó la solicitud anterior antes de volver a intentarlo, para evitar llamadas duplicadas.
No se puede encontrar input.wav o input.pcm
Mantenga la grabación al lado del ejemplo y ejecute el comando desde esa carpeta. Python usa input.wav; Node.js utiliza input.pcm. El texto final aparece después de “Final:”; El reconocimiento no crea un archivo de audio.
Antecedentes del protocolo: OpenAI WebSockets ↗