跳至主要內容

Google

Mastra 的 Google Voice 實作使用 Google Cloud 服務提供文字轉語音（TTS）與語音轉文字（STT）功能。它支援多種語音、語言、進階音訊設定選項，以及用於企業部署的標準 API 金鑰驗證與 Vertex AI 模式。

使用範例
「使用範例」的直接連結

import { GoogleVoice } from '@mastra/voice-google'

// Initialize with default configuration (uses GOOGLE_API_KEY environment variable)
const voice = new GoogleVoice()

// Text-to-Speech (plain text)
const audioStream = await voice.speak('Hello, world!', {
  languageCode: 'en-US',
  audioConfig: {
    audioEncoding: 'LINEAR16',
  },
})

// Text-to-Speech with SSML
const ssmlStream = await voice.speak('ignored', {
  input: {
    ssml: '<speak>Take <say-as interpret-as="unit">5 mg</say-as> daily.</speak>',
  },
})

// Text-to-Speech with Gemini-TTS model
const geminiStream = await voice.speak('Hello from Gemini TTS!', {
  voice: { name: 'Kore', modelName: 'gemini-2.5-flash-preview-tts' },
  input: { prompt: 'Warm, calm tone.' },
})

// Speech-to-Text
const transcript = await voice.listen(audioStream, {
  config: {
    encoding: 'LINEAR16',
    languageCode: 'en-US',
  },
})

// Get available voices for a specific language
const voices = await voice.getSpeakers({ languageCode: 'en-US' })

建構函式參數
「建構函式參數」的直接連結

speechModel?:

GoogleModelConfig
= { apiKey: process.env.GOOGLE_API_KEY }
文字轉語音功能的設定
GoogleModelConfig

apiKey?:

string
Google Cloud API 金鑰。若未提供，則使用 GOOGLE_API_KEY 環境變數。vertexAI 為 true 時不使用。

keyFilename?:

string
服務帳戶 JSON 金鑰檔的路徑。若未提供，則使用 GOOGLE_APPLICATION_CREDENTIALS 環境變數。

credentials?:

object
記憶體內服務帳戶認證資訊物件，包含 client_email 與 private_key 屬性。

listeningModel?:

GoogleModelConfig
= { apiKey: process.env.GOOGLE_API_KEY }
語音轉文字功能的設定
GoogleModelConfig

apiKey?:

string
Google Cloud API 金鑰。若未提供，則使用 GOOGLE_API_KEY 環境變數。vertexAI 為 true 時不使用。

keyFilename?:

string
服務帳戶 JSON 金鑰檔的路徑。若未提供，則使用 GOOGLE_APPLICATION_CREDENTIALS 環境變數。

credentials?:

object
記憶體內服務帳戶認證資訊物件，包含 client_email 與 private_key 屬性。

speaker?:

string
= 'en-US-Casual-K'
文字轉語音使用的預設語音 ID

vertexAI?:

boolean
= false
為企業部署啟用 Vertex AI 模式。使用以專案為基礎的驗證，而非 API 金鑰。必須設定 'project'。

project?:

string
Google Cloud 專案 ID（vertexAI 為 true 時為必填）。若未提供，則使用 GOOGLE_CLOUD_PROJECT 環境變數。

location?:

string
= 'us-central1'
Vertex AI 的 Google Cloud 區域。若未提供，則使用 GOOGLE_CLOUD_LOCATION 環境變數。

方法
「方法」的直接連結

speak()
「speak」的直接連結

使用 Google Cloud Text-to-Speech 服務將文字轉換為語音。

input:

string | NodeJS.ReadableStream
要轉換為語音的文字。若提供資料流，會先將其轉換為文字。

options?:

object
語音合成選項
GoogleSpeakOptions

speaker?:

string
此請求使用的語音 ID。

languageCode?:

string
語音的語言程式碼（例如 'en-US'）。預設使用從語音 ID 衍生的語言程式碼，若無則使用 'en-US'。

input?:

ISynthesizeSpeechRequest['input']
直接傳遞給 Google Cloud TTS API 的豐富輸入物件。支援 ssml、markup、prompt（Gemini-TTS 風格引導）、customPronunciations 與 multiSpeakerMarkup。若提供的物件未包含 text、ssml、markup 或 multiSpeakerMarkup，位置 input 引數會自動用作 text 欄位。

