音訊轉錄

Gemini API 會使用 Gemini 3.5 Transcribe 模型 (gemini-3.5-transcribe)，將音訊檔案中的語音轉換為文字。根據 Gemini 的音訊理解能力，這項 API 可提供準確的轉錄內容，並自動辨識語言、區分說話者、提供字詞層級的時間戳記，以及自訂詞彙提示。此外，這項功能還提供智慧轉錄模式，可移除贅詞並智慧格式化。

如要轉錄音訊檔案，請上傳音訊並傳遞至 gemini-3.5-transcribe：

Python

from google import genai

client = genai.Client()

audio_file = client.files.upload(file="path/to/sample.mp3")

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const audioFile = await client.files.upload({
  file: "path/to/sample.mp3",
  config: { mime_type: "audio/mp3" },
});

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
});

console.log(interaction.output_text);

REST

# First upload the file via the Files API, then pass its URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ]
  }'

總覽

Gemini 3.5 Transcribe 專為語音轉文字工作而生，可處理各種口音、背景噪音和多語言對話。

主要功能如下所示：

  • 自動語音辨識 (ASR)：自動偵測 85 種以上的語言。處理句子內和句子間的程式碼切換，無須手動設定。
  • 自訂詞彙：傳遞最多 1,000 個詞組，讓辨識結果偏向特定領域的詞彙、縮寫和專有名詞。
  • 講者區分：區分多位講者，並為說話片段加上不同標籤。
  • 字詞層級時間戳記：為每個辨識出的字詞產生精確的開始和結束時間偏移。
  • 智慧轉錄：清除贅字、重複內容和語病，並套用結構化格式。
  • 格式和正規化：套用大小寫、標點符號和反向文字正規化，例如將「二十六 million dollars」轉換為「$26M」。

如要對音訊內容進行一般音訊推理或問答，請使用音訊理解。如要合成文字轉語音音訊，請使用 Text-to-speech。

語言偵測和提示

根據預設，模型會自動偵測說話者使用的語言。當講者切換語言時，這項功能會動態切換語言。

如要使用自動偵測功能，請省略 language_codes 或提供空白清單：

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "language_codes": [],
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      language_codes: [],
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "language_codes": []
      }
    }
  }'

如果預先知道語言，請在 language_codes 中指定 BCP-47 語言代碼，以提高語音轉錄準確率 (請參閱「支援的語言」)：

Python

generation_config = {
    "transcription_config": {
        "language_codes": ["es-ES"],
    }
}

JavaScript

const generationConfig = {
  transcription_config: {
    language_codes: ["es-ES"],
  },
};

REST

{
  "generation_config": {
    "transcription_config": {
      "language_codes": ["es-ES"]
    }
  }
}

自訂詞彙

你可以引導語音模型辨識不常見的字詞、專業術語、品牌名稱或專有名詞。在 custom_vocabulary 陣列中提供最多 1,000 個字詞 (通常最多 100 個字詞就能獲得最佳結果)：

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"],
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      custom_vocabulary: ["Gemini", "Kubernetes", "BigQuery"],
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"]
      }
    }
  }'

說話者分段標記

說話者分段標記功能會識別錄音中不同的聲音，並為每個片段加上說話者 ID，例如 spk_1 或 spk_2。最多支援 8 個音箱 (3 個以上音箱的歸因功能為實驗功能)。

如要啟用說話者分段標記，請在 mode 中設定 diarization_mode：

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "diarization_mode": "speaker",
            },
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: {
        type: "verbatim",
        diarization_mode: "speaker",
      },
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "diarization_mode": "speaker"
        }
      }
    }
  }'

字詞層級時間戳記

字詞層級時間戳記會提供音訊串流中每個辨識字詞的確切開始和結束偏移。

如要在 mode 中設定 timestamp_granularities，請啟用時間戳記：

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "timestamp_granularities": ["word"],
            },
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: {
        type: "verbatim",
        timestamp_granularities: ["word"],
      },
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "timestamp_granularities": ["word"]
        }
      }
    }
  }'

您可以在 mode 中合併 diarization_mode 和 timestamp_granularities，同時取得發言者標籤和字詞時間戳記：

Python

generation_config = {
    "transcription_config": {
        "custom_vocabulary": ["Gemini"],
        "mode": {
            "type": "verbatim",
            "diarization_mode": "speaker",
            "timestamp_granularities": ["word"],
        },
    }
}

JavaScript

const generationConfig = {
  transcription_config: {
    custom_vocabulary: ["Gemini"],
    mode: {
      type: "verbatim",
      diarization_mode: "speaker",
      timestamp_granularities: ["word"],
    },
  },
};

REST

{
  "generation_config": {
    "transcription_config": {
      "custom_vocabulary": ["Gemini"],
      "mode": {
        "type": "verbatim",
        "diarization_mode": "speaker",
        "timestamp_granularities": ["word"]
      }
    }
  }
}

轉錄模式

