API Grok STT et TTS : transcrire, narrer et télécharger

Utilisez Grok STT pour transcrire un enregistrement existant et Grok TTS pour faire lire un script par une voix prédéfinie. Essayez d'abord les deux dans le Playground de SpicyAPI, puis appelez-les depuis du code ou un agent. C'est un flux fondé sur des fichiers enregistrés ; pour un échange vocal en direct, il faut un transport temps réel. STT coûte environ 0,002 $ par minute d'audio ; TTS, 0,018 $ pour 1 000 caractères. D'après nos tests de septembre 2026, les deux routes traitent tels quels les enregistrements et scripts pour adultes, sans refus, masquage ni clip coupé.

Tarifs, limites et ce que renvoie chaque route

Un enregistrement plus long ou plus volumineux nécessite une URL publique. Une URL peut aussi pointer vers du M4A, FLAC, OGG, Opus, AAC, MP4 ou MKV, mais elle doit renvoyer le fichier audio lui-même, pas un lecteur ni une page de partage. STT n'accepte pas le PCM, μ-law ni A-law sans en-tête.

Une heure d'audio coûte environ 0,12 $, et un enregistrement de 90 secondes environ 0,003 $. La tâche réserve d'abord le maximum de deux heures, soit environ 0,24 $, puis libère la différence une fois la durée réelle connue. Un script de 1 800 caractères coûte 0,0324 $ ; deux prises complètes plus une reprise de 240 caractères coûtent 0,06912 $. Les espaces, la ponctuation et les balises de diction comptent comme des caractères, et le devis affiché avant un lancement TTS est le montant final.

Essayer d'abord dans le Playground

Transcrire. Ouvrez la page Grok STT et restez sur l'onglet Playground.