voice?:

ISynthesizeSpeechRequest['voice']
合併至預設值（name 與 languageCode）之上的語音設定。支援 modelName（例如 'gemini-2.5-flash-preview-tts'）與 multiSpeakerVoiceConfig。

audioConfig?:

ISynthesizeSpeechRequest['audioConfig']
Google Cloud Text-to-Speech API 的音訊設定選項。

回傳：Promise<NodeJS.ReadableStream>

listen()
「listen」的直接連結

使用 Google Cloud Speech-to-Text 服務將語音轉換為文字。支援 v1（預設）與 v2 API。v2 API 可透過自動解碼支援 AAC-in-MP4 音訊（iOS Safari）。

v1（預設）
「v1（預設）」的直接連結

audioStream:

NodeJS.ReadableStream
要轉錄的音訊資料流

options?:

GoogleListenOptionsV1
v1 辨識選項
GoogleListenOptionsV1

config?:

IRecognitionConfig
Google Cloud Speech-to-Text API 的 v1 辨識設定

v2
「v2」的直接連結

傳入 v2: true 即可使用 Cloud Speech-to-Text v2 API；此 API 支援 AAC-in-MP4（iOS Safari）等其他音訊格式。

v2 recognize 呼叫使用 IAM 授權，不接受僅使用 API 金鑰的驗證。請在 listeningModel 設定服務帳戶認證資訊（或設定 GOOGLE_APPLICATION_CREDENTIALS），並設定 GOOGLE_CLOUD_PROJECT，讓系統可解析辨識器路徑；即使未啟用 vertexAI 也一樣。

import { GoogleVoice } from '@mastra/voice-google'

// v2 listen() requires service account credentials, not just GOOGLE_API_KEY.
// Set GOOGLE_CLOUD_PROJECT so the recognizer path can be resolved.
const voice = new GoogleVoice({
  listeningModel: { keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS },
})

const transcript = await voice.listen(iosSafariAacStream, {
  v2: true,
  config: {
    autoDecodingConfig: {},
  },
})
備註

只設定 GOOGLE_API_KEY 時，listen({ v2: true }) 會在 speech.recognizers.recognize 發生 PERMISSION_DENIED。API 金鑰請求不帶 OAuth 身分，因此將 roles/speech.client 授予使用者帳戶並無幫助；此角色必須授予請求中使用的服務帳戶。無論 vertexAI 設定為何皆是如此；speak() 與 v1 listen() 仍可只使用 API 金鑰執行。

audioStream:

NodeJS.ReadableStream
要轉錄的音訊資料流

options:

GoogleListenOptionsV2
v2 辨識選項
GoogleListenOptionsV2

v2:

true
啟用 v2 API 路徑

config?:

v2.IRecognitionConfig
v2 辨識設定。預設使用自動解碼，以及 languageCodes: ['en-US'] 和 model: 'long'。設定 autoDecodingConfig: {} 可自動偵測音訊格式，或使用 explicitDecodingConfig 指定 MP4_AAC、M4A_AAC 或 MOV_AAC 等編碼。

recognizer?:

string
v2 辨識器資源路徑。預設為 projects/{project}/locations/global/recognizers/_，其中 {project} 會從建構函式的 project 選項、GOOGLE_CLOUD_PROJECT 或使用者端的預設專案解析。

回傳：Promise<string>

getSpeakers()
「getspeakers」的直接連結

回傳可用語音選項的陣列，其中每個節點包含：

voiceId:

string
語音的唯一識別碼

languageCodes:

string[]
此語音支援的語言程式碼清單

isUsingVertexAI()
「isusingvertexai」的直接連結

檢查是否已啟用 Vertex AI 模式。

回傳：boolean — 使用 Vertex AI 時為 true，否則為 false

getProject()
「getproject」的直接連結

取得已設定的 Google Cloud 專案 ID。

回傳：string | undefined — 專案 ID；若未設定則為 undefined

getLocation()
「getlocation」的直接連結

取得已設定的 Google Cloud 位置／區域。

回傳：string — 位置（預設：'us-central1'）

驗證
「驗證」的直接連結

Google Voice Provider 支援兩種驗證方法：

標準模式（API 金鑰）
「標準模式（API 金鑰）」的直接連結

