Gemini TTS 시리즈

Google의 Gemini 음성 합성 모델로, OpenAI 호환 POST /v1/audio/speech로 호출하며 어조와 스타일을 자연어로 지정할 수 있습니다.

주요 모델 ID（호출 시 그대로 복사）

Gemini 3.8 Flash TTSgoogle/gemini-3.8-flash-tts

Gemini 3.8 Flash-Lite TTSgoogle/gemini-3.8-flash-lite-tts더 낮은 단가

전체 TTS 모델은 모델 페이지 를 참고하십시오. API의 공통 파라미터는 Audio Speech API를 참고하십시오.

호출 예시

Python

gemini_tts.py


import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])
 
with client.audio.speech.with_streaming_response.create(
    model="google/gemini-3.8-flash-tts",
    voice="Kore",
    input="오늘 회의는 오후 3시로 변경되었습니다. 모두 시간에 맞춰 참석해 주십시오.",
    instructions="뉴스 앵커처럼 차분하고 또렷한 어조로 읽어 주세요.",
    response_format="wav",
) as resp:
    resp.stream_to_file("speech.wav")

파라미터 값

핵심voice는 필수이며 Google의 음색 이름을 사용합니다. 출력 형식은 wav와 pcm만 지원합니다.

파라미터	설명
`voice`	필수. Google의 음색 이름（예: `Kore`, `Puck`, `Zephyr`）. 전체 목록은 Gemini 공식 문서 · 음색 을 참고하십시오. OpenAI의 음색 이름（예: `alloy`）은 사용할 수 없습니다
`response_format`	`wav`（기본값）또는 `pcm`, 둘 다 24 kHz, 16비트, 모노. `mp3`, `opus`, `aac`, `flac`은 지원하지 않습니다
`instructions`	어조, 말하기 속도, 스타일을 자연어로 지정합니다. 예: “밝은 어조로”, “천천히 말하기”
`language_code`	언어 코드（예: `cmn-CN`, `en-US`）. 전달하지 않으면 텍스트를 보고 자동으로 판별합니다
`stream_format`	`sse`를 전달하면 오디오 조각을 스트리밍으로 반환하므로, 생성과 동시에 재생할 때 적합합니다

mp3가 필요하면 먼저 wav를 받은 뒤 ffmpeg 등의 도구로 변환하십시오: ffmpeg -i speech.wav speech.mp3.

소요 시간과 긴 텍스트

실측에서 약 20자 분량의 중국어 문장 하나는 약 3초 만에 반환되었습니다. 약 6,000자의 영어 텍스트로 약 9분 길이의 오디오를 생성하는 데 약 105초가 걸렸고, wav 파일은 약 26 MB였습니다. 긴 텍스트는 클라이언트 타임아웃을 300초 이상으로 설정하거나 stream_format: "sse"로 스트리밍 방식으로 받으십시오.

자주 발생하는 오류

HTTP	오류 메시지 원문	원인	해결 방법
400	`voice is required for speech completion`	`voice`를 전달하지 않음	음색 이름（예: `Kore`）전달
400	`Request contains an invalid argument.`	존재하지 않는 음색 이름（예: `alloy`）을 전달함	Google의 음색 이름 사용
400	`unsupported Gemini response_format: mp3`	지원하지 않는 형식	`wav` 또는 `pcm` 사용

더 많은 오류는 Audio Speech API를 참고하십시오.

공식 문서

Gemini API · 음성 생성

자주 묻는 질문

Gemini TTS의 voice에는 무엇을 입력합니까?

Google의 음색 이름（예: Kore, Puck, Zephyr）을 입력하며, 전체 목록은 Gemini 공식 문서를 참고하십시오. voice는 필수이며 OpenAI의 alloy 등의 음색은 사용할 수 없습니다.

Gemini TTS로 mp3를 출력할 수 있습니까?

할 수 없습니다. wav와 pcm（24 kHz, 16비트, 모노）만 지원합니다. mp3가 필요하면 ffmpeg -i speech.wav speech.mp3처럼 직접 변환하십시오.

Gemini TTS의 어조는 어떻게 제어합니까?

instructions 파라미터에 자연어로 지정합니다. 예: "밝은 어조로 읽기", "뉴스 앵커처럼 차분하게".

Gemini TTS에서 voice is required 오류가 납니다

Gemini TTS는 반드시 voice를 전달해야 합니다. 예: "voice": "Kore".