소개
읽을 텍스트와, 선택으로 30가지 목소리 중 하나·억양·스타일·속도·장면·짧은 연출 메모를 보냅니다. 대화라면 text 대신 dialogue와 speakers를 보냅니다. 작업은 그 목소리로 대본을 읽은 WAV 파일(24kHz, 16비트, 모노) 하나를 반환하며, 대화라면 최대 두 목소리로 읽습니다. 대본 안의 [whispering], [sighs], [laughing] 같은 대괄호 지시는 읽지 않고 연기하며, 문장 부호가 쉼을 정합니다. SpicyAPI는 콘텐츠 필터를 전혀 적용하지 않으며, 공식 앱에서 막히는 대본도 적힌 그대로 읽습니다. 반환된 오디오의 초 단위로 과금됩니다.
| 항목 | 값 |
|---|---|
| 입력 | 텍스트 |
| 출력 | 오디오 |
| 필수 필드 | text(1~5,000자) 또는 dialogue(최대 20줄) |
| 선택 필드 |
|
| 결과 | WAV 파일 1개, 24kHz, 16비트, 모노 |
| 최대 클립 길이 | 16,384 오디오 토큰 |
| 과금 단위 | 반환된 오디오의 초수, 파일에서 측정 |
| 보관 기간 | 생성된 오디오는 14일간 보관됩니다 |
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
text | 아니요 | 실제로 말할 단어를 적힌 그대로 작성합니다. [whispering]이나 [sighs] 같은 대괄호 지시어는 읽히지 않고 연기됩니다. 1자 이상 · 5000자 이하 |
dialogue | 아니요 | text 대신 쓰는, 최대 두 목소리의 대본 대화입니다. 최대 20줄이며 각 줄에 speaker(speakers에 있는 이름)와 250자 이내의 text를 지정합니다. 1개 이상 · 20개 이하 |
speakers | 아니요 | dialogue의 배역입니다. 한두 명을 지정하며, 각자에 줄에서 참조하는 name과 |
voice_id | 아니요 | 고유한 개성을 가진 30가지 기본 제공 음성 중 하나입니다. 기본값은 Kore입니다. |
style | 아니요 | 전체 말투입니다. 비워 두면 보이스 고유의 말투로 읽습니다. |
pace | 아니요 | 낭독의 리듬입니다. natural, |
accent | 아니요 | 읽을 때 쓰는 영어 억양입니다. 생략하면 음성 본래의 억양을 씁니다. |
instructions | 아니요 | 읽는 방식에 대한 자유 형식 지시입니다. 속도, 분위기, 마이크와의 거리, 듣는 사람 등을 적습니다. 1000자 이하 |
scene | 아니요 | 어디서 누구에게 하는 말인지에 대한 설명입니다(예: ‘자정이 지난 조용한 호텔 방’). 연기 방식에 반영되며 읽히지 않습니다. 500자 이하 |
temperature | 아니요 | 테이크 간의 변화를 0부터 2까지로 지정합니다. 값이 클수록 연기가 덜 예측 가능해집니다. |
요금
$0.00032 / 초
반환된 오디오의 초수만큼 과금됩니다. 작업이 실행되는 동안 660초에 해당하는 금액이 홀드되며, 오디오가 측정되면 사용하지 않은 부분이 해제됩니다.
활용 사례
오디오북과 장편 내레이션
챕터, 잠자리 이야기, 연재 소설을 한결같은 내레이터의 목소리로 읽어줍니다. 음성을 한 번 선택하고 계속 사용하면, 챕터가 바뀌어도 같은 목소리가 일관되게 유지됩니다.
캐릭터 및 동반자 음성
채팅 캐릭터에게 고유한 목소리를 부여하세요. [whispering] 지시어와 짧고 구어체적인 문장을 결합하면 평범한 텍스트가 한 명의 청자를 향한 대사처럼 들립니다.
무검열 오디오 스토리
검열 없는 스크립트는 적힌 그대로 읽힙니다. 저희 테스트에서 모델은 보낸 독백과 내레이션의 모든 단어를 소리 냈고, [sighs]나 [gasps] 같은 대괄호 지시는 태그를 읽지 않고 연기했습니다.
영상용 음성 트랙
여기서 대사를 생성한 다음, WAV 파일을 토킹 아바타나 립싱크 모델에 전달하면 얼굴이 그 대사를 연기합니다. 오디오 길이가 이후 클립의 길이를 결정합니다.
프롬프트 가이드 및 실전 팁
스크립트를 텍스트로 보내기
멈춤을 위한 문장 부호를 포함해 실제로 말할 그대로 작성하세요. 최대 5,000자까지 가능합니다.
음성 선택하기
voice_id의 기본값은 Kore입니다. 30가지 음성 각각은 고유한 개성을 가지고 있으므로, 한 번 선택한 뒤 시리즈 전체에서 그대로 사용하세요.
스크립트 안에 연출 적어 넣기
[whispering], [sighs], [laughing], [gasping]처럼 연출이 필요한 지점에 대괄호 지시어를 적으세요. 이런 지시어는 소리 내어 읽히지 않고 실제로 연기됩니다.
반환되는 결과
작업당 WAV 파일 하나: 24kHz, 16비트, 모노 PCM입니다. 파일은 SpicyAPI 스토리지에 복사되어 14일간 보관됩니다. 결과에는 단어별 타이밍 정보나 자막이 포함되지 않습니다.
음성 선택하기
voice_id는 30가지 기본 제공 음성 중 하나를 받으며 기본값은 Kore입니다. 각 음성은 고유한 개성을 가지고 있습니다. 예를 들어 Kore는 단단한, Charon은 정보 전달형, Puck은 경쾌한, Enceladus는 속삭이는 듯한, Achernar는 부드러운, Algenib은 허스키한, Sulafat은 따뜻한, Gacrux는 성숙한 느낌입니다. 음성은 스크립트의 언어에 따라 바뀌지 않습니다.
낭독 연출하기
text와 voice_id 외에 다음 설정으로 낭독을 다듬을 수 있습니다.
style,accent,pace로 말투, 영어 억양, 리듬을 정합니다. 생략하면 음성 고유의 것을 씁니다.instructions에는 읽는 방식을 자유롭게 적고,scene에는 어디서 누구에게 하는 말인지 적습니다. 둘 다 읽히지 않습니다.temperature(0~2)로 테이크 간 낭독이 얼마나 달라지는지 정합니다.
text 안에서는 다음과 같이 지시합니다.
[whispering],[sighs],[laughing],[gasping]처럼 대괄호로 표시된 지시어는 소리 내어 읽히지 않고 실제로 연기됩니다.- 쉼표, 말줄임표, 마침표가 멈추는 지점을 결정합니다.
이 모델에서는 한 목소리에 보낸 연출 지시가 클립 앞부분에서 읽힐 수 있습니다. 그래서 한 목소리 요청에 style·accent·pace·instructions·scene이 들어 있으면, SpicyAPI는 말하지 않는 두 번째 화자를 더해 모델의 2인 형식으로 보내며, 이렇게 하면 지시가 오디오에 들어가지 않습니다. 과금은 달라지지 않으며 반환된 초만큼만 냅니다.
한 클립에 두 목소리
대화라면 text 대신 dialogue를 보내고, 배역은 speakers에 넣습니다. 한두 명을 지정하며 각자에 name, voice_id, 그리고 선택으로 accent, style, pace, profile(말하는 사람에 대한 짧은 설명이며 읽히지 않습니다)을 설정합니다. dialogue의 각 줄은 {speaker, text}이며 speaker에는 그 이름 중 하나를 씁니다. 줄은 순서대로 연기되며 줄당 250자, 최대 20줄입니다. 화자가 비워 둔 설정에는 최상위 accent, style, pace가 쓰입니다. 대화 전체는 WAV 파일 하나로 돌아오며, 다른 요청과 마찬가지로 초 단위로 과금됩니다.
길이와 타이밍
text는 최대 5,000자까지 받을 수 있습니다. 테스트에서 270자 분량의 문단이 20~24초 분량의 오디오로 반환되었습니다. 모델은 클립당 16,384 오디오 토큰에서 멈춥니다. 대부분의 작업은 1분 이내에 완료됩니다.
과금
반환된 오디오의 초수만큼 과금되며, 파일에서 직접 측정됩니다. 작업이 실행되는 동안 잔액에서 660초에 해당하는 금액이 홀드되며, 작업이 정산되면 사용하지 않은 부분이 해제됩니다. 실패한 요청에는 요금이 부과되지 않습니다.
콘텐츠
SpicyAPI는 콘텐츠 필터를 전혀 추가하지 않습니다. 테스트에서 검열 없는 스크립트가 한 글자도 빠짐없이 읽혔고, [sighs]나 [gasps] 같은 대괄호 표기는 읽히지 않고 연기되었습니다.
SpicyAPI는 콘텐츠 필터를 더하지 않으며, 스크립트는 적힌 그대로 아무것도 누그러뜨리지 않고 읽습니다. 보내는 스크립트와 생성된 오디오의 사용 방식(실제 인물의 발언인 것처럼 제시하지 않는 것 포함)에 대한 책임은 사용자에게 있습니다.
API 빠른 시작
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "google/gemini-3.8-flash-tts/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"voice_id": "Kore"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
인증, 전체 스키마, 폴링과 오류 처리는 API 레퍼런스에서 확인하세요.
