> ## Documentation Index > Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Gemini TTS > gemini-3.8-flash-tts / gemini-3.1-flash-tts-preview 음성 합성 및 음성 라이브러리 조회 이 페이지는 [오디오 (Audio)](/ko/api-reference/endpoint/audio) 페이지의 Gemini 네이티브 형식을 확장하며, 차세대 TTS 모델을 다룹니다. ## 인증 ``` Authorization: Bearer sk-xxxxxxxxxx ``` ## Gemini 네이티브 형식 (TTS) ``` POST https://api.gravitex.ai/v1beta/models/{model}:generateContent ``` `{model}`은 `gemini-3.8-flash-tts` 또는 `gemini-3.1-flash-tts-preview`입니다. ### gemini-3.8-flash-tts ```bash theme={null} curl "https://api.gravitex.ai/v1beta/models/gemini-3.8-flash-tts:generateContent" \ -H "Authorization: Bearer sk-xxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "오늘의 기술 아침 뉴스를 시작합니다.첫 번째 소식입니다. 연구진이 상온 초전도 소재에서 획기적인 성과를 발표했습니다.", "speech_metadata": { "speaker": "Host", "style": "뉴스 방송, 또렷하고 열정적으로" } } ] } ], "generationConfig": { "responseModalities": ["AUDIO"], "speechConfig": { "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } } } }' ``` ### gemini-3.1-flash-tts-preview ```bash theme={null} curl "https://api.gravitex.ai/v1beta/models/gemini-3.1-flash-tts-preview:generateContent" \ -H "Authorization: Bearer sk-xxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "밝은 어조로 말해 주세요: 오늘도 좋은 하루 보내세요!" } ] } ], "generationConfig": { "responseModalities": ["AUDIO"], "speechConfig": { "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } } } }' ``` ### 응답 ```json theme={null} { "candidates": [ { "content": { "role": "model", "parts": [ { "inlineData": { "mimeType": "audio/wav", "data": "UklGRi4..." } } ] }, "finishReason": "STOP" } ], "usageMetadata": { "promptTokenCount": 5, "candidatesTokenCount": 1680, "totalTokenCount": 1685, "candidatesTokensDetails": [ { "modality": "AUDIO", "tokenCount": 1680 } ] }, "modelVersion": "gemini-3.8-flash-tts", "responseId": "xxxx", "createTime": "2026-10-10T10:00:00Z" } ``` | 필드 | 설명 | | - | - | | `candidates[].content.parts[].inlineData.mimeType` | 오디오 형식, 아래 처리 표 참조 | | `candidates[].content.parts[].inlineData.data` | base64 오디오 | | `candidates[].finishReason` | `STOP`(정상 종료) 또는 기타 중단 사유 | | `usageMetadata.promptTokenCount` | 텍스트 입력 토큰(과금 기준) | | `usageMetadata.candidatesTokenCount` | 오디오 출력 토큰(과금 기준) | | `usageMetadata.totalTokenCount` | 합계 | | `usageMetadata.candidatesTokensDetails[].modality` | 모달리티별 내역, 오디오 출력은 `AUDIO` | | `modelVersion` / `responseId` / `createTime` | 실제 모델 버전 / 요청 ID / 시간 | ### 응답 처리 오디오는 `candidates[0].content.parts[0].inlineData`로 반환됩니다: ```bash theme={null} echo "" | base64 --decode > out.wav ``` | 모델 | mimeType | 처리 방법 | | - | - | - | | gemini-3.8-flash-tts | `audio/wav` | 디코딩하면 바로 재생 가능한 완전한 WAV | | gemini-3.1-flash-tts-preview | `audio/l16;codec=pcm;rate=24000` | 순수 PCM이므로 WAV 헤더를 추가해야 함. 실제 파라미터는 응답의 `mimeType`을 따름 | 3.1용 WAV 헤더 추가(Python, 샘플링 레이트는 응답의 `mimeType`에서 파싱하고 하드코딩하지 마세요): ```python theme={null} import base64, json, struct resp = json.load(open("response.json")) inline = resp["candidates"][0]["content"]["parts"][0]["inlineData"] pcm = base64.b64decode(inline["data"]) # mimeType 예: audio/l16;codec=pcm;rate=24000, rate=에서 파싱 rate = 24000 for part in inline["mimeType"].split(";"): if part.strip().startswith("rate="): rate = int(part.strip()[5:]) header = (b"RIFF" + struct.pack("`, ``, ``, ``, ``. **멀티턴:** 3.8은 긴 멀티턴 대화를 안정적으로 지원하며, 3.1은 단일 턴만 지원합니다. `contents`에는 user 턴이 하나만 있어야 하며 여러 턴이면 `Multiturn chat is not enabled for this model`이 반환됩니다. 멀티턴이 필요하면 `gemini-3.8-flash-tts`를 사용하세요. **다중 화자(3.8):** 각 part에 `speech_metadata.speaker`를 지정하며, 화자는 `speechConfig`에 설정된 화자와 일치해야 합니다: ```json theme={null} { "contents": [ { "role": "user", "parts": [ { "text": "오늘 밤 주제는 인공지능 안전입니다.", "speech_metadata": { "speaker": "Alice", "style": "차분한 진행자" } }, { "text": "결론부터 말씀드리면,가장 큰 위험은 배포 단계에 있습니다.", "speech_metadata": { "speaker": "Bob", "style": "경쾌한 학자" } } ] } ], "generationConfig": { "responseModalities": ["AUDIO"], "speechConfig": { "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Puck" } } } } } ``` ## 음성 라이브러리 조회 ``` GET https://api.gravitex.ai/v1beta/voices?model={model} ``` 사용 가능한 음성(프리빌트 / 확장 음성 라이브러리)을 조회합니다. `?model=`로 지정한 모델에 따라 채널이 라우팅됩니다. 조회는 과금되지 않습니다. ### 요청 파라미터 | 파라미터 | 필수 | 설명 | | - | - | - | | `model` | 예 | 모델 이름, 예: `gemini-3.8-flash-tts` | | `language_code` | 아니요 | 언어별 필터, 반복 가능, 예: `zh-CN`, `en-US`, `ar-EG` | | `gender` | 아니요 | `female` / `male` | | `pitch` | 아니요 | `low` / `medium` / `high` | | `context` | 아니요 | 적용 시나리오별 필터, 응답의 `context` 필드와 대응: `Content & Media`, `Conversational / Edu`, `Enterprise Agent`, `Growth & Marketing`, `Entertainment & Gaming`, `Wellness & Culture` | | `type` | 아니요 | `prebuilt`(프리빌트) 등 | | `search` | 아니요 | 음성 특징 자유 텍스트 검색, 예: `warm` | | `page_size` | 아니요 | 페이지 크기, 기본값 50 | | `page_token` | 아니요 | 페이지 토큰, 이전 응답의 `next_page_token` 사용 | ### 요청 예시 ```bash theme={null} curl -G "https://api.gravitex.ai/v1beta/voices?model=gemini-3.1-flash-tts-preview" \ -H "Authorization: Bearer sk-xxxxxxxxxx" \ --data-urlencode "language_code=zh-CN" \ --data-urlencode "gender=female" \ --data-urlencode "search=warm" ``` ### 응답 ```json theme={null} { "voices": [ { "id": "achernar", "type": "VOICE_TYPE_PREBUILT", "display_name": "Achernar", "language_code": "en-US", "region_code": "US", "accent": "General American", "persona": "Storyteller & Narrator", "context": "Content & Media", "gender": "female", "pitch": "PITCH_HIGH", "description": "Soft, calm, and soothing voice with a higher pitch. Recommended for quiet or personal storytelling." }, { "id": "achird", "type": "VOICE_TYPE_PREBUILT", "display_name": "Achird", "language_code": "en-US", "region_code": "US", "accent": "General American", "persona": "Companion & Peer", "context": "Conversational / Edu", "gender": "male", "pitch": "PITCH_LOW", "description": "Friendly, approachable, and warm voice with a lower-middle pitch. Recommended for casual walkthroughs or vlogs." } ], "next_page_token": "achird|en-US" } ``` | 필드 | 설명 | | - | - | | `id` | 음성 ID, `voiceName`에 입력하여 사용 | | `type` | 음성 유형, 예: `VOICE_TYPE_PREBUILT`(프리빌트) | | `display_name` | 표시 이름 | | `language_code` / `region_code` | 언어와 지역, 예: `en-US` / `US` | | `accent` | 억양, 예: `General American` | | `persona` | 페르소나, 예: `Storyteller & Narrator`, `High-Trust Advisor` | | `context` | 적용 시나리오 | | `gender` | `female` / `male` | | `pitch` | `PITCH_HIGH` / `PITCH_MEDIUM` / `PITCH_LOW` | | `description` | 음성 설명 | | `next_page_token` | 다음 페이지 토큰, 다음 요청의 `page_token`으로 전달. 더 이상 결과가 없으면 생략됨 | 음성 라이브러리는 `ar-001`(현대 표준 아랍어), `ar-EG`(이집트 아랍어) 등 지역 변형을 포함하여 130개 이상의 언어를 지원합니다. ## 모델 비교 | 모델 | 스타일 제어 | 멀티턴 | 출력 형식 | 컨텍스트 캐싱 | 언어 | | - | - | - | - | - | - | | `gemini-3.8-flash-tts` | `speech_metadata` 구조화 | ✅ | WAV | ✅ | 130+ | | `gemini-3.1-flash-tts-preview` | 본문 내 인라인 지시 | ❌ | 순수 PCM | ❌ | 다국어 | 두 모델 모두 음성 라이브러리 조회(`/v1beta/voices`)와 프리빌트 음성(`voiceName`)을 지원합니다. 입력 / 출력 토큰 한도: 둘 다 8,192 / 16,384(출력 16,384 토큰은 약 11분 분량의 오디오). ## 과금 실제 사용량 기준으로 정산되며, 응답의 `usageMetadata`를 따릅니다: | 항목 | 가격 | | - | - | | 입력(텍스트) | \$0.50 / 1M tokens(`promptTokenCount`) | | 출력(오디오) | \$9.00 / 1M tokens(`candidatesTokenCount`, 오디오 10초당 약 250 토큰) | 음성 라이브러리 조회(`/v1beta/voices`)는 과금되지 않습니다. ## 자주 발생하는 오류 | 오류 | 원인 및 해결 | | - | - | | `Multiturn chat is not enabled for this model` | 3.1은 단일 턴만 지원합니다. 모든 내용을 하나의 user 턴으로 합치거나, 멀티턴이 필요하면 `gemini-3.8-flash-tts`로 변경하세요 | | `Invalid token` | API Key가 유효하지 않거나 `Authorization: Bearer` 헤더가 없음 | | `No available channel for model ...` | 모델 이름 오류(예: `{model}` 플레이스홀더를 교체하지 않음) 또는 현재 그룹에 사용 가능한 채널이 없음 | | 생성이 중단됨 | 출력이 16,384 토큰(약 11분)을 초과함. 나누어 합성하세요 | ## 관련 링크 * [Google Speech Generation 문서](https://ai.google.dev/gemini-api/docs/speech-generation) * [gemini-3.8-flash-tts 모델 페이지](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash-tts) * [gemini-3.1-flash-tts-preview 모델 페이지](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-tts-preview) * [GravitexAI 오디오 개요](https://docs.gravitex.ai/ko/api-reference/endpoint/audio) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.