Grok STT·TTS API: 전사, 내레이션, 다운로드

기존 녹음을 전사할 때는 Grok STT, 대본을 프리셋 목소리로 읽게 할 때는 Grok TTS를 쓰세요. 먼저 SpicyAPI Playground에서 둘 다 써 본 뒤 코드나 에이전트로 호출하면 됩니다. 저장된 파일을 다루는 워크플로이며, 실시간 음성 대화에는 실시간 전송 방식이 필요합니다. STT는 오디오 1분당 약 0.002달러, TTS는 1,000자당 0.018달러입니다. 2026년 9월 테스트에서 두 경로 모두 성인용 녹음과 대본을 쓰인 그대로 처리했고, 거부나 마스킹, 중간에 잘린 클립은 없었습니다.

요금, 한도, 각 경로가 반환하는 것

더 길거나 큰 녹음에는 공개 URL이 필요합니다. URL은 M4A, FLAC, OGG, Opus, AAC, MP4, MKV도 가리킬 수 있지만, 플레이어나 공유 페이지가 아니라 오디오 파일 자체를 반환해야 합니다. STT는 헤더 없는 PCM, μ-law, A-law를 받지 않습니다.

오디오 1시간은 약 0.12달러, 90초 녹음은 약 0.003달러입니다. 작업은 먼저 최대치인 2시간분, 약 0.24달러를 잡아 두었다가 실제 길이가 확정되면 차액을 해제합니다. 1,800자 대본은 0.0324달러이고, 전체 테이크 두 번과 240자 보충 녹음은 0.06912달러입니다. 공백, 문장부호, 낭독 태그도 모두 글자 수에 포함되며, TTS 실행 전에 표시되는 견적이 최종 청구액입니다.

먼저 Playground에서 써 보기

전사. Grok STT 페이지를 열고 Playground 탭에 머무르세요.

1. Input audio에서 MP3 또는 WAV(90 MB까지)를 업로드하거나, Asset URL로 바꾸고 Add URL을 눌러 다른 곳에 있는 녹음을 지정합니다.
2. Language, Normalize text, Key terms, Keep filler words, Transcribe channels separately가 필요할 때만 Advanced parameters를 엽니다.
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)는 지어낸 이름이나 브랜드의 철자를 유도하며, 용어당 50자, 최대 100개입니다. 단순 문자열이 아니라 [{"term":"Mara"},{"term":"Jon"}]처럼 객체로 보내세요.

Transcribe channels separately(multichannel: true)는 파일의 각 채널을 따로 전사합니다(최대 8개). 꺼 두면 좌우에 다른 화자가 있는 스테레오 녹음에서 한쪽 화자가 빠진 채 돌아올 수 있습니다. 각 채널의 단어와 시간은 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을 설치하면 코딩 어시스턴트가 최신 스키마를 읽고 멱등성 키를 재사용하도록 배웁니다. 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를 쓰세요. 8 kHz의 원시 pcm, mulaw, alaw는 전화 시스템용이며 브라우저에서 재생되지 않습니다. SSML은 지원하지 않으니 위의 태그를 쓰세요.

등장인물이 둘인 장면은 화자별 대사를 서로 다른 목소리로 따로 합성해서 편집으로 이어 붙이세요. 한 번의 요청은 하나의 목소리만 읽습니다. 이음매의 자연스러운 간격은 0으로 자르지 말고 남겨 두세요.

테이크를 점검하려면 생성된 오디오를 다시 STT에 넣어 대본과 비교하세요. 빠지거나 바뀐 단어, 끝부분이 잘린 것, 소리 내어 읽힌 태그는 대개 드러나고, 짧은 클립이라면 비용은 1센트의 일부입니다. 그런 다음 시작 부분, 끝부분, 표시된 줄을 직접 들어 보세요. Grok 프리셋으로 부족하다면 모델 목록에 다른 음성 옵션이 있습니다. 비교 글 "Uncensored text-to-speech APIs compared"는 아직 영어로만 제공됩니다.

흔한 문제와 해결

STT의 단어 타임스탬프는 원본 녹음에 속합니다. TTS는 단어별 시간 없이 오디오를 반환하므로 텍스트나 속도를 바꾸면 이전 타임스탬프는 무효가 됩니다. 자막은 완성된 합성 테이크에 맞춰 다시 정렬하세요.