API de Grok STT y TTS: transcribe, narra y descarga

Usa Grok STT para transcribir una grabación existente y Grok TTS para que una voz predefinida lea un guion. Prueba ambos primero en el Playground de SpicyAPI y después llámalos desde código o desde un agente. Es un flujo con archivos guardados; para conversar por voz en directo necesitas un transporte en tiempo real. STT cuesta unos 0,002 $ por minuto de audio; TTS, 0,018 $ por 1.000 caracteres. Según nuestras pruebas de septiembre de 2026, ambas rutas procesan grabaciones y guiones para adultos tal como están escritos, sin rechazos, enmascarado ni clips cortados.

Precios, límites y qué devuelve cada ruta

Una grabación más larga o más pesada necesita una URL pública. La URL también puede apuntar a M4A, FLAC, OGG, Opus, AAC, MP4 o MKV, pero debe devolver el archivo de audio en sí, no un reproductor ni una página para compartir. STT no acepta PCM, μ-law ni A-law sin cabecera.

Una hora de audio cuesta unos 0,12 $ y una grabación de 90 segundos, unos 0,003 $. La tarea retiene primero el máximo de dos horas, unos 0,24 $, y libera la diferencia cuando se conoce la duración real. Un guion de 1.800 caracteres cuesta 0,0324 $; dos tomas completas más una toma de corrección de 240 caracteres cuestan 0,06912 $. Los espacios, la puntuación y las etiquetas de entonación cuentan como caracteres, y el presupuesto que se muestra antes de una ejecución de TTS es el cobro final.

Pruébalo primero en el Playground

Transcribir. Abre la página de Grok STT y quédate en la pestaña Playground.

1. En Input audio, sube tu MP3 o WAV (hasta 90 MB) o cambia a Asset URL y pulsa Add URL para una grabación alojada en otro sitio.
2. Abre Advanced parameters solo si necesitas Language, Normalize text, Key terms, Keep filler words o Transcribe channels separately.
3. Revisa la estimación de precio, inicia sesión y ejecuta. La transcripción aparece en el panel Output, con una vista JSON para los tiempos por palabra.

Narrar. Abre la página de Grok TTS.

1. Pega o edita el guion en Text (el botón Sample script rellena un ejemplo), con las etiquetas de entonación que quieras.
2. Elige una Voice; el menú indica de cada una el nombre, el género y el idioma. En Advanced parameters están Speed, Output format, Bitrate y Language.
3. Ejecútalo, escucha la toma en el panel Output y usa Download para guardarla.

Prueba aquí tu nombre o frase más difícil antes de escribir una narración entera; lo que suena mal en el Playground sonará igual de mal desde la API.

Opciones de transcripción que cambian el resultado

Language (language) puede omitirse para que se detecte. Normalize text (text_normalization) escribe números, precios y fechas con cifras («March 14», «$1,250») y exige language; déjalo desactivado si necesitas las palabras exactas tal como se dijeron.

Keep filler words (filler_words: true) conserva los «eh» y «mm», que por defecto se eliminan. Key terms (keyterms) orientan la ortografía hacia nombres inventados y marcas, hasta 100 términos de 50 caracteres. Envíalos como objetos, [{"term":"Mara"},{"term":"Jon"}], no como cadenas simples.

Transcribe channels separately (multichannel: true) transcribe por separado cada canal de un archivo, hasta ocho. Con la opción desactivada, una grabación estéreo con un hablante distinto en cada lado puede devolverse sin uno de ellos. Lee output.transcript.channels para las palabras y los tiempos de cada lado; el texto combinado es una línea por canal, no un diálogo terminado. No separa a dos personas mezcladas en un canal mono, y la ruta no devuelve etiquetas de hablante, así que usa canales grabados por separado o una herramienta de diarización para entrevistas en mono.

Después, llámalo desde código

Instala el SDK de Python (pip install spicyapi, Python 3.11+), define SPICY_API_KEY y ejecuta este flujo de transcripción a narración. Sustituye la ruta del archivo por una grabación que estés autorizado a usar.

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

