音声設計機能を使用すると、自然言語による説明からカスタム音声を作成できます。プリビルド音声を選択したり、リファレンス音声を録音したりする代わりに、キャラクターの年齢、声の音色、アクセント、ベースラインの配信を説明して音声を作成します。Voices API は、音声をプロジェクトに保存し、音声生成リクエストで渡す再利用可能な voice_... ID を返します。
設計された音声は、Gemini 3.8 Flash TTS(gemini-3.8-flash-tts)と Gemini 3.8 Flash-Lite TTS(gemini-3.8-flash-lite-tts)の両方で機能します。
音声設計の仕組み
- プロンプト付き音声を作成する: Voices API の
createメソッドを呼び出し、voice.typeをVOICE_TYPE_PROMPTEDに、storeをtrueに設定します。 - 音声 ID とサンプルを受け取る: Voices API は音声を生成してプロジェクトに保存し、その ID(
voice_abc123...など)をidフィールドに、音声のサンプルをsample_audioフィールドに返します。 - 音声を生成する:
generateContentまたはstreamGenerateContentを呼び出すときに、speechConfig.voiceConfig.voiceで音声 ID を渡します。
始める前に
Gemini TTS ページの始める前にの手順を完了します。Voices API は、v1beta1 API バージョンを介して global ロケーションで使用できます。
デザインされた音声を作成する
リクエストで次のフィールドを設定します。
store:trueでなければなりません。デザインされた音声は常にプロジェクトに保存されます。voice.type:VOICE_TYPE_PROMPTEDvoice.prompted.input: 音声の自然言語による説明。voice.display_name、voice.gender、voice.language_code: 音声の省略可能なメタデータ。
voice.model を設定しないでください。モデルと store: true を一緒に設定するリクエストは、INVALID_ARGUMENT エラーで失敗します。
音声の設計には数秒かかることがあります。Python サンプルでは、リクエストのタイムアウトが 60 秒に設定されています。
レスポンスには、次のフィールドが含まれます。
id: 新しい音声の ID。sample_audio: 音声のサンプル。dataフィールドには base64 でエンコードされた音声が格納され、mime_typeフィールドにはエンコードの名前が格納されます。たとえば、audio/l16; rate=24000; channels=1はヘッダーなしの 16 ビット PCM、24 kHz、モノラルです。usage: リクエストで使用されたトークンの数。詳細については、料金をご覧ください。
Python
import base64
import wave
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
voice = client.voices.create(
store=True,
voice={
"type": "VOICE_TYPE_PROMPTED",
"display_name": "Warm British Astronomer",
"gender": "male",
"language_code": "en-GB",
"prompted": {
"input": (
"A warm, thoughtful astronomer in his late 60s with a gentle"
" British accent, speaking with quiet wonder."
)
},
},
timeout=60,
)
print(f"Created voice ID: {voice.id}")
# Save the voice sample. The SDK returns sample_audio.data as a base64
# string. Raw 16-bit PCM (audio/l16) needs a WAV header.
sample = base64.b64decode(voice.sample_audio.data)
if voice.sample_audio.mime_type.lower().startswith("audio/l16"):
with wave.open("voice_sample.wav", "wb") as wf:
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
wf.writeframes(sample)
else:
with open("voice_sample.wav", "wb") as f:
f.write(sample)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices \
-d '{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"displayName": "Warm British Astronomer",
"gender": "male",
"languageCode": "en-GB",
"prompted": {
"input": "A warm, thoughtful astronomer in his late 60s with a gentle British accent, speaking with quiet wonder."
}
}
}' > created_voice.json
# Print the voice ID and the encoding of the voice sample.
jq -r '.id, .sample_audio.mime_type' created_voice.json
# Decode the voice sample.
jq -r '.sample_audio.data' created_voice.json | base64 --decode > voice_sample.pcm
sample_audio.mime_type が audio/l16 の場合、voice_sample.pcm ファイルにはヘッダーなしの 16 ビット PCM 音声(24 kHz、モノラル)が含まれます。
独自のテキストで音声を聞くには、次のセクションに示すように、そのテキストで音声を生成します。
設計された音声で音声を生成する
speechConfig.voiceConfig.voice で音声 ID を渡します。
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content(
model="gemini-3.8-flash-tts",
contents=[{
"role": "user",
"parts": [{
"text": (
"Look out past the rings of Saturn. Those faint photons left"
" their source millions of years ago."
),
"speech_metadata": {"style": "reflective and awe-inspired"},
}],
}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {"voice_config": {"voice": "VOICE_ID"}},
},
)
# The SDK has already decoded the base64 audio, so inline_data.data is a
# complete WAV file by default.
with open("designed_voice.wav", "wb") as f:
f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
"speechMetadata": {"style": "reflective and awe-inspired"}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"voice": "VOICE_ID"}
}
}
}' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > designed_voice.wav
VOICE_ID は、create メソッドが返した音声 ID に置き換えます。
保存された音声を管理する
プロジェクトに保存されている音声(設計された音声や保存された複製音声など)のリスト表示、取得、削除を行うことができます。list メソッドは、プロジェクトに保存されている音声、続いて事前構築済みの音声と拡張音声ライブラリの音声を返します。プロジェクトに保存されている音声のみを一覧表示するには、次の例のように type フィルタを prompted と replicated に設定します。get メソッドは、sample_audio フィールドで設計された音声のサンプルも返します。
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
# List the voices stored in your project.
for voice in client.voices.list(type_=["prompted", "replicated"]).voices or []:
print(voice.id, voice.display_name, voice.type)
# Get a voice by ID.
voice = client.voices.get(id="VOICE_ID")
# Delete a voice.
client.voices.delete(id="VOICE_ID")
REST
# List the voices stored in your project.
curl -G \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices \
--data-urlencode "type=prompted" \
--data-urlencode "type=replicated"
# Get a voice by ID.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices/VOICE_ID
# Delete a voice.
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices/VOICE_ID
上限
- 保存された音声は、最後に使用してから 1 年後に有効期限が切れます。音声を使用して音声生成を行うと、この期間がリセットされるため、定期的に使用する音声は期限切れになりません。不要になった音声は削除できます。
- 音声作成リクエストには、プロジェクトごと、1 分あたりの割り当てが適用されます。上限を超えると、
createメソッドはRESOURCE_EXHAUSTEDエラーを返します。しばらく待ってから再試行してください。詳細については、割り当てとシステムの上限をご覧ください。
料金
設計された音声の作成は、Gemini 3.8 Flash TTS の料金でテキスト入力トークンとオーディオ出力トークンとして課金されます。オーディオ出力トークンは、Voices API が生成する音声サンプルを対象としています。create レスポンスの usage フィールドには、両方のカウントがレポートされます。たとえば、サンプルを作成するの 1 文の説明では、約 220 個の入力トークンと約 1,100 個の出力トークンが使用されます。
get、list、delete の各メソッドは課金されません。設計された音声で生成した音声は、呼び出すモデルの料金で課金されます。
トークン料金については、Gemini Enterprise の料金をご覧ください。
プロンプトのベスト プラクティス
- 音声の説明に永続的な特徴を記述する: 音声を作成するときに、年齢、性別、音色、声の質感、地域の方言を
speech_metadata.styleではなく定義します。 - 状況に応じた感情に
speech_metadata.styleを使用する: 音声を作成したら、"whispered urgently"や"cheerful and energetic"などの短いstyle値を使用して、話者のアイデンティティを変更せずに各ターンを指示します。 - 具体的かつ簡潔にする: 「30 代のキレのある元気なスポーツ アナウンサーで、中西部のアクセントが少しある」のように、1 ~ 2 文で明確に説明すると、長文や矛盾した段落よりも一貫性のある結果が得られます。
次のステップ
- ボイス レプリケーションを使用して、既存の話者の声を複製します。
- ターンレベルのスタイル設定、インライン タグ、複数話者の会話については、Gemini TTS で音声を生成するをご覧ください。