Convertir texto en voz
Envíe texto a través de una conexión WebSocket y reciba audio en fragmentos. Comience con un ejemplo completo que guarda un archivo WAV reproducible.
wss://api.starsg.ai/v1/realtime?model=tts-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.
- Voz
- La voz utilizada para la síntesis. Elija un voice_id del catálogo del modelo seleccionado; El reconocimiento no necesita voz.
- 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.
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 éxitoLa terminal imprime "Guardado:" y crea salida.wav. Ábrelo con tu reproductor de audio. Para ejecutarlo nuevamente, cambie el nombre o elimine ese archivo primero; el ejemplo no lo sobrescribirá.
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 = "tts-altair-v1-mini"
SESSION = json.loads("{\"type\":\"realtime\",\"output_modalities\":[\"audio\"],\"audio\":{\"output\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000}}}}")
TEXT = "¡Hola! Este es mi primer ejemplo de síntesis de voz."
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())
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 ↗
Para elegir una voz, busque su voice_id en el catálogo de voces de ese modelo y configure SPEECH_VOICE en su terminal antes de ejecutar. Omítelo para usar la voz predeterminada. Un nombre para mostrar como "Aleación" no es voice_id. Reemplace VOICE_ID a continuación con un valor de ese catálogo.
export SPEECH_VOICE="VOICE_ID"
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 tarea, el formato de audio y la voz opcional.
- Recibir
session.updatedEl servidor aceptó la configuración. Ahora envía la entrada.
- Enviar
conversation.item.createCree un mensaje de usuario con content.type=input_text y content.text que contenga su texto.
- Enviar
response.createPídale al servidor que genere audio para el texto.
- Recibir
response.output_audio.deltaDecodifique el campo delta Base64 y recopile los bytes PCM en orden. Estos fragmentos no son archivos WAV separados.
- Recibir
response.doneVerifique que el estado de respuesta esté completo, luego agregue un encabezado WAV y guarde el audio recopilado. Otros estados son fracasos.
Inspeccionar el mensaje session.update
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}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/escenariotts-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 el tiempo real para una sesión de texto a voz. Este es un flujo de trabajo de síntesis, no una conversación general entre agentes de voz.
Ejemplo/escenario"realtime"session.output_modalitiesstring[]RequeridoSolicitar salida de audio para síntesis. Envíe esta matriz en session.update.
Ejemplo/escenario["audio"]session.audio.output.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.output.voicestringOpcionalvoice_id opcional del catálogo de voz del modelo seleccionado. Está limitado al modelo. Omítalo como valor predeterminado del servidor; no utilice el nombre para mostrar del proveedor. Configúrelo antes de que comience la salida de audio.
Explorar vocesPredeterminado/omitido La voz predeterminada del modelo.item.content[].textstringRequeridoTexto a sintetizar, dentro de conversacion.item.create → item → content. Establezca el tipo de elemento de contenido en input_text, item.type en mensaje y item.role en usuario. Los límites de texto dependen del modelo.
Controles de voz opcionales
Comience sin estos controles. Verifique el output_controls del modelo antes de agregarlos. Los valores de volumen o tono no admitidos provocan un error; no son ignorados silenciosamente. Bloqueo de voz y velocidad después de la primera salida de audio; El volumen y el tono pueden actualizarse más adelante.
session.audio.output.speednumberOpcionalMultiplicador de velocidad de conversación: 1.0 es la velocidad normal. Los valores mínimos y máximos aceptados dependen del modelo; Consulta el catálogo. Configúrelo antes del primer audio de salida.
Ejemplo/escenario1.0session.audio.output.options.volumenumber | nullOpcionalExtensión de plataforma en opciones: multiplicador de ganancia, valor neutral 1.0. El rango de protocolo es 0 < volumen ≤ 10, pero el modelo debe admitirlo. Omitido o nulo utiliza el valor neutral; los valores no admitidos se rechazan.
Predeterminado/omitido1.0session.audio.output.options.pitchnumber | nullOpcionalAmpliación de plataforma en opciones: cambio de tono en semitonos, valor neutro 0. El rango de protocolo externo es −24 a 24; un modelo puede permitir menos. Utilice los límites anunciados. Omitido o nulo utiliza tono neutro.
Predeterminado/omitido0
Solución de problemas
Lea primero el mensaje de error devuelto. La apertura de una conexión o la llegada de un fragmento de audio no significa que la solicitud se haya completado correctamente.
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.
Sin transcripción, audio no válido o reproducción confusa
Verifique 24 kHz, mono, PCM little-endian de bits 16 y al menos 100 ms de voz. Utilice el comando de conversión en lugar de cambiar el nombre del archivo. El reconocimiento envía PCM sin formato, no el encabezado WAV. Para la síntesis, decodifique Base64 y una fragmentos PCM antes de crear un archivo WAV.
invalid_value o un control no compatible
Elimine las configuraciones opcionales de velocidad, volumen y tono, luego verifique output_controls para el modelo seleccionado. No reutilice el voice_id ni los límites numéricos de otro modelo. Una actualización de sesión rechazada no aplica esa configuració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.
output.wav ya existe o falta el archivo de entrada
Ejecute el script desde la carpeta que contiene Speech.py o Speech.mjs. Coloque input.wav (Python) o input.pcm (Node.js) allí. Cambie el nombre del archivo anterior.wav antes de generarlo nuevamente. Una línea "Final:" es el resultado del reconocimiento; no crea un archivo de audio.
Antecedentes del protocolo: OpenAI WebSockets ↗