Documentación API

WebSocketEventos compatibles con OpenAI

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.

ID del modelo
Entrada de audioenviar mensajes de texto
WSSwss://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.

  1. 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 ↗

    bash
    python3 -m venv .venv
    .venv/bin/python -m pip install "openai[realtime]==3.35.1"
  2. 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 ↗

    bash
    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.

  3. 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 ↗

    bash
    ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
  4. 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.

    bash
    .venv/bin/python speech.py
    Cómo se ve el éxito

    El 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.

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())

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.

  1. Recibir
    session.created

    El servidor ha abierto una sesión. Ya puedes enviar su configuración.

  2. Enviar
    session.update

    Configure la sesión de transcripción, el formato de audio de entrada, el modelo de reconocimiento y la detección de turnos.

  3. Recibir
    session.updated

    El servidor aceptó la configuración. Ahora envía la entrada.

  4. Enviar
    input_audio_buffer.append

    Envíe Base64 PCM en el campo de audio. Este ejemplo utiliza fragmentos de bytes 4,800, equivalentes a 100 ms en el formato configurado.

  5. Enviar
    input_audio_buffer.commit

    Termina el turno de entrada. Con turn_detection=null, debes comprometerte explícitamente; no envíe respuesta.cree para reconocimiento.

  6. Recibir
    conversation.item.input_audio_transcription.delta

    Leer delta y text_mode; actualice los item_id y content_index correspondientes.

  7. Recibir
    conversation.item.input_audio_transcription.completed

    El 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
json
{
  "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

modelstringRequerido

Pará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/escenario asr-altair-v1-mini
AuthorizationstringRequerido

Encabezado 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/escenario Bearer <API_KEY>

Sesión y entrada

session.typestringRequerido

Utilice la transcripción únicamente para reconocimiento. Devuelve texto sin generar una respuesta de voz del asistente.

Ejemplo/escenario "transcription"
session.audio.input.formatobjectRequerido

Configuració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.modelstringRequerido

Utilice el mismo ID de modelo público ASR que la consulta URL. No sustituya el nombre del modelo del proveedor ascendente.

Ejemplo/escenario asr-altair-v1-mini
session.audio.input.turn_detectionobject | nullOpcional

El 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/escenario null
audiostringRequerido

Base64-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 ↗