1. Sous Input audio, téléversez votre MP3 ou WAV (jusqu'à 90 Mo) ou passez à Asset URL et cliquez sur Add URL pour un enregistrement hébergé ailleurs.
2. N'ouvrez Advanced parameters que si vous avez besoin de Language, Normalize text, Key terms, Keep filler words ou Transcribe channels separately.
3. Vérifiez l'estimation du prix, connectez-vous et lancez. La transcription apparaît dans le panneau Output, avec une vue JSON pour les horodatages des mots.

Narrer. Ouvrez la page Grok TTS.

1. Collez ou modifiez le script dans Text (le bouton Sample script insère un exemple), avec d'éventuelles balises de diction.
2. Choisissez une Voice ; le menu indique pour chacune le nom, le genre et la langue. Advanced parameters donne accès à Speed, Output format, Bitrate et Language.
3. Lancez, écoutez la prise dans le panneau Output et conservez-la avec Download.

Essayez ici votre nom ou votre phrase les plus difficiles avant de scripter toute une narration ; ce qui sonne mal dans le Playground sonnera tout aussi mal via l'API.

Options de transcription qui changent le résultat

Language (language) peut être omis pour une détection automatique. Normalize text (text_normalization) écrit les nombres, prix et dates en chiffres (« March 14 », « $1,250 ») et exige language ; laissez-le désactivé si vous avez besoin des mots exacts prononcés.

Keep filler words (filler_words: true) conserve les « euh » et « hum », supprimés par défaut. Key terms (keyterms) orientent l'orthographe vers des noms inventés et des marques, jusqu'à 100 termes de 50 caractères. Envoyez-les sous forme d'objets, [{"term":"Mara"},{"term":"Jon"}], et non de simples chaînes.

Transcribe channels separately (multichannel: true) transcrit séparément chaque canal d'un fichier, jusqu'à huit. Désactivée, l'option peut faire disparaître un locuteur d'un enregistrement stéréo où chaque côté porte une voix différente. Lisez output.transcript.channels pour les mots et horodatages de chaque côté ; le texte combiné compte une ligne par canal et n'est pas un dialogue finalisé. L'option ne sépare pas deux personnes mélangées sur un seul canal mono, et la route ne renvoie aucune étiquette de locuteur : pour des entretiens mono, utilisez des canaux enregistrés séparément ou un outil de diarisation.

Puis l'appeler depuis le code

Installez le SDK Python (pip install spicyapi, Python 3.11+), définissez SPICY_API_KEY et exécutez ce flux de la transcription à la narration. Remplacez le chemin du fichier par un enregistrement que vous avez le droit d'utiliser.

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"])

Ne réutilisez une clé d'idempotence que pour renvoyer la même requête après une réponse perdue. Téléversements, attente, erreurs, nouvelles tentatives et renouvellement d'un lien de téléchargement expiré sont décrits dans la référence du SDK Python et le guide des tâches.

Ou laisser un agent s'en charger

Si un assistant doit transcrire et narrer à votre place, donnez-lui la CLI ou le serveur MCP. Tous deux affichent le prix et demandent votre confirmation avant un appel payant. La Skill ajoute des instructions par-dessus l'un ou l'autre.

• CLI. spicyapi exécute une tâche depuis un terminal (npx @spicyapi/cli fonctionne sans installation) :

``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 ``

• Serveur MCP. Ajoutez le serveur MCP à votre assistant, puis demandez : « Transcribe ./interview.mp3 with Grok STT, with each channel separate. » Il appelle spicyapi_upload_file, puis spicyapi_task_create (qui s'arrête pour que vous confirmiez le prix), puis 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 installe l'Agent Skill, qui apprend à un assistant de code à lire le schéma à jour et à réutiliser les clés d'idempotence. Il ne peut pas exécuter de tâches seul : utilisez-le avec la CLI ou MCP.

De la transcription au script, puis à la voix

Corrigez la transcription avant la synthèse : noms, ponctuation et tout ce que vous voulez voir lu autrement. Une courte liste de key terms vaut la peine pour des noms inventés, mais la transcription reflète toujours ce que dit l'enregistrement ; vérifiez donc les noms à l'écoute.

TTS propose 71 voix prédéfinies. eve est la voix par défaut ; eve, ara, leo, rex et sal parlent toutes les langues prises en charge, tandis que les 66 autres sont réglées pour une seule langue et apparaissent comme des ID opaques dans l'API. Choisissez-les dans le menu des voix de la page du modèle Grok TTS, qui indique pour chacune le nom, le genre et la langue. Essayez un court passage contenant votre nom le plus difficile avant de synthétiser toute une narration.

La diction s'écrit dans le script. Les balises en ligne produisent un son là où vous les placez : [pause], [long-pause], [breath], [inhale], [exhale], [sigh], [laugh], [chuckle], [giggle], [cry]. Les balises englobantes modifient la façon dont les mots qu'elles entourent sont lus : <whisper>, <soft>, <slow>, <loud>, <build-intensity> et d'autres. Les balises sont interprétées, pas lues à voix haute, mais elles comptent dans le prix. Par exemple :

{"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 à 1,5. bitrate ne s'applique qu'au MP3. Utilisez le MP3 pour l'écoute et le WAV pour le montage ; les formats bruts pcm, mulaw et alaw à 8 kHz sont destinés aux systèmes téléphoniques et ne se lisent pas dans un navigateur. SSML n'est pas pris en charge ; utilisez les balises ci-dessus.

Pour une scène à deux personnages, synthétisez séparément les répliques de chaque locuteur avec des voix différentes, puis montez-les ensemble ; une requête ne lit qu'une voix. Gardez des pauses naturelles aux raccords plutôt que de les réduire à zéro.

Pour contrôler une prise, repassez l'audio généré dans STT et comparez-le au script : mots manquants ou modifiés, fin coupée ou balise prononcée à voix haute ressortent généralement, et un clip court coûte une fraction de centime. Écoutez ensuite le début, la fin et toute ligne signalée. Si les voix prédéfinies de Grok ne suffisent pas, le catalogue des modèles propose d'autres options vocales ; le comparatif « Uncensored text-to-speech APIs compared » n'existe pour l'instant qu'en anglais.

Problèmes courants et solutions

Les horodatages de mots de STT appartiennent à l'enregistrement d'origine. TTS renvoie de l'audio sans horodatage de mots : modifier le texte ou la vitesse invalide donc les anciens horodatages ; alignez les sous-titres sur la prise synthétisée finale.