Gemini API を使用した音声機能の詳細

Python JavaScript Go REST

Gemini は、音声に関するプロンプトに応答できます。たとえば、Gemini は次のようなことができます。

• 音声コンテンツの説明、要約、質問への回答を行う。
• 音声の文字起こしを提供します。
• 音声の特定のセグメントに関する回答または文字変換を提供します。

このガイドでは、Gemini API を使用して音声ファイルと音声コンテンツを操作するさまざまな方法について説明します。

サポートされているオーディオ形式

Gemini は、次の音声形式の MIME タイプをサポートしています。

• WAV - audio/wav
• MP3 - audio/mp3
• AIFF - audio/aiff
• AAC - audio/aac
• OGG Vorbis - audio/ogg
• FLAC - audio/flac

オーディオに関する技術的な詳細

Gemini では、音声に対して次のルールが適用されます。

• Gemini では、音声の 1 秒は 32 個のトークンとして表されます。たとえば、1 分間の音声は 1,920 個のトークンとして表されます。
• Gemini は、英語の音声に対する回答のみを推測できます。
• Gemini は、鳥のさえずりやサイレンなど、音声以外のコンポーネントを「理解」できます。
• 1 つのプロンプトでサポートされる音声データの最大長は 9.5 時間です。Gemini では、1 つのプロンプト内の音声ファイルの数に制限はありませんが、1 つのプロンプト内のすべての音声ファイルの合計時間は 9.5 時間を超過できません。
• Gemini は、音声ファイルを 16 Kbps のデータ解像度にダウンサンプリングします。
• 音声ソースに複数のチャンネルが含まれている場合、Gemini はこれらのチャンネルを 1 つのチャンネルに統合します。

始める前に: プロジェクトと API キーを設定する

Gemini API を呼び出す前に、プロジェクトを設定して API キーを構成する必要があります。

音声ファイルを Gemini で使用できるようにする

音声ファイルを Gemini で使用できるようにするには、次のいずれかの方法を使用します。

• 音声ファイルを事前にアップロードします。
• 音声ファイルをインライン データとしてプロンプト リクエストに指定します。

音声ファイルをアップロードしてコンテンツを生成する

File API を使用すると、任意のサイズの音声ファイルをアップロードできます。リクエストの合計サイズ（ファイル、テキスト プロンプト、システム インストラクションなど）が 20 MB を超える場合は、常に File API を使用してください。

media.upload を呼び出して、File API を使用してファイルをアップロードします。次のコードは、音声ファイルをアップロードし、models.generateContent の呼び出しでそのファイルを使用します。

from google import genai

client = genai.Client()

myfile = client.files.upload(file='media/sample.mp3')

response = client.models.generate_content(
  model='gemini-2.0-flash',
  contents=['Describe this audio clip', myfile]
)

print(response.text)

ファイルのメタデータを取得する

API がアップロードされたファイルを正常に保存したことを確認するには、files.get を呼び出してメタデータを取得します。

myfile = client.files.upload(file='media/sample.mp3')
file_name = myfile.name
myfile = client.files.get(name=file_name)
print(myfile)

アップロードしたファイルを一覧表示する

複数の音声ファイル（および他の種類のファイル）をアップロードできます。次のコードは、アップロードされたすべてのファイルのリストを生成します。

print('My files:')
for f in client.files.list():
    print(' ', f.name)

アップロードしたファイルを削除する

ファイルは 48 時間後に自動的に削除されます。必要に応じて、アップロードしたファイルを手動で削除できます。次に例を示します。

myfile = client.files.upload(file='media/sample.mp3')
client.files.delete(name=myfile.name)

音声ファイルをリクエストのインライン データとして指定する

オーディオ ファイルをアップロードする代わりに、プロンプトを含む呼び出しでオーディオ データを渡すことができます。

次に、ダウンロードした小さな音声ファイルをプロンプトとともに Gemini に渡します。

from google.genai import types

with open('media/small-sample.mp3', 'rb') as f:
    audio_bytes = f.read()

response = client.models.generate_content(
  model='gemini-2.0-flash',
  contents=[
    'Describe this audio clip',
    types.Part.from_bytes(
      data=audio_bytes,
      mime_type='audio/mp3',
    )
  ]
)

print(response.text)

音声をインライン データとして指定する場合は、次の点に注意してください。

• リクエストの最大サイズは 20 MB です。これには、テキスト プロンプト、システム インストラクション、インラインで提供されるファイルが含まれます。ファイルのサイズが原因でリクエストの合計サイズが 20 MB を超える場合は、File API を使用してリクエストで使用するファイルをアップロードします。
• 音声サンプルを複数回使用する場合は、File API を使用する方が効率的です。

音声を扱う方法の追加

このセクションでは、音声からより多くの情報を得るための方法をいくつか紹介します。

音声ファイルの文字起こしを取得する

文字起こしを取得するには、プロンプトでリクエストします。次に例を示します。

myfile = client.files.upload(file='media/sample.mp3')
prompt = 'Generate a transcript of the speech.'

response = client.models.generate_content(
  model='gemini-2.0-flash',
  contents=[prompt, myfile]
)

print(response.text)

音声ファイル内のタイムスタンプを参照する

プロンプトでは、MM:SS 形式のタイムスタンプを指定して、音声ファイル内の特定のセクションを参照できます。たとえば、次のプロンプトは、次のような文字起こしをリクエストします。

• ファイルの先頭から 2 分 30 秒の位置から開始します。
• ファイルの先頭から 3 分 29 秒で終了します。

# Create a prompt containing timestamps.
prompt = "Provide a transcript of the speech from 02:30 to 03:29."

トークンのカウント

countTokens メソッドを呼び出して、音声ファイル内のトークン数を取得します。次に例を示します。

response = client.models.count_tokens(
  model='gemini-2.0-flash',
  contents=[myfile]
)

print(response)

次のステップ

このガイドでは、File API を使用して音声ファイルをアップロードし、音声入力からテキスト出力を生成する方法について説明します。詳細については、次のリソースをご覧ください。

• ファイル プロンプト戦略: Gemini API は、テキスト、画像、音声、動画データによるプロンプト（マルチモーダル プロンプト）をサポートしています。
• システム指示: システム指示を使用すると、特定のニーズやユースケースに基づいてモデルの動作を制御できます。
• 安全性に関するガイダンス: 生成 AI モデルは、不正確な出力、偏見のある出力、不適切な出力など、予期しない出力を生成することがあります。このような出力による被害のリスクを軽減するには、後処理と人間による評価が不可欠です。