소개
읽을 텍스트와 함께 선택 사항으로 목소리, 억양, 말하기 스타일, 속도, 장면, 연기에 대한 짧은 메모를 보내세요. 대화라면 텍스트 대신 대사와 화자를 보냅니다. 작업은 그 목소리로 대본을 읽은 WAV 파일 하나(24kHz, 16비트 모노)를 반환하며, 대화의 경우 최대 두 개의 목소리를 씁니다. 모델은 쉬운 말로 된 지시(더 천천히, 마이크에 더 가까이, 즐겁게, 지친 듯이 등)를 따르고, [sighs]처럼 대괄호로 된 큐는 소리 내어 읽지 않고 연기합니다. SpicyAPI는 콘텐츠 필터를 적용하지 않으며, 모든 대본은 적힌 그대로 읽힙니다. 과금은 반환된 오디오의 초 단위입니다.
| 항목 | 값 |
|---|---|
| 입력 | 텍스트 |
| 출력 | 오디오 |
| 필수 필드 | text(1~5,000자) 또는 dialogue(최대 20줄) |
| 선택 필드 |
|
| 결과 | WAV 파일 하나(24kHz, 16비트, 모노) |
| 최장 음성 길이 | 약 655초(오디오 토큰 16,384개) |
| 과금 기준 | 돌려받은 음성의 초 수(파일에서 측정) |
| 보관 기간 | 생성한 음성은 14일간 보관 |
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
text | 아니요 | 말할 내용을 쓴 그대로 넣습니다. [sighs] 같은 대괄호 지시는 읽지 않고 연기로 표현됩니다. 1자 이상 · 5000자 이하 |
dialogue | 아니요 | text 대신 쓰는, 최대 두 목소리의 대본 대화입니다. 최대 20줄이며 각 줄에 speaker(speakers에 있는 이름)와 250자 이내의 text를 지정합니다. 1개 이상 · 20개 이하 |
speakers | 아니요 | dialogue의 배역입니다. 한두 명을 지정하며, 각자에 줄에서 참조하는 name과 |
voice_id | 아니요 | 기본 제공 보이스 30종 중 하나이며, 보이스마다 음색이 정해져 있습니다. 기본값은 Kore입니다. |
style | 아니요 | 전체 말투입니다. 비워 두면 보이스 고유의 말투로 읽습니다. |
pace | 아니요 | 낭독의 리듬입니다. natural, |
accent | 아니요 | 읽을 때 쓰는 영어 억양입니다. 기본값은 neutral입니다. |
instructions | 아니요 | 읽는 방식에 대한 자유 형식 지시입니다. 속도, 분위기, 마이크와의 거리, 듣는 사람 등을 적습니다. 1000자 이하 |
scene | 아니요 | 어디서 누구에게 하는 말인지에 대한 설명입니다(예: ‘자정이 지난 조용한 호텔 방’). 연기 방식에 반영되며 읽히지 않습니다. 500자 이하 |
temperature | 아니요 | 테이크 간의 변화를 0부터 2까지로 지정합니다. 값이 클수록 연기가 덜 예측 가능해집니다. |
요금
$0.00045 / 초
돌려받은 음성의 초 수로 과금합니다. 작업 중에는 660초만큼을 임시로 확보하고, 음성을 측정하면 쓰지 않은 부분을 해제합니다.
활용 사례
오디오북과 긴 내레이션
챕터 단위의 이야기, 잠자리 동화, 연재 소설을 안정적인 내레이터 목소리로 읽습니다. 보이스는 한 번 정하면 계속 유지하는 것이 좋습니다. 같은 보이스와 같은 연출 메모를 쓰면 챕터가 바뀌어도 음색이 일관됩니다.
캐릭터와 컴패니언 음성
채팅 캐릭터에게 고유한 목소리를 줄 수 있습니다. 속삭이는 말투와 짧은 연출 메모를 더하면 밋밋한 텍스트가 한 사람에게 건네는 대사처럼 들립니다.
무검열 오디오 스토리
대본은 콘텐츠 필터 없이 적힌 그대로 읽힙니다. 저희 테스트에서 모델은 1인칭 대사와 서술 장면을 가리지 않고 모든 단어를 말했고, 단어를 건너뛰거나 클립을 중간에 끝내지 않았습니다.
영상용 보이스 트랙
여기서 대사를 만든 뒤 WAV를 토킹 아바타나 립싱크 모델에 넘기면 얼굴 영상이 그 대사를 연기합니다. 다음 단계 영상의 길이는 음성 길이로 정해집니다.
프롬프트 가이드 및 실전 팁
대본을 text에 넣기
말해야 하는 그대로 쓰고, 쉬어야 할 곳에는 문장 부호를 넣으세요. 최대 5,000자입니다.
보이스를 고르고, 필요하면 말투와 억양 지정하기
voice_id의 기본값은 Kore, accent의 기본값은 neutral입니다. 속삭임처럼 특정한 말투가 필요할 때만 style을 지정하세요.
instructions로 읽는 방식 연출하기
형용사를 나열하기보다 속도, 분위기, 듣는 사람을 한두 문장으로 적는 편이 더 잘 전달됩니다. 이 메모는 소리 내어 읽히지 않습니다.
돌려받는 결과
작업마다 WAV 파일 하나를 돌려받습니다. 형식은 24kHz, 16비트, 모노 PCM입니다. 파일은 SpicyAPI 스토리지에 복사되어 14일간 보관됩니다. 결과에는 단어별 타이밍이나 자막이 포함되지 않습니다.
보이스 고르기
voice_id에는 기본 제공 보이스 30종 중 하나를 지정하며, 기본값은 Kore입니다. 보이스마다 음색이 정해져 있습니다. 예를 들어 Kore는 단단한 목소리, Charon은 설명에 어울리는 목소리, Puck은 경쾌한 목소리, Enceladus는 숨결이 섞인 목소리, Achernar는 부드러운 목소리, Algenib는 거친 목소리, Sulafat는 따뜻한 목소리, Gacrux는 성숙한 목소리입니다. 대본의 언어가 바뀌어도 보이스는 바뀌지 않습니다.
읽는 방식 연출
style은 전체 말투입니다.whisper,empathetic,vocal_smile,newscaster,promo_hype,deadpan중에서 고릅니다. 생략하면 보이스 고유의 말투로 읽습니다.accent는 영어 억양이며 기본값은neutral입니다.pace는 리듬이며natural,rapid_fire,the_drift,staccato중에서 고릅니다.instructions에는 속도, 분위기, 마이크와의 거리, 말하는 대상 등 읽는 방식을 자유롭게 적습니다.scene에는 어디서 누구에게 하는 말인지 적습니다. 둘 다 읽히지 않습니다.temperature(0~2)로 테이크 간 낭독이 얼마나 달라지는지 정합니다.text안의[sighs]나[whispering]같은 대괄호 지시는 읽히지 않고 연기됩니다.
한 클립에 두 목소리
대화라면 text 대신 dialogue를 보내고, 배역은 speakers에 넣습니다. 한두 명을 지정하며 각자에 name, voice_id, 그리고 선택으로 accent, style, pace, profile(말하는 사람에 대한 짧은 설명이며 읽히지 않습니다)을 설정합니다. dialogue의 각 줄은 {speaker, text}이며 speaker에는 그 이름 중 하나를 씁니다. 줄은 순서대로 연기되며 줄당 250자, 최대 20줄입니다. 화자가 비워 둔 설정에는 최상위 accent, style, pace가 쓰입니다. 대화 전체는 WAV 파일 하나로 돌아오며, 다른 요청과 마찬가지로 초 단위로 과금됩니다.
길이와 소요 시간
text는 최대 5,000자입니다. 자체 테스트에서 270자 문단은 보이스와 말투에 따라 23~29초 길이의 음성이 되었습니다. 모델은 오디오 토큰 16,384개, 약 655초에서 출력을 멈춥니다. 대부분의 작업은 1분 안에 끝납니다.
과금
돌려받은 음성의 초 수로 과금하며, 초 수는 파일에서 측정합니다. 작업이 진행되는 동안에는 모델이 만들 수 있는 가장 긴 음성인 660초만큼을 잔액에서 임시로 확보하고, 정산할 때 쓰지 않은 부분을 해제합니다. 실패한 요청에는 과금하지 않습니다.
콘텐츠
SpicyAPI는 콘텐츠 필터를 추가하지 않습니다. 저희 테스트에서 다른 서비스가 거절하는 대본도 한 단어씩 전부 읽혔고, 건너뛴 단어도 중간에 끊긴 클립도 없었습니다.
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-2.5-pro-tts/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"accent": "neutral",
"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 레퍼런스에서 확인하세요.