使用 Google Cloud API 金鑰進行驗證。適用於 speak() 與 v1 listen()，不適用於 listen({ v2: true })；後者使用 IAM 授權並需要服務帳戶認證資訊（請參閱 v2）。

// Using environment variable (GOOGLE_API_KEY)
const voice = new GoogleVoice()

// Using explicit API key
const voice = new GoogleVoice({
  speechModel: { apiKey: 'your-api-key' },
  listeningModel: { apiKey: 'your-api-key' },
  speaker: 'en-US-Casual-K',
})

Vertex AI 模式（服務帳戶）
「Vertex AI 模式（服務帳戶）」的直接連結

使用以 Google Cloud 專案為基礎的服務帳戶驗證。建議用於正式環境與企業部署。

優點：

  • 安全性更佳（程式碼中沒有 API 金鑰）
  • 以 IAM 為基礎的存取控制
  • 專案層級的計費與配額
  • 稽核記錄
  • 企業功能

設定選項：

// Using Application Default Credentials (ADC)
// Set GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT env vars
const voice = new GoogleVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1', // Optional, defaults to 'us-central1'
})

// Using service account key file
const voice = new GoogleVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  speechModel: {
    keyFilename: '/path/to/service-account.json',
  },
  listeningModel: {
    keyFilename: '/path/to/service-account.json',
  },
})

// Using in-memory credentials
const voice = new GoogleVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  speechModel: {
    credentials: {
      client_email: 'service-account@project.iam.gserviceaccount.com',
      private_key: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
    },
  },
})

必要權限
「必要權限」的直接連結

IAM 角色
「IAM 角色」的直接連結

Text-to-Speech：

  • roles/texttospeech.admin — Text-to-Speech 管理員（完整存取權）
  • roles/texttospeech.editor — Text-to-Speech 編輯者（建立及管理）
  • roles/texttospeech.viewer — Text-to-Speech 檢視者（唯讀）

Speech-to-Text：

  • roles/speech.client — Speech-to-Text 使用者端

請將 roles/speech.client 授予請求所使用認證資訊對應的服務帳戶（透過 keyFilename、credentials 或 GOOGLE_APPLICATION_CREDENTIALS）。此角色是 listen({ v2: true }) 特別需要的，並非只在 Vertex AI 模式下才需要。將角色授予使用者帳戶不會影響僅使用 API 金鑰的請求，因為這類請求不帶可供授權的身分。

OAuth 範圍
「OAuth 範圍」的直接連結

同步 Text-to-Speech 合成：

  • https://www.googleapis.com/auth/cloud-platform — 完整存取 Google Cloud Platform 服務

長音訊 Text-to-Speech 作業：

  • locations.longAudioSynthesize — 建立長音訊合成作業
  • operations.get — 取得作業狀態
  • operations.list — 列出作業

重要事項
「重要事項」的直接連結

  1. 驗證：必須提供 Google Cloud API 金鑰（標準模式）或服務帳戶認證資訊（Vertex AI 模式）。
  2. 環境變數：
    • GOOGLE_API_KEY — 標準模式的 API 金鑰
    • GOOGLE_CLOUD_PROJECT — Vertex AI 模式的專案 ID
    • GOOGLE_CLOUD_LOCATION — Vertex AI 模式的位置（預設為 'us-central1'）
    • GOOGLE_APPLICATION_CREDENTIALS — 服務帳戶金鑰檔的路徑
  3. 預設語音設為 'en-US-Casual-K'。
  4. 文字轉語音與語音轉文字服務都使用 LINEAR16 作為預設音訊編碼。
  5. speak() 方法支援透過 Google Cloud Text-to-Speech API 進行進階音訊設定。
  6. listen() 方法支援透過 Google Cloud Speech-to-Text API 使用各種辨識設定。
  7. listen({ v2: true }) 需要服務帳戶認證資訊與 GOOGLE_CLOUD_PROJECT；只設定 GOOGLE_API_KEY 時會因 PERMISSION_DENIED 而失敗。speak() 與 v1 listen() 可只使用 API 金鑰執行。
  8. 可使用 getSpeakers() 方法依語言程式碼篩選可用語音。
  9. Vertex AI 模式提供 IAM 控制、稽核記錄與專案層級計費等企業功能。
On this page