Live API 可讓您與 Gemini 進行低延遲的雙向語音/視訊互動。您可以使用 Live API,為使用者提供自然流暢的對話體驗,並讓使用者透過語音指令中斷模型的回覆。模型可處理文字、音訊和影片輸入內容,並提供文字和音訊輸出內容。
您可以在 Google AI Studio 中試用 Live API。
最新資訊
Live API 推出了新功能和新能力!
新功能:
- 新增兩種語音和 30 種語言,並可設定輸出語言
- 可設定的圖片解析度 66/256 個符記
- 可設定的轉向覆蓋率:隨時傳送所有輸入內容,或僅在使用者說話時傳送
- 設定輸入內容是否應中斷模型
- 可設定的語音活動偵測功能,以及用於表示回合結束的全新用戶端事件
- 符記數量
- 用於傳送串流結束訊號的用戶端事件
- 文字串流
- 可設定的工作階段續行功能,工作階段資料會儲存在伺服器上 24 小時
- 透過滑動式脈絡窗口支援較長的工作階段
新客戶事件:
- 音訊串流結束 / 麥克風關閉
- 用於手動控制轉向轉換的活動開始/結束事件
新伺服器事件:
- 通知訊息顯示需要重新啟動工作階段
- 產生完成
使用 Live API
本節說明如何搭配使用 Live API 和我們的 SDK。如要進一步瞭解基礎 WebSockets API,請參閱 WebSockets API 參考資料。
收發簡訊
import asyncio
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["TEXT"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
while True:
message = input("User> ")
if message.lower() == "exit":
break
await session.send_client_content(
turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
)
async for response in session.receive():
if response.text is not None:
print(response.text, end="")
if __name__ == "__main__":
asyncio.run(main())
接收音訊
以下範例說明如何接收音訊資料,並將資料寫入 .wav
檔案。
import asyncio
import wave
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["AUDIO"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
wf = wave.open("audio.wav", "wb")
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
message = "Hello? Gemini are you there?"
await session.send_client_content(
turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
)
async for idx,response in async_enumerate(session.receive()):
if response.data is not None:
wf.writeframes(response.data)
# Un-comment this code to print audio data info
# if response.server_content.model_turn is not None:
# print(response.server_content.model_turn.parts[0].inline_data.mime_type)
wf.close()
if __name__ == "__main__":
asyncio.run(main())
音訊格式
Live API 支援下列音訊格式:
- 輸入音訊格式:原始 16 位元 PCM 音訊,位元深度為 16 位元,取樣率為 16 kHz 小端序
- 輸出音訊格式:24 kHz 小端序的原始 16 位元 PCM 音訊
串流音訊和視訊
系統指示
系統指令可讓您根據特定需求和用途,控制模型的行為。系統指示可在設定配置中設定,並在整個工作階段中持續生效。
from google.genai import types
config = {
"system_instruction": types.Content(
parts=[
types.Part(
text="You are a helpful assistant and answer in a friendly tone."
)
]
),
"response_modalities": ["TEXT"],
}
逐步更新內容
使用遞增更新功能傳送文字輸入內容、建立工作階段背景資訊或還原工作階段背景資訊。針對短時間的內容,您可以傳送逐向互動,以代表確切的事件順序:
turns = [
{"role": "user", "parts": [{"text": "What is the capital of France?"}]},
{"role": "model", "parts": [{"text": "Paris"}]},
]
await session.send_client_content(turns=turns, turn_complete=False)
turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]
await session.send_client_content(turns=turns, turn_complete=True)
{
"clientContent": {
"turns": [
{
"parts":[
{
"text": ""
}
],
"role":"user"
},
{
"parts":[
{
"text": ""
}
],
"role":"model"
}
],
"turnComplete": true
}
}
對於較長的背景資訊,建議您提供單一訊息摘要,以便釋出脈絡窗口,供後續互動使用。
變更語音
Live API 支援 Puck、Charon、Kore、Fenrir、Aoede、Leda、Orus 和 Zephyr 等語音。
如要指定語音,請在 speechConfig
物件中設定語音名稱,做為工作階段設定的一部分:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
)
)
)
{
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
變更語言
Live API 支援多種語言。
如要變更語言,請在 speechConfig
物件中設定語言代碼,做為工作階段設定的一部分:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
language_code="de-DE",
)
)
使用函式呼叫
您可以使用 Live API 定義工具。請參閱函式呼叫教學課程,進一步瞭解函式呼叫。
您必須在工作階段設定中定義工具:
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
tools=[set_light_values]
)
async with client.aio.live.connect(model=model, config=config) as session:
await session.send_client_content(
turns={
"role": "user",
"parts": [{"text": "Turn the lights down to a romantic level"}],
},
turn_complete=True,
)
async for response in session.receive():
print(response.tool_call)
模型可從單一提示產生多個函式呼叫,以及連結輸出的必要程式碼。這個程式碼會在沙箱環境中執行,產生後續的 BidiGenerateContentToolCall 訊息。執行作業會暫停,直到每個函式呼叫的結果可用為止,藉此確保按順序處理。
用戶端應回覆 BidiGenerateContentToolResponse。
音訊輸入和輸出會對模型使用函式呼叫的功能造成負面影響。
處理中斷
使用者隨時可以中斷模型的輸出內容。當語音活動偵測功能 (VAD) 偵測到中斷情形時,系統會取消並捨棄目前的產生作業。只有已傳送至用戶端的資訊會保留在工作階段記錄中。接著,伺服器會傳送 BidiGenerateContentServerContent 訊息,回報中斷情形。
此外,Gemini 伺服器會捨棄所有待處理的函式呼叫,並傳送含有取消呼叫 ID 的 BidiGenerateContentServerContent
訊息。
async for response in session.receive():
if response.server_content.interrupted is True:
# The generation was interrupted
設定語音活動偵測 (VAD)
根據預設,模型會自動對連續音訊輸入串流執行語音活動偵測 (VAD)。您可以使用設定配置的 realtimeInputConfig.automaticActivityDetection
欄位設定 VAD。
如果音訊串流暫停超過一秒 (例如因為使用者關閉麥克風),就應傳送 audioStreamEnd
事件,以便清除任何快取音訊。用戶端隨時可以恢復傳送音訊資料。
或者,您也可以在設定訊息中將 realtimeInputConfig.automaticActivityDetection.disabled
設為 true
,停用自動語音偵測功能。在這個設定中,用戶端負責偵測使用者的語音,並在適當時間傳送 activityStart
和 activityEnd
訊息。在這個設定中,系統不會傳送 audioStreamEnd
。而是會在任何中斷的串流上標示 activityEnd
訊息。
這項功能的 SDK 支援功能將於未來幾週內推出。
取得符記數
您可以在傳回的伺服器訊息的 usageMetadata 欄位中,找到已使用的符記總數。
async for message in session.receive():
# The server will periodically send messages that include UsageMetadata.
if message.usage_metadata:
usage = message.usage_metadata
print(
f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
)
for detail in usage.response_tokens_details:
match detail:
case types.ModalityTokenCount(modality=modality, token_count=count):
print(f"{modality}: {count}")
延長工作階段時間
工作階段持續時間上限可透過兩種機制延長至無限:
此外,您會在工作階段結束前收到 GoAway 訊息,方便您採取進一步行動。
啟用內容視窗壓縮功能
如要啟用較長的工作階段,並避免連線突然中斷,您可以將 contextWindowCompression 欄位設為工作階段設定的一部分,啟用內容視窗壓縮功能。
在 ContextWindowCompressionConfig 中,您可以設定滑動視窗機制和觸發壓縮功能的符記數。
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
context_window_compression=(
# Configures compression with default parameters.
types.ContextWindowCompressionConfig(
sliding_window=types.SlidingWindow(),
)
),
)
設定工作階段恢復功能
如要避免在伺服器定期重設 WebSocket 連線時終止工作階段,請在設定配置中設定 sessionResumption 欄位。
傳遞這項設定會導致伺服器傳送 SessionResumptionUpdate 訊息,可用於將上一個恢復權杖傳遞為後續連線的 SessionResumptionConfig.handle
,藉此恢復工作階段。
from google.genai import types
print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
model="gemini-2.0-flash-live-001",
config=types.LiveConnectConfig(
response_modalities=["AUDIO"],
session_resumption=types.SessionResumptionConfig(
# The handle of the session to resume is passed here,
# or else None to start a new session.
handle=previous_session_handle
),
),
) as session:
# Session connected
while True:
await session.send_client_content(
turns=types.Content(
role="user", parts=[types.Part(text="Hello world!")]
)
)
async for message in session.receive():
# Periodically, the server will send update messages that may
# contain a handle for the current state of the session.
if message.session_resumption_update:
update = message.session_resumption_update
if update.resumable and update.new_handle:
# The handle should be retained and linked to the session.
return update.new_handle
# For the purposes of this example, placeholder input is continually fed
# to the model. In non-sample code, the model inputs would come from
# the user.
if message.server_content and message.server_content.turn_complete:
break
在工作階段中斷前收到訊息
伺服器會傳送「GoAway」GoAway訊息,表示目前的連線即將終止。這則訊息包含 timeLeft,可顯示剩餘時間,並讓您在連線以「已中止」狀態終止前採取進一步行動。
async for response in session.receive():
if response.go_away is not None:
# The connection will soon be terminated
print(response.go_away.time_left)
產生完成後收到訊息
伺服器會傳送 generationComplete 訊息,表示模型已完成產生回應。
async for response in session.receive():
if response.server_content.generation_complete is True:
# The generation is complete
變更媒體解析度
您可以將 mediaResolution
欄位設為工作階段設定的一部分,藉此指定輸入媒體的媒體解析度:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)
限制
規劃專案時,請考量 Live API 和 Gemini 2.0 的下列限制。
回應模式
您只能在工作階段設定中為每個工作階段設定一個回應模式 (TEXT
或 AUDIO
)。嘗試設定這兩者會導致設定錯誤訊息。也就是說,您可以設定模型以文字或音訊回應,但在同一個工作階段中,不能同時使用這兩種回應。
用戶端驗證
Live API 只提供伺服器對伺服器驗證,不建議直接用於用戶端。用戶端輸入內容應透過中介應用程式伺服器進行轉送,以便透過 Live API 進行安全驗證。
工作階段持續時間
啟用工作階段壓縮功能,即可延長工作階段時間長度。如未壓縮,僅音訊的會話時間上限為 15 分鐘,音訊加視訊的會話時間上限為 2 分鐘。如果未經過壓縮處理就超過這些限制,連線就會終止。
此外,您可以設定工作階段恢復功能,讓用戶端能夠恢復已終止的工作階段。
脈絡窗口
工作階段的脈絡窗口限制為 32k 個符號。
支援的語言
Live API 支援下列語言:
語言 | BCP-47 代碼 |
---|---|
德文 (德國) | de-DE |
英文 (澳洲) | en-AU |
英文 (英國) | en-GB |
英文 (印度) | en-IN |
英文 (美國) | en-US |
西班牙文 (美國) | es-US |
法文 (法國) | fr-FR |
北印度文 (印度) | hi-IN |
葡萄牙文 (巴西) | pt-BR |
阿拉伯文 (一般) | ar-XA |
西班牙文 (西班牙) | es-ES |
法文 (加拿大) | fr-CA |
印尼文 (印尼) | id-ID |
義大利文 (義大利) | it-IT |
日文 (日本) | ja-JP |
土耳其文 (土耳其) | tr-TR |
越南文 (越南) | vi-VN |
孟加拉文 (印度) | bn-IN |
古吉拉特文 (印度) | gu-IN |
卡納達文 (印度) | kn-IN |
馬拉雅拉姆文 (印度) | ml-IN |
馬拉地文 (印度) | mr-IN |
泰米爾文 (印度) | ta-IN |
泰盧固文 (印度) | te-IN |
荷蘭文 (荷蘭) | nl-NL |
韓文 (南韓) | ko-KR |
中文 (中國) | cmn-CN |
波蘭文 (波蘭) | pl-PL |
俄文 (俄羅斯) | ru-RU |
泰文 (泰國) | th-TH |
第三方整合
如要部署網站和行動應用程式,您可以探索下列選項: