API Grok STT и TTS: расшифровка, озвучка и загрузка

Grok STT расшифровывает готовую запись, а Grok TTS читает сценарий заранее выбранным голосом. Сначала попробуйте оба в Playground SpicyAPI, затем вызывайте их из кода или через агента. Это работа с сохранёнными файлами; для живого голосового диалога нужен транспорт реального времени. STT стоит около 0,002 $ за минуту аудио, TTS — 0,018 $ за 1000 символов. По нашим тестам в сентябре 2026 года оба маршрута обрабатывают записи и сценарии для взрослых как написано, без отказов, маскировки и обрезанных клипов.

Цены, лимиты и что возвращает каждый маршрут

Для более длинной или более крупной записи нужен публичный URL. URL может вести и на M4A, FLAC, OGG, Opus, AAC, MP4 или MKV, но должен отдавать сам аудиофайл, а не плеер или страницу для обмена. STT не принимает PCM, μ-law и A-law без заголовка.

Час аудио стоит около 0,12 $, запись на 90 секунд — около 0,003 $. Сначала задача резервирует максимум в два часа, около 0,24 $, и возвращает разницу, когда становится известна реальная длительность. Сценарий на 1800 символов стоит 0,0324 $; два полных дубля плюс вставка на 240 символов — 0,06912 $. Пробелы, знаки препинания и теги интонации считаются символами, а стоимость, показанная перед запуском TTS, является окончательной.

Сначала попробуйте в Playground

Расшифровка. Откройте страницу Grok STT и оставайтесь на вкладке Playground.

1. В Input audio загрузите MP3 или WAV (до 90 МБ) либо переключитесь на Asset URL и нажмите Add URL для записи, размещённой в другом месте.
2. Открывайте Advanced parameters, только если нужны Language, Normalize text, Key terms, Keep filler words или Transcribe channels separately.
3. Проверьте оценку цены, войдите в аккаунт и запустите. Расшифровка появится на панели Output; для времени слов есть вид JSON.

Озвучка. Откройте страницу Grok TTS.

1. Вставьте или отредактируйте сценарий в поле Text (кнопка Sample script подставляет пример), при необходимости с тегами интонации.
2. Выберите Voice; в меню у каждого голоса указаны имя, пол и язык. В Advanced parameters находятся Speed, Output format, Bitrate и Language.
3. Запустите, прослушайте дубль на панели Output и сохраните его кнопкой Download.

Проверьте здесь самое трудное имя или фразу, прежде чем писать сценарий целой озвучки: то, что плохо звучит в Playground, так же плохо прозвучит через API.

Параметры расшифровки, которые меняют результат

Language (language) можно не указывать — язык определится сам. Normalize text (text_normalization) записывает числа, цены и даты цифрами («March 14», «$1,250») и требует language; оставьте выключенным, если нужна точная произнесённая формулировка.

Keep filler words (filler_words: true) сохраняет «э-э» и «м-м», которые по умолчанию удаляются. Key terms (keyterms) направляют написание к вымышленным именам и брендам, до 100 терминов по 50 символов. Передавайте их объектами, [{"term":"Mara"},{"term":"Jon"}], а не простыми строками.

Transcribe channels separately (multichannel: true) расшифровывает каждый канал файла отдельно, до восьми. При выключенной опции в стереозаписи с разными говорящими на каждой стороне одного из них может не оказаться. Читайте output.transcript.channels, чтобы получить слова и время каждой стороны; объединённый текст — это по строке на канал, а не готовый диалог. Опция не разделяет двух людей, смешанных в одном моноканале, а маршрут не возвращает меток говорящих, поэтому для моноинтервью используйте раздельно записанные каналы или инструмент диаризации.

Затем вызовите из кода

Установите Python SDK (pip install spicyapi, Python 3.11+), задайте SPICY_API_KEY и запустите этот поток от расшифровки до озвучки. Замените путь к файлу записью, которую вам разрешено использовать.

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

Используйте ключ идемпотентности повторно только для повтора того же запроса после потерянного ответа. Загрузки, ожидание, ошибки, повторные попытки и обновление просроченной ссылки на скачивание описаны в справочнике Python SDK и руководстве по задачам.

Или поручите агенту

Если расшифровку и озвучку должен выполнять ассистент, дайте ему CLI или MCP-сервер. Оба показывают цену и просят вашего подтверждения перед платным вызовом. Skill добавляет инструкции поверх любого из них.

• CLI. spicyapi запускает одну задачу из терминала (npx @spicyapi/cli работает без установки):

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

• MCP-сервер. Добавьте MCP-сервер своему ассистенту и попросите: «Transcribe ./interview.mp3 with Grok STT, with each channel separate.» Он вызовет spicyapi_upload_file, затем spicyapi_task_create (остановится для подтверждения цены) и после этого 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 устанавливает Agent Skill, который учит ассистента для программирования читать актуальную схему и повторно использовать ключи идемпотентности. Сам он задачи не запускает, поэтому применяйте его вместе с CLI или MCP.

От расшифровки к сценарию и голосу

Перед синтезом отредактируйте расшифровку: исправьте имена, пунктуацию и всё, что должно читаться иначе. Короткий список key terms полезен для вымышленных имён, но расшифровка всё равно отражает то, что звучит в записи, поэтому сверяйте имена со звуком.

В TTS 71 готовый голос. По умолчанию используется eve; eve, ara, leo, rex и sal говорят на всех поддерживаемых языках, а остальные 66 настроены на один язык и в API выглядят как непрозрачные ID. Выбирайте их в меню голосов на странице модели Grok TTS: там у каждого указаны имя, пол и язык. Прежде чем синтезировать всю озвучку, попробуйте короткий отрывок с самым трудным именем.

Интонация задаётся в сценарии. Встроенные теги издают звук там, где вы их поставите: [pause], [long-pause], [breath], [inhale], [exhale], [sigh], [laugh], [chuckle], [giggle], [cry]. Оборачивающие теги меняют то, как читаются заключённые в них слова: <whisper>, <soft>, <slow>, <loud>, <build-intensity> и другие. Теги исполняются, а не зачитываются вслух, но входят в цену. Например:

{"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 меняется от 0,7 до 1,5. bitrate действует только для MP3. Для прослушивания берите MP3, для монтажа — WAV; сырые pcm, mulaw и alaw на 8 кГц предназначены для телефонных систем и в браузере не воспроизведутся. SSML не поддерживается; используйте теги выше.

Для сцены с двумя персонажами синтезируйте реплики каждого говорящего отдельно разными голосами и смонтируйте вместе; один запрос читает одним голосом. На стыках оставляйте естественные паузы, а не обрезайте их до нуля.

Чтобы проверить дубль, пропустите созданное аудио обратно через STT и сравните со сценарием: пропавшие или изменённые слова, обрезанный конец или зачитанный вслух тег обычно заметны, а короткий клип стоит доли цента. Затем прослушайте начало, конец и каждую отмеченную строку. Если готовых голосов Grok мало, в каталоге моделей есть другие варианты озвучки; сравнение «Uncensored text-to-speech APIs compared» пока доступно только на английском.

Частые проблемы и решения

Метки времени слов в STT относятся к исходной записи. TTS возвращает аудио без времени слов, поэтому смена текста или скорости делает старые метки недействительными; выравнивайте субтитры по готовому синтезированному дублю.