Gemini 3.5 Transcribe 支援兩種轉錄模式，可透過 mode 參數設定：

  • verbatim (預設)：逐字轉錄所有說出的內容，保留原始的填充詞 (例如「嗯」、「呃」、「像」、「你知道」)、重複內容、停頓和錯誤開頭。時間戳記和說話者分段標記是在這個模式 ({"type": "verbatim", ...}) 中設定。
  • smart (智慧轉錄)：透過智慧後續處理，讓轉錄稿更易於閱讀：
    • 移除贅詞：移除對話中的贅詞、口吃和錯誤開場白。
    • 即時修正：直接解決口語修正內容 (例如「我們星期二碰面，不對，星期三下午兩點」會變成「我們星期三下午兩點碰面」)。
    • 自動結構化格式：自動將口述內容結構化為段落、編號清單、項目符號、格式化日期、貨幣和數字。
    • 文法清理：套用自然的標點符號、句子大小寫和流暢度。
語音音訊 verbatim 輸出 smart (智慧轉錄) 輸出內容
「嗯，所以我覺得我們應該邀請愛麗絲參加會議，等等，不是，是小明和卡羅。」 「嗯，所以我覺得我們應該邀請愛麗絲參加會議，等等，是鮑伯和卡羅。」 「我覺得應該邀請 Bob 和 Carol 參加會議。」
「First item review budget second item finalize timeline third item send recap」(先審查預算，再確定時間表，最後傳送摘要) 「first item review budget second item finalize timeline third item send recap」(第一個項目審查預算，第二個項目確定時間軸，第三個項目傳送摘要) 「1. 查看預算
2. 完成時間軸
3. 傳送摘要」

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": "smart",
        }
    },
)
print(interaction.output_text)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: "smart",
    },
  },
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": "smart"
      }
    }
  }'

剖析轉錄輸出內容

完整轉錄稿文字會以 interaction.output_text 形式傳回。

啟用 timestamp_granularities 或 diarization_mode 時，API 也會傳回附加至互動內容的詳細字詞層級註解。

以下說明如何擷取及疊代字詞時間戳記和說話者輪流說話的片段：

Python

def extract_word_annotations(interaction):
    words = []
    for step in getattr(interaction, "steps", []) or []:
        for content in getattr(step, "content", []) or []:
            for annotation in getattr(content, "annotations", []) or []:
                if getattr(annotation, "type", None) == "word_info":
                    words.append(annotation)
    return words

words = extract_word_annotations(interaction)

for w in words:
    speaker = f"[{w.speaker}] " if getattr(w, "speaker", None) else ""
    start = getattr(w, "start_offset", "")
    end = getattr(w, "end_offset", "")
    timing = f"({start} -> {end}) " if start and end else ""
    print(f"{speaker}{timing}{w.text}")

JavaScript

function extractWordAnnotations(interaction) {
  const words = [];
  for (const step of interaction.steps ?? []) {
    for (const content of step.content ?? []) {
      for (const annotation of content.annotations ?? []) {
        if (annotation.type === "word_info") {
          words.push(annotation);
        }
      }
    }
  }
  return words;
}

const words = extractWordAnnotations(interaction);

for (const w of words) {
  const speaker = w.speaker ? `[${w.speaker}] ` : "";
  const timing = (w.start_offset && w.end_offset) ? `(${w.start_offset} -> ${w.end_offset}) ` : "";
  console.log(`${speaker}${timing}${w.text}`);
}

REST

{
  "id": "interactions/abc123xyz",
  "status": "completed",
  "steps": [
    {
      "id": "step_001",
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello world",
          "annotations": [
            {
              "type": "word_info",
              "text": "Hello",
              "speaker": "spk_1",
              "start_offset": "0.100s",
              "end_offset": "0.450s"
            },
            {
              "type": "word_info",
              "text": "world",
              "speaker": "spk_1",
              "start_offset": "0.500s",
              "end_offset": "0.850s"
            }
          ]
        }
      ]
    }
  ]
}

支援的語言

Gemini 3.5 Transcribe 支援下列語言和 BCP-47 語言代碼：