# 1. Transcribe a local recording (uploads are free and kept for one day)
source = client.upload_file("./interview.mp3")
stt = client.create_task(
    model="xai/grok-stt/speech-to-text",
    input_data={"audio_url": source["uri"], "multichannel": True},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
done = client.wait_for_terminal(stt["taskId"])
if done["state"] != "succeeded":
    raise RuntimeError(f"STT task {stt['taskId']} ended as {done['state']}")
print(done["output"]["text"])  # edit this into your script

# 2. Narrate the edited script
script = "Chapter Three. The storm kept them in the cabin. [breath] <slow>Neither of them pretended to be reading.</slow>"
tts = client.create_task(
    model="xai/grok-tts/text-to-speech",
    input_data={"text": script, "voice_id": "rex", "language": "en", "speed": 0.9},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
final = client.wait_for_terminal(tts["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"TTS task {tts['taskId']} ended as {final['state']}")

# 3. Copy the MP3 link to your own storage now; generated audio is kept for 14 days
print(output_assets(final)[0]["url"])

Reutiliza una clave de idempotencia solo para reintentar la misma solicitud tras una respuesta perdida. Las subidas, la espera, los errores, los reintentos y la renovación de un enlace de descarga caducado están en la referencia del SDK de Python y en la guía de tareas.

O deja que lo ejecute un agente

Si quieres que un asistente haga la transcripción y la narración por ti, dale la CLI o el servidor MCP. Ambos muestran el precio y piden tu confirmación antes de una llamada de pago. La Skill añade instrucciones sobre cualquiera de los dos.

• CLI. spicyapi ejecuta una tarea desde la terminal (npx @spicyapi/cli funciona sin instalar):

``bash spicyapi files upload ./interview.mp3 # prints a spicy:// URI spicyapi tasks create --model xai/grok-stt/speech-to-text \ --input-json '{"audio_url": "spicy://YOUR-UPLOAD-URI", "multichannel": true}' --wait ``

• Servidor MCP. Añade el servidor MCP a tu asistente y pide: «Transcribe ./interview.mp3 with Grok STT, with each channel separate.» Llama a spicyapi_upload_file, luego a spicyapi_task_create (que se detiene a esperar tu confirmación del precio) y después a spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill instala la Agent Skill, que enseña a un asistente de programación a leer el esquema vigente y a reutilizar las claves de idempotencia. No puede ejecutar tareas por sí sola, así que úsala junto con la CLI o MCP.

De la transcripción al guion y a la voz

Edita la transcripción antes de sintetizar: corrige nombres, puntuación y todo lo que quieras que se lea de otra manera. Conviene añadir una lista breve de key terms para los nombres inventados, pero la transcripción sigue reflejando lo que dice la grabación, así que comprueba los nombres con el audio.

TTS tiene 71 voces predefinidas. eve es la predeterminada; eve, ara, leo, rex y sal hablan todos los idiomas admitidos, mientras que las otras 66 están ajustadas a un solo idioma y aparecen en la API como ID opacos. Elígelas en el menú de voces de la página del modelo Grok TTS, que indica de cada una el nombre, el género y el idioma. Prueba un pasaje corto con tu nombre más difícil antes de sintetizar una narración entera.

La entonación se escribe en el guion. Las etiquetas en línea producen un sonido donde las colocas: [pause], [long-pause], [breath], [inhale], [exhale], [sigh], [laugh], [chuckle], [giggle], [cry]. Las etiquetas envolventes cambian cómo se leen las palabras que contienen: <whisper>, <soft>, <slow>, <loud>, <build-intensity> y otras. Las etiquetas se interpretan, no se leen en voz alta, pero cuentan en el precio. Por ejemplo:

{"text": "Chapter Three. The storm kept them in the cabin for two more days. [breath] By the second night, <slow>neither of them pretended to be reading anymore.</slow>", "voice_id": "rex", "speed": 0.9, "language": "en"}

speed va de 0,7 a 1,5. bitrate solo se aplica a MP3. Usa MP3 para reproducir y WAV para editar; los formatos sin procesar pcm, mulaw y alaw a 8 kHz son para sistemas telefónicos y no se reproducen en un navegador. SSML no es compatible; usa las etiquetas anteriores.

Para una escena con dos personajes, sintetiza por separado las líneas de cada hablante con voces distintas y móntalas juntas; una solicitud lee una sola voz. Deja pausas naturales en las uniones en lugar de recortarlas a cero.

Para comprobar una toma, pasa el audio generado de nuevo por STT y compáralo con el guion: las palabras que faltan o cambian, un final cortado o una etiqueta leída en voz alta suelen delatarse, y un clip corto cuesta una fracción de céntimo. Después escucha el comienzo, el final y cualquier línea que se haya señalado. Si las voces predefinidas de Grok no bastan, en el catálogo de modelos hay otras opciones de voz; la comparativa «Uncensored text-to-speech APIs compared» solo existe en inglés por ahora.

Problemas comunes y soluciones

Las marcas de tiempo por palabra de STT pertenecen a la grabación original. TTS devuelve audio sin tiempos por palabra, de modo que cambiar el texto o la velocidad invalida las marcas antiguas; alinea los subtítulos con la toma sintetizada final.