소개
읽을 텍스트, 시스템 목소리, 감정, 그리고 선택 사항으로 언어 힌트를 보냅니다. 작업은 그 목소리와 감정으로 대본을 읽은 오디오 파일 하나를 반환합니다. output_format, sample_rate, bitrate, audio_channels를 설정하지 않으면 32kHz 모노 MP3입니다. speed, pitch, volume으로 전달 방식을 조절하고, pronunciation_dict로 특정 단어의 읽는 법을 고정할 수 있습니다. 텍스트에 넣은 (sighs)나 (laughs) 같은 괄호 사운드 태그는 소리 내어 읽지 않고 소리로 연기합니다. SpicyAPI는 콘텐츠 필터를 적용하지 않으며, 모든 대본은 적힌 그대로 읽힙니다. 과금은 보내는 텍스트 1,000자 단위입니다.
| 항목 | 값 |
|---|---|
| 입력 | 텍스트 |
| 출력 | 오디오 |
| 필수 필드 | text — 1~5,000자 |
| 선택 필드 |
|
| 결과 | 오디오 파일 1개(기본값 MP3·32kHz·모노, WAV·FLAC·PCM 가능) |
| 과금 수량 | 전송한 text의 글자 수(1,000자당) |
| 일반적인 소요 시간 | 300자 기준 약 8초 |
| 보관 기간 | 생성된 오디오는 14일간 보관됩니다 |
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
text | 예 | 실제로 말할 단어를 적힌 그대로 지정합니다. (sighs)나 (laughs) 같은 괄호 태그는 소리로 연기되며 소리 내어 읽히지 않습니다. 1자 이상 · 5000자 이하 |
voice_id | 아니요 | 472종의 시스템 보이스 중 하나입니다. 기본값은 Calm_Woman입니다. |
emotion | 아니요 | neutral, happy, sad, angry, fearful, disgusted, surprised 중 하나의 고정된 감정으로, 읽기 전체에 적용됩니다. 기본값은 neutral입니다. |
speed | 아니요 | 말하는 속도를 0.5(느리게)부터 2(빠르게)까지로 지정합니다. 1이 음성의 보통 속도입니다. |
pitch | 아니요 | 음높이를 반음 단위로 -12부터 12까지 이동합니다. 0이면 음성 본래의 높이를 유지합니다. |
volume | 아니요 | 음량 배율을 0.1부터 10까지로 지정합니다. 1이 보통 음량입니다. |
language | 아니요 | 40개 언어 중 하나에 대해 발음을 개선하는 힌트입니다. 기본값은 auto이며, 대본에서 언어를 자동으로 감지합니다. |
output_format | 아니요 | 파일 형식입니다. mp3(기본값), wav, flac, pcm 중에서 고릅니다. |
sample_rate | 아니요 | 오디오의 샘플링 레이트(Hz)입니다. 8000, 16000, 22050, 24000, 32000, 44100 중에서 고릅니다. |
bitrate | 아니요 | MP3 비트레이트(초당 비트)입니다. 32000, 64000, 128000, 256000 중에서 고릅니다. |
audio_channels | 아니요 | 출력 채널입니다. mono(기본값) 또는 stereo를 고릅니다. |
english_normalization | 아니요 | 켜면 영어 텍스트의 숫자·날짜·약어를 사람이 말하듯 읽습니다(1990을 ‘nineteen ninety’로 읽는 식). 기본값은 꺼짐입니다. 기본값: |
pronunciation_dict | 아니요 | {alias, pronunciation} 쌍을 최대 100개까지 지정합니다. text 안의 alias는 모두 pronunciation으로 읽힙니다. 100개 이하 |
요금
$0.12 / 1,000자
전송한 텍스트 1,000자마다 과금되며, 공백과 문장 부호도 글자 수에 포함됩니다. 실행 전에 표시되는 견적이 최종 가격입니다.
활용 사례
짧은 영상용 보이스오버
설명 영상, 제품 클립, 소셜 게시물용 내레이션입니다. 가격은 대본 길이로 정해지므로 시작 전에 배치 비용을 알 수 있습니다.
다국어 콘텐츠
language에 지원되는 40개 언어 중 하나를 지정해 같은 대본을 읽거나, auto로 두어 대본이 판단하게 할 수 있습니다.
무검열 오디오 스토리
대본은 콘텐츠 필터 없이 적힌 그대로 읽힙니다. 저희 테스트에서 모델은 다른 서비스가 거절하는 독백과 서술 장면을 한 단어도 빠짐없이 말했고, 숨소리나 음향 큐는 소리 내어 읽지 않고 연기했습니다.
감정이 담긴 캐릭터 연기
요청마다 happy, sad, angry, fearful, disgusted, surprised 중 하나의 감정을 설정하고, 대본 속 (sighs), (laughs), (breath) 태그가 연기를 이끌게 하세요.
프롬프트 가이드 및 실전 팁
대본을 text로 전송하기
쉼과 문장 부호를 포함해 실제로 말해야 할 그대로 작성하고, 연기되길 원하는 부분에는 (sighs)처럼 괄호로 사운드 태그를 넣으세요. 최대 5,000자까지 지원합니다.
보이스와 감정 선택하기
voice_id의 기본값은 Calm_Woman이며, emotion의 기본값은 neutral로 7가지 고정 값 중 하나를 사용합니다.
필요하면 언어 힌트 추가하기
language를 auto로 두면 대본에서 자동으로 감지되며, 짧거나 여러 언어가 섞인 대본의 발음을 보완하려면 40개 언어 중 하나를 지정하세요.
반환되는 내용
작업마다 오디오 파일 1개를 반환합니다. output_format, sample_rate, bitrate, audio_channels를 바꾸지 않으면 32kHz 모노 MP3입니다. 파일은 SpicyAPI 스토리지에 복사되어 14일간 보관됩니다.
보이스 선택하기
voice_id는 Calm_Woman, Deep_Voice_Man, Lively_Girl, Elegant_Man 등 472종의 시스템 보이스 중 하나를 지정할 수 있으며 기본값은 Calm_Woman입니다. 클로닝이나 참조 음성 업로드는 지원하지 않습니다.
감정 설정하기
emotion은 neutral, happy, sad, angry, fearful, disgusted, surprised 중 하나의 고정 값을 지정할 수 있으며, 읽기 전체에 적용됩니다. 기본값은 neutral입니다.
사운드 태그
text 안에 괄호로 넣은 태그((sighs), (laughs), (breath), (gasps) 등)는 소리 내어 읽히지 않고 소리로 연기됩니다. 저희 테스트에서 이는 다른 서비스가 거절하는 대본에서도, 평범한 대본에서도 그대로였습니다.
언어
언어는 대본에서 자동으로 감지됩니다. language로 표준 중국어, 광둥어, 영어, 아랍어, 러시아어, 스페인어, 프랑스어, 포르투갈어, 독일어, 일본어, 이탈리아어, 한국어, 폴란드어 등 40개 언어 중 하나를 힌트로 지정해 짧거나 여러 언어가 섞인 대본의 발음을 개선할 수 있습니다.
읽는 방식 조절
speed(0.52), 12 반음), pitch(-12volume(0.1~10)으로 가격 변동 없이 읽는 방식을 조절합니다. pronunciation_dict에는 {alias, pronunciation} 쌍을 최대 100개까지 넣을 수 있어, 이름·약어·외래어를 항상 원하는 대로 읽게 할 수 있습니다(일반 단어나 괄호로 감싼 IPA). english_normalization을 켜면 영어 텍스트의 숫자·날짜·약어를 사람이 말하듯 읽습니다.
출력 형식
output_format으로 mp3(기본값), wav, flac, pcm을 고릅니다. sample_rate는 8000~44100Hz, bitrate는 MP3 비트레이트, audio_channels는 스테레오 전환입니다. pcm은 헤더 없는 16비트 리틀 엔디언 원시 샘플이라 브라우저에서 재생할 수 없습니다. 같은 샘플을 재생 가능한 파일로 받으려면 wav를 고르세요.
과금
text의 공백, 문장 부호, 줄바꿈을 포함해 1,000자마다 과금됩니다. 글자 수는 작업 시작 전에 확정되므로 견적이 곧 최종 청구 금액입니다. 실패한 요청에는 과금되지 않습니다.
콘텐츠
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": "minimax/speech-2.8-hd/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"emotion": "neutral",
"language": "auto",
"voice_id": "Calm_Woman",
"output_format": "mp3"
}
}'
# 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 레퍼런스에서 확인하세요.