語言 BCP-47 代碼 語言 BCP-47 代碼
南非荷蘭文 af-ZA 日文 ja-JP
阿姆哈拉文 am-ET 爪哇語 jv-ID
阿拉伯文 (埃及) ar-EG Kabuverdianu kea-CV
亞美尼亞文 hy-AM 卡納達文 kn-IN
阿薩姆文 as-IN 哈薩克文 kk-KZ
亞塞拜然文 az-AZ 韓文 ko-KR
白俄羅斯語 be-BY 吉爾吉斯文 ky-KG
孟加拉文 (孟加拉) bn-BD 拉脫維亞文 lv-LV
孟加拉文 (印度) bn-IN 林格拉文 ln-CD
波士尼亞文 bs-BA 立陶宛文 lt-LT
保加利亞文 bg-BG 馬其頓文 mk-MK
保加利亞文 (阿羅馬尼亞文) rup-BG 馬來文 ms-MY
緬甸文 my-MM 馬拉雅拉姆文 ml-IN
粵語 (繁體) yue-Hant-HK 馬爾他文 mt-MT
加泰隆尼亞文 ca-ES 中文 (簡體) cmn-Hans-CN
宿霧文 ceb 馬拉地文 mr-IN
中部高棉文 km-KH 蒙古文 mn-MN
克羅埃西亞文 hr-HR 尼泊爾文 ne-NP
捷克文 cs-CZ 挪威文 nb-NO
丹麥文 da-DK 奧里雅文 or-IN
荷蘭文 nl-NL 波蘭文 pl-PL
英文 (英國) en-GB 葡萄牙文 (巴西) pt-BR
英文 (印度) en-IN 葡萄牙文 (葡萄牙) pt-PT
英文 (美國) en-US 旁遮普文 pa-IN
愛沙尼亞文 et-EE 旁遮普文 (古爾穆基字母) pa-Guru-IN
波斯文 fa-IR 羅馬尼亞文 ro-RO
菲律賓文 fil-PH 俄文 ru-RU
芬蘭文 fi-FI 塞爾維亞文 sr-RS
法文 fr-FR 信德文 (阿拉伯字母) sd-Arab-IN
加里西亞文 gl-ES 斯洛伐克文 sk-SK
喬治亞文 ka-GE 斯洛維尼亞文 sl-SI
德文 de-DE 西班牙文 (拉丁美洲) es-419
希臘文 el-GR 西班牙文 (美國) es-US
古吉拉特文 gu-IN 斯瓦希里文 (肯亞) sw-KE
豪薩文 ha-NG 瑞典文 sv-SE
希伯來文 he-IL 塔吉克文 tg-TJ
北印度文 hi-IN 泰盧固文 te-IN
匈牙利文 hu-HU 泰文 th-TH
冰島文 is-IS 土耳其文 tr-TR
印度英語 en-IN 烏克蘭文 uk-UA
印尼文 id-ID 烏茲別克文 uz-UZ
義大利文 it-IT 越南文 vi-VN

參數參照

在 generation_config 中設定 transcription_config 物件內的欄位，即可設定轉錄功能：

欄位 類型 說明
language_codes 字串陣列 BCP-47 語言代碼 (例如 ["en-US"])。如果省略或空白 ([])，模型會自動偵測語言並處理代碼切換。
custom_vocabulary 字串陣列 最多 1,000 個自訂字詞、縮寫或專有名詞，可調整語音辨識結果。
mode 物件或字串 轉錄模式設定。接受 "smart" 或逐字模式物件 ({"type": "verbatim", ...})。預設為逐字轉錄。
mode.type 字串 (僅限逐字模式) 模式 ID。一律設為 "verbatim"。
mode.timestamp_granularities 字串陣列 (僅限逐字模式) 要傳回的時間戳記精細程度。傳遞 ["word"] 即可啟用字詞開始和結束時間偏移。
mode.diarization_mode 字串 (僅限逐字模式) 說話者區分模式。傳遞 "speaker" 可識別不同的說話者並加上標籤。

最佳做法

  • 提供清晰的音訊：確保錄音的語音分離度良好，並避免嚴重剪輯。
  • 已知語言時提供語言提示：如果預先知道音訊語言，請指定 language_codes，盡可能提高準確度。
  • 目標自訂詞彙：請只在 custom_vocabulary 中加入不重複的網域字詞、品牌名稱或專有名詞，而非常見的日常用語。
  • 使用 Files API 處理大型錄音檔：如要處理長度超過幾秒的檔案，請使用 client.files.upload 上傳檔案，並將傳回的檔案 URI 傳遞至模型。

限制

  • 音訊長度：標準一元要求支援最長 1 小時的音訊檔案。啟用說話者分段標記或個別字詞時間戳記等功能時，音訊處理時間上限為 30 分鐘。
  • 字詞層級時間戳記：啟用字詞層級時間戳記可能會降低整體轉錄準確率。
  • 說話者分段標記：說話者分段標記最多可支援 8 位說話者。3 個以上音箱的說話者辨識功能目前為實驗功能。
  • 自訂詞彙：您最多可以在 custom_vocabulary 中提供 1,000 個字詞，但通常最多 100 個字詞就能獲得最佳結果。
  • 模式相容性：智慧轉錄 ("smart") 無法與 timestamp_granularities 或 diarization_mode 合併使用。

後續步驟

  • 使用 Live API 透過即時轉錄指南串流即時音訊。
  • 探索「音訊理解」，分析、摘要或查詢音訊內容。
  • 瞭解如何使用 Text-to-Speech 從文字合成音訊。
  • 如需模型定價和權杖限制，請參閱定價頁面。
  • 如要瞭解如何上傳及管理媒體檔案，請參閱「Files API」指南。