음성 메시지, 소설의 한 장, 두 인물의 장면 같은 성인용 대본이 있고, 숨소리와 한숨까지 포함해 작성한 그대로 읽어 주길 원하며 비용도 알고 싶다면, SpicyAPI의 Gemini 2.5 Pro TTS로 가능합니다. SpicyAPI는 콘텐츠 필터를 추가하지 않습니다. 2026년 9월 테스트에서는 성인용 대본이 생략이나 표현 완화, 조기 종료 없이 완전한 오디오로 반환되었습니다.
Playground에서 다음과 같이 시작합니다.
- 분위기에 맞는 Voice를 선택합니다.
Enceladus(숨이 섞인 음성),Achernar(부드러운 음성),Sulafat(따뜻한 음성),Gacrux(성숙한 음성), 또는 기본값Kore(단호한 음성)가 있습니다. - Style을 설정합니다. 친밀한 내용에는 보통
Whisper를 선택합니다. 그런 다음 Delivery instructions 또는 Scene에 상황을 설명하는 한두 문장을 추가합니다. - Text 안에
[sighs]나[laughs]처럼 소리를 대괄호로 표시합니다. 테스트 예시에서는 이 지시가 소리로 표현되었습니다. 지시 자체가 읽힌다면 해당 연기 지시를 Delivery instructions로 옮깁니다. - 인물이 둘이라면 Text 대신 Dialogue와 Speakers를 사용합니다.
먼저 Playground에서 테스트하기
Gemini 2.5 Pro TTS를 열고 Playground 탭의 Form 보기를 사용합니다.
- Text에 대본을 붙여 넣습니다(최대 5,000자). Cues 바로가기는
[whispers],[sighs],[laughs],[gasps],[pause]를 삽입합니다. - Voice를 선택합니다(예:
Enceladus · Breathy). 이어서 Style을Whisper, Pace를Unhurried로 설정하면 느리고 여운이 남는 낭독을 얻을 수 있습니다. - Delivery instructions와 Scene에 한두 문장을 작성합니다. 두 필드 모두 읽히지 않습니다.
- Text 아래에서 길이 기반 예상 비용을 확인하고 Run model을 누른 다음, Output에서 결과를 재생합니다. WAV도 그곳에서 다운로드합니다.
코드를 작성하기 전에 가장 어려운 구절을 여기서 들어 보십시오. Playground에서 소리로 표현되지 않고 읽히는 지시는 API에서도 읽힙니다. 아래 설정에서 각 항목의 역할을 설명합니다.
결과를 바꾸는 설정
voice_id에는 30개의 기본 제공 음성 중 하나를 지정합니다. 기본값은 Kore입니다.
| 분위기 | 들어 볼 음성 |
|---|---|
| 숨이 섞인, 가까운 음성 | Enceladus |
| 부드럽고 다정한 음성 | Achernar, Vindemiatrix |
| 따뜻한 음성 | Sulafat |
| 성숙하고 거친 음성 | Gacrux, Algenib |
| 단호한 음성 | Kore, Orus |
| 밝고 경쾌한 음성 | Puck, Aoede |
네 가지 선택 필드로 연기를 더 조정합니다. 어느 것도 소리 내어 읽히지 않습니다.
style은 전반적인 말투를 설정합니다.whisper,empathetic,vocal_smile,newscaster,promo_hype,deadpan중에서 선택합니다.pace는 리듬을 설정합니다.natural,rapid_fire(빠르고 짧게),the_drift(느리고 여운 있게),staccato(짧고 분리된 구절)가 있습니다. 속도가 느리면 오디오의 초 수가 늘어나며, 요금은 초 단위로 부과됩니다.instructions(최대 1,000자)는 분위기, 마이크와의 거리, 말을 건네는 대상을 자유롭게 설명하는 텍스트입니다. 형용사를 나열하기보다 한두 문장이 더 효과적입니다. 예: "close to the microphone, unhurried, as if speaking only to the listener".scene(최대 500자)은 어디서 누구에게 말하는지 설명합니다. 예: "a quiet hotel room after midnight".
accent(영어 억양 여덟 가지, 영어 대본에만 적용)와 temperature(테이크 간 차이의 정도)는 선택 사항입니다. 변화를 원하기 전까지 지정하지 마십시오. 언어 필드는 없습니다. 모델이 대본의 언어를 감지하며 각 음성은 고유한 특성을 유지합니다.
연기를 이끌어 내는 대본 작성하기
text 안의 짧은 대괄호 지시는 소리를 내거나 말투를 바꿀 위치를 표시합니다. 테스트 예시에서는 [sighs]와 [laughs]가 소리로 표현되었습니다. 긴 구절의 말투는 style: "whisper" 또는 instructions로 지정합니다. 태그가 단어로 읽힌다면 이 필드를 대신 사용하십시오. 말줄임표는 쉼을 암시합니다.
다음 두 습관이 도움이 됩니다.
- 듣기 좋은 글을 씁니다. 말해야 할 내용을 풀어 쓰고, 말줄임표와 쉼표로 쉬는 곳을 표시하며 문장을 짧게 유지합니다.
- 연기 지시는 본문 대신 전용 필드에 씁니다.
text안에 "she whispers breathlessly"라고 쓰면 그 단어들이 읽힙니다.style이나instructions에 넣으십시오.
이어서 코드로 호출하기
이 코드는 작업을 생성하고 완료를 기다린 다음 WAV 링크를 출력합니다(pip install spicyapi를 실행하고 SPICY_API_KEY를 설정합니다).
import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
task = client.create_task(
model="google/gemini-2.5-pro-tts/text-to-speech",
input_data={
"text": "Hey... it is me. [sighs] I know it is late. Stay on the line a little longer?",
"voice_id": "Enceladus",
"style": "whisper",
"pace": "the_drift",
"scene": "A quiet bedroom after midnight, speaking to one listener",
"instructions": "Close to the microphone, unhurried, a little tired.",
},
idempotency_key=str(uuid.uuid4()), # new key per new request; reuse only to retry the same one
)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")
print(output_assets(final)[0]["url"]) # a 24 kHz, 16-bit mono WAV; copy it to your own storage오디오는 14일 동안 보관되며 단어별 시간 정보나 자막은 없습니다. 대기, 재시도, 결과 링크 만료와 오류 처리는 Python SDK 참고 문서, 작업 문서, 보관 정책에 설명되어 있습니다.
또는 Agent에게 실행 맡기기
어시스턴트가 음성 메시지를 생성해야 한다면 CLI 또는 MCP 서버를 제공하십시오. 둘 다 가격을 보여 주고 유료 호출 전에 확인을 요청합니다. Skill은 이 두 방식에 추가 지침을 제공합니다.
- CLI.
spicyapi를 사용합니다(npx @spicyapi/cli는 설치 없이 실행됩니다).input.json에는 위 코드의input객체를 넣습니다.
``bash spicyapi tasks create --model google/gemini-2.5-pro-tts/text-to-speech \ --input-file input.json --wait ``
- MCP 서버. MCP 서버를 추가한 뒤 "Read this script in a whispered Enceladus voice with Gemini 2.5 Pro TTS."라고 요청합니다.
spicyapi_task_create(가격 확인을 위해 멈춥니다)와spicyapi_task_wait를 호출합니다. - Skill.
npx skills add spicyapi-ai/spicy-skill로 Agent Skill을 설치합니다. 코딩 어시스턴트에게 현재 스키마를 읽고 멱등성 키를 재사용하는 방법을 알려 줍니다. 단독으로 작업을 실행할 수 없으므로 CLI 또는 MCP와 함께 사용합니다.
클립 하나에 두 인물 넣기
두 인물의 장면에는 dialogue를 text 대신 보내고(둘 다 보내면 안 됩니다), 배역을 정의하는 speakers도 보냅니다. 각 화자는 대사에서 참조하는 name과 voice_id를 가지며, 자체 accent, style, pace와 누가 말하는지 설명하는 짧은 profile도 설정할 수 있습니다(이 설명은 읽히지 않습니다). 화자가 생략한 값은 최상위 값을 사용합니다. 각 대사는 {speaker, text} 형식이며 순서대로 표현됩니다. 최대 20개 대사, 대사당 250자, 화자는 최대 두 명입니다. 위와 같은 호출에서 input 객체를 다음으로 바꾸십시오.
{
"speakers": [
{ "name": "Mara", "voice_id": "Sulafat", "style": "whisper", "profile": "Warm, close, unhurried" },
{ "name": "Jonah", "voice_id": "Charon", "profile": "Low, amused" }
],
"dialogue": [
{ "speaker": "Mara", "text": "Stay a little longer." },
{ "speaker": "Jonah", "text": "[laughs] You say that every time." },
{ "speaker": "Mara", "text": "And every time you do." }
],
"scene": "A quiet apartment after midnight"
}대화는 믹싱된 WAV 하나로 반환됩니다. 나중에 한 인물의 대사를 따로 편집하려면 각 인물을 별도의 단일 음성 작업으로 생성하고 편집기에서 파일을 연결하십시오. 더 긴 장면, 두 개를 넘는 음성, 참조 클립으로 복제한 음성이 필요하다면 TTS 비교와 Chatterbox 음성 참조 가이드를 확인하십시오.
비용
실제로 반환된 오디오 길이를 파일에서 측정해 초당 $0.00045로 과금합니다. 길이는 음성, 스타일, 속도에 따라 달라집니다. 270자 문단은 23~29초이므로, 대략적인 비용은 글자 수를 10으로 나누고 $0.00045를 곱한 값입니다.
| 클립 길이 | 비용 | 대략적인 텍스트 분량 |
|---|---|---|
| 15초 | $0.0068 | 150자 |
| 30초 | $0.0135 | 300자 |
| 60초 | $0.027 | 600자 |
| 5분 | $0.135 | 3,000자 |
| 7~9분 | $0.19~$0.24 | text 한도인 5,000자 |
작업 실행 중에는 잔액에서 약 $0.30이 임시로 확보됩니다(초당 요율 기준 660초로, 모델이 생성할 수 있는 최장 클립인 약 655초를 충당합니다). 오디오를 측정하면 미사용 금액이 해제됩니다. 실패한 요청은 과금되지 않습니다. 배치를 대기열에 넣기 전에 최소한 이만큼의 잔액을 사용 가능한 상태로 유지하십시오. 앞선 작업의 임시 확보 금액 때문에 다음 작업을 시작하지 못할 수 있습니다.
자주 겪는 문제
- 지시가 단어로 읽힙니다. 문구를 바꾸거나 연기 지시를
style또는instructions로 옮기고 대괄호에는 소리만 남깁니다. - 연기 지시가 무시되는 것 같습니다.
accent는 영어 대본에만 적용됩니다. 최상위style과pace는 자체 값을 지정하지 않은 모든 화자에게 적용됩니다. text와dialogue를 모두 보냈습니다. 하나만 선택하십시오.dialogue에는speakers도 필요합니다.
더 새로운 Gemini 음성을 선택할 때
Gemini 3.8 Flash TTS(초당 $0.00032)와 Gemini 3.8 Flash-Lite TTS(초당 $0.00021)는 dialogue를 포함한 같은 필드를 더 낮은 가격으로 받습니다. Flash-Lite는 일부 대괄호 지시를 그대로 읽는 경향이 있으므로 숨소리와 한숨이 중요하다면 Pro를 선택하십시오. Flash도 보통 대괄호 지시를 소리로 표현하지만, 먼저 짧은 구절을 들어 보십시오. Gemini 3.8 내레이션 가이드에서 두 모델을 자세히 설명합니다.
자주 묻는 질문
Gemini 2.5 Pro TTS는 무검열인가요?
테스트한 성인용 대본은 단어 생략이나 표현 완화 없이 완전하게 반환되었습니다. SpicyAPI는 추가 콘텐츠 필터를 적용하지 않습니다. 대본과 오디오 사용에 대한 책임은 사용자에게 있으며, 실제 사람의 발언으로 제시하지 않는 것도 포함됩니다. 인물은 가상의 성인으로 설정하십시오.
[sighs]나 [laughs] 같은 지시를 소리 내어 읽나요?
테스트한 [sighs]와 [laughs] 예시에서는 소리로 표현했습니다. 다른 지시가 읽힌다면 해당 지시를 instructions로 옮기거나 style을 사용하십시오. 다른 모델은 동작이 다르며, 위 TTS 비교에서 설명합니다.
instructions, scene, style은 어떻게 다른가요?
style은 전반적인 말투를 고르는 고정 목록입니다. instructions는 전달 방식에 대한 자유로운 지시이고, scene은 어디서 누구에게 말하는지 설명합니다. style을 먼저 사용하고 해당 상황에 맞게 instructions나 scene을 추가하십시오.
오디오 1분은 얼마인가요?
약 $0.027이며, 대본 길이가 아니라 반환된 오디오의 초 수로 과금합니다.
음성을 복제할 수 있나요?
이 엔드포인트에서는 불가능합니다. 30개의 기본 제공 음성 중에서 선택하거나 참조 클립을 받는 모델을 사용하십시오.
Playground에서 시작하십시오(먼저 계정을 만드십시오). Enceladus, Whisper, [sighs] 지시 하나가 들어간 짧은 대본으로 지시가 어떻게 반영되는지 확인할 수 있습니다.
