Guías de medios

Audio y tiempo real

Cree voz, transcriba audio, traduzca voz o abra una sesión en tiempo real

Utilice los endpoints de audio cuando el resultado sea un archivo o texto. Utilice el endpoint WebSocket de tiempo real para una experiencia de audio bidireccional en vivo.

Elija un endpoint

NecesidadEndpointÚselo cuando
Texto a vozPOST /v1/audio/speechNecesite un archivo de audio a partir de texto.
TranscripciónPOST /v1/audio/transcriptionsNecesite texto a partir de un archivo de audio.
Traducción de audioPOST /v1/audio/translationsNecesite texto traducido a partir de un archivo de audio.
WebSocket en tiempo realWS /v1/realtime?model={model}Necesite streaming de audio bidireccional a través de WebSocket. El GET /v1/realtime simple solo devuelve metadatos.

Elija un modelo

Lea la lista de modelos actual en lugar de codificarla de forma rígida. Verifique los detalles del modelo seleccionado para confirmar la compatibilidad con tiempo real antes de abrir un socket.

curl "https://api.tokenlab.sh/v1/models?recommended_for=tts" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models?recommended_for=stt" \
  -H "Authorization: Bearer sk-your-api-key"

Solicitudes de audio

La función de voz (speech) devuelve audio en la respuesta HTTP. La transcripción y la traducción pueden devolver texto final o una tarea aceptada. Cuando el cuerpo contenga un ID de tarea y un estado en lugar del texto final, guarde el ID y realice consultas a GET /v1/tasks/{id} hasta que se complete o falle. Deje suficiente tiempo para archivos grandes y conserve el Request ID.

Las URLs de resultados de audio son URLs de TokenLab media-result que permanecen válidas durante 30 días. media_retention.items informa el estado de guardado de cada elemento y su expires_at; la respuesta puede omitir media_retention cuando el estado de guardado no se conoce a tiempo, y la URL seguirá funcionando. Las respuestas de audio en línea o binarias están fuera de esta retención de copia de URL. Consulte Retención de datos.

curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-tts",
    "voice": "eve",
    "input": "Welcome to TokenLab."
  }' \
  --output speech.mp3

Sesiones en tiempo real

Abra un WebSocket con el modelo en la cadena de consulta (query string) y la API key en el encabezado Authorization. Mantenga el formato de evento documentado para el modelo de tiempo real seleccionado y cierre el socket cuando la sesión haya finalizado.

Una sesión dura como máximo 1 hora. Después, el servidor cierra el socket con el código 1000 y el motivo session_timeout. Un solo mensaje puede tener hasta 32 MiB; un mensaje más grande cierra el socket con el código 1009. Algunos modelos de tiempo real, como grok-voice-think-fast-2.0, solo aceptan tramas de audio y actualizaciones de sesión. Un elemento de entrada de texto devuelve el error unsupported_realtime_text_input y cierra el socket con el código 1008.

Esta guía cubre solo el subconjunto de WebSocket. TokenLab actualmente no proporciona el secreto de cliente de OpenAI Realtime REST, el secreto de cliente de traducción, llamadas (Calls) ni endpoints de gestión de sesiones beta heredados.

Para el ejemplo del lado del servidor a continuación, instale ws y establezca TOKENLAB_REALTIME_MODEL en un modelo actual cuyo detalle declare /v1/realtime. Proporcione TOKENLAB_API_KEY en el entorno del servidor; el nombre por sí solo no establece la compatibilidad con tiempo real.

npm install ws
import WebSocket from 'ws';

const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
socket.on('message', (event) => console.log(event.toString()));
socket.on('error', (error) => console.error(error.message));
process.once('SIGINT', () => socket.close(1000, 'Client stopped'));

Mostrar el progreso de forma segura

  • Guarde los archivos de audio generados en lugar de repetir la misma solicitud al actualizar.
  • Para la transcripción y la traducción, muestre los estados de carga y procesamiento incluso cuando la llamada a la API sea síncrona.
  • Para el tiempo real, maneje los eventos de cierre y vuelva a conectar solo después de que el usuario inicie una nueva sesión.
  • No incluya API keys, URLs privadas o secretos de cuenta en la entrada de texto de audio.

Referencia de la API

TemaReferencia
Crear vozCrear voz
Crear transcripciónCrear transcripción
Crear traducciónCrear traducción
WebSocket en tiempo realWebSocket en tiempo real
Listar modelosListar modelos
Facturación y preciosFacturación y precios

En esta página