API Grok STT i TTS: transkrypcja, narracja i pobieranie

Użyj Grok STT, aby przepisać istniejące nagranie, i Grok TTS, aby gotowy głos przeczytał scenariusz. Najpierw wypróbuj oba w Playground SpicyAPI, a potem wywołuj je z kodu lub przez agenta. To przepływ oparty na zapisanych plikach; do rozmowy głosowej na żywo potrzebny jest transport czasu rzeczywistego. STT kosztuje około 0,002 USD za minutę audio, TTS — 0,018 USD za 1000 znaków. Według naszych testów z września 2026 obie trasy przetwarzają nagrania i scenariusze dla dorosłych dokładnie tak, jak je napisano, bez odmów, maskowania i uciętych klipów.

Ceny, limity i co zwraca każda trasa

Dłuższe lub większe nagranie wymaga publicznego adresu URL. URL może też wskazywać M4A, FLAC, OGG, Opus, AAC, MP4 lub MKV, ale musi zwracać sam plik audio, a nie odtwarzacz ani stronę udostępniania. STT nie przyjmuje PCM, μ-law ani A-law bez nagłówka.

Godzina audio kosztuje około 0,12 USD, a nagranie trwające 90 sekund — około 0,003 USD. Zadanie najpierw rezerwuje maksimum dwóch godzin, około 0,24 USD, i zwalnia różnicę, gdy znana jest rzeczywista długość. Scenariusz o długości 1800 znaków kosztuje 0,0324 USD; dwa pełne ujęcia plus dogrywka 240 znaków kosztują 0,06912 USD. Spacje, interpunkcja i znaczniki dykcji liczą się jako znaki, a wycena pokazana przed uruchomieniem TTS jest ostateczną opłatą.

Najpierw wypróbuj w Playground

Transkrypcja. Otwórz stronę Grok STT i zostań na karcie Playground.

1. W Input audio prześlij plik MP3 lub WAV (do 90 MB) albo przełącz na Asset URL i kliknij Add URL, jeśli nagranie jest hostowane gdzie indziej.
2. Otwieraj Advanced parameters tylko wtedy, gdy potrzebujesz Language, Normalize text, Key terms, Keep filler words lub Transcribe channels separately.
3. Sprawdź szacowaną cenę, zaloguj się i uruchom. Transkrypt pojawi się w panelu Output, z widokiem JSON dla czasów słów.

Narracja. Otwórz stronę Grok TTS.

1. Wklej lub edytuj scenariusz w polu Text (przycisk Sample script wstawia przykład), w razie potrzeby ze znacznikami dykcji.
2. Wybierz Voice; menu opisuje każdy głos imieniem, płcią i językiem. W Advanced parameters są Speed, Output format, Bitrate i Language.
3. Uruchom, odsłuchaj ujęcie w panelu Output i zapisz je przyciskiem Download.

Sprawdź tu swoje najtrudniejsze imię lub zdanie, zanim zaczniesz skryptować całą narrację; to, co brzmi źle w Playground, zabrzmi tak samo źle z API.

Ustawienia transkrypcji, które zmieniają wynik

Language (language) można pominąć, aby język został wykryty. Normalize text (text_normalization) zapisuje liczby, ceny i daty cyframi („March 14”, „$1,250”) i wymaga language; zostaw wyłączone, gdy potrzebujesz dokładnego wypowiedzianego brzmienia.

Keep filler words (filler_words: true) zachowuje „yyy” i „eee”, które domyślnie są usuwane. Key terms (keyterms) kierują pisownię ku zmyślonym imionom i markom, do 100 terminów po 50 znaków. Wysyłaj je jako obiekty, [{"term":"Mara"},{"term":"Jon"}], a nie zwykłe ciągi znaków.

Transcribe channels separately (multichannel: true) transkrybuje osobno każdy kanał pliku, do ośmiu. Przy wyłączonej opcji w nagraniu stereo z innym mówcą po każdej stronie jednego z nich może zabraknąć. Odczytaj output.transcript.channels, aby uzyskać słowa i czasy każdej strony; połączony tekst to jedna linia na kanał, a nie gotowy dialog. Opcja nie rozdziela dwóch osób zmiksowanych w jednym kanale mono, a trasa nie zwraca etykiet mówców, więc przy wywiadach mono użyj osobno nagranych kanałów albo narzędzia do diaryzacji.

Potem wywołaj z kodu

Zainstaluj SDK Pythona (pip install spicyapi, Python 3.11+), ustaw SPICY_API_KEY i uruchom ten przepływ od transkrypcji do narracji. Zamień ścieżkę pliku na nagranie, którego wolno ci użyć.

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

Używaj ponownie klucza idempotencji tylko po to, by powtórzyć to samo żądanie po utraconej odpowiedzi. Przesyłanie plików, oczekiwanie, błędy, ponowienia i odnawianie wygasłego linku do pobrania opisuje dokumentacja SDK Pythona i przewodnik po zadaniach.

Albo zleć to agentowi

Jeśli transkrypcję i narrację ma wykonać asystent, daj mu CLI lub serwer MCP. Oba pokazują cenę i proszą o potwierdzenie przed płatnym wywołaniem. Skill dodaje instrukcje na wierzch któregokolwiek z nich.

• CLI. spicyapi uruchamia jedno zadanie z terminala (npx @spicyapi/cli działa bez instalacji):

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

• Serwer MCP. Dodaj serwer MCP do asystenta i poproś: „Transcribe ./interview.mp3 with Grok STT, with each channel separate.” Wywoła spicyapi_upload_file, potem spicyapi_task_create (zatrzyma się na twoje potwierdzenie ceny), a następnie 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 instaluje Agent Skill, który uczy asystenta programistycznego czytać aktualny schemat i ponownie używać kluczy idempotencji. Sam nie uruchamia zadań, więc używaj go razem z CLI lub MCP.

Od transkryptu do scenariusza i głosu

Przed syntezą popraw transkrypt: imiona, interpunkcję i wszystko, co ma być czytane inaczej. Krótka lista key terms przydaje się przy zmyślonych imionach, ale transkrypt nadal odzwierciedla to, co jest na nagraniu, więc sprawdzaj imiona w nagraniu.

TTS ma 71 gotowych głosów. Domyślny to eve; eve, ara, leo, rex i sal mówią we wszystkich obsługiwanych językach, a pozostałe 66 jest dostrojonych do jednego języka i w API występuje jako nieczytelne ID. Wybierz je z menu głosów na stronie modelu Grok TTS, które opisuje każdy głos imieniem, płcią i językiem. Przed syntezą całej narracji wypróbuj krótki fragment z najtrudniejszym imieniem.

Dykcję zapisuje się w scenariuszu. Znaczniki wewnątrz tekstu wydają dźwięk tam, gdzie je umieścisz: [pause], [long-pause], [breath], [inhale], [exhale], [sigh], [laugh], [chuckle], [giggle], [cry]. Znaczniki obejmujące fragment zmieniają sposób czytania zawartych w nim słów: <whisper>, <soft>, <slow>, <loud>, <build-intensity> i inne. Znaczniki są wykonywane, nie czytane na głos, ale wliczają się do ceny. Na przykład:

{"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 mieści się w zakresie od 0,7 do 1,5. bitrate dotyczy tylko MP3. Używaj MP3 do odsłuchu, a WAV do montażu; surowe pcm, mulaw i alaw przy 8 kHz są przeznaczone dla systemów telefonicznych i nie odtworzą się w przeglądarce. SSML nie jest obsługiwany; użyj powyższych znaczników.

W scenie z dwiema postaciami syntezuj kwestie każdego mówcy osobno, różnymi głosami, i zmontuj je razem; jedno żądanie czyta jednym głosem. Na łączeniach zostaw naturalne pauzy zamiast przycinać je do zera.

Aby sprawdzić ujęcie, puść wygenerowane audio z powrotem przez STT i porównaj ze scenariuszem: brakujące lub zmienione słowa, ucięte zakończenie albo przeczytany na głos znacznik zwykle wychodzą na jaw, a krótki klip kosztuje ułamek centa. Potem odsłuchaj początek, koniec i każdą wskazaną linijkę. Jeśli gotowe głosy Grok nie wystarczą, w katalogu modeli znajdziesz inne opcje głosowe; zestawienie „Uncensored text-to-speech APIs compared” jest na razie dostępne tylko po angielsku.

Typowe problemy i rozwiązania

Znaczniki czasu słów z STT dotyczą oryginalnego nagrania. TTS zwraca audio bez czasów słów, więc zmiana tekstu lub tempa unieważnia stare znaczniki; dopasuj napisy do gotowego, zsyntezowanego ujęcia.