# 音频转写

Gemini API 使用 Gemini 3.5 Transcribe 模型将音频文件中的语音转换为文本（`gemini-3.5-transcribe`）。基于 Gemini 的音频理解功能，它可以通过自动语言识别、说话人分类、词级时间戳和自定义词汇提示来提供准确的转录。它还提供了一个 [智能转录](/docs/transcribe#transcription-modes) 具有不流畅消除和智能格式化功能的模式。

要转录音频文件，请上传音频并将其传递到 `gemini-3.5-transcribe`:

{% tabs %}
{% tab filename="transcribe_quickstart.py" label="Python" %}
```python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

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

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
)

print(response.output_text)
```
{% /tab %}

{% tab filename="transcribe_quickstart.js" label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

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

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

console.log(response.output_text);
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab filename="transcribe_quickstart.sh" label="REST" %}
```bash
# 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": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
有关来自麦克风或实时音频流的实时、低延迟流式语音识别，请参阅 [实时转录](/docs/live-api/live-transcribe) 使用 Live API 和 `gemini-3.5-transcribe-live`.
{% /callout %}

## 概览  {% #overview %}

Gemini 3.5 Transcribe 针对语音转文本任务进行了优化。它可以处理不同的口音、背景噪音和多语言对话。

主要能力包括：

* **自动语音识别（ASR）：** 自动检测跨语言 [85+ 区域设置](/docs/transcribe#supported-languages)。无需手动配置即可处理句内和句间代码转换。
* **自定义词汇：** 通过传递最多 1,000 短语，将识别偏向于特定于域的术语、首字母缩略词和专有名称。
* **说话人分类：** 区分多个说话者并将语音片段分配给不同的标签。
* **字级时间戳：** 为每个识别的单词生成精确的开始和结束时间偏移。
* **智能转录：** 清理不流畅、填充词、重复并应用结构化格式。
* **格式化和规范化：** 应用大写、标点符号和反向文本规范化，例如将“2600 万美元”转换为“$26M”。

对于一般音频推理或通过音频内容回答问题，请使用 [音频理解](/docs/audio)。对于文本到语音的音频合成，请使用 [文字转语音](/docs/speech-generation).

## 语言检测和提示  {% #language-detection %}

默认情况下，模型会自动检测口语。当说话者进行语码转换时，它会动态地在语言之间切换。

要使用自动检测，请省略 `language_codes` 或提供一个空列表：

{% tabs %}
{% tab filename="transcribe_language_auto.py" label="Python" %}
```python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "language_codes": [],
        }
    },
)
```
{% /tab %}

{% tab filename="transcribe_language_auto.js" label="JavaScript" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      languageCodes: [],
    },
  },
});
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    LanguageCodes: []string{},
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab filename="transcribe_language_auto.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "language_codes": []
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

如果您事先知道语言，请在中指定 BCP-47 语言代码 `language_codes` 提高转录准确性（参见 [支持的语言](/docs/transcribe#supported-languages)):

{% tabs %}
{% tab filename="transcribe_language_hint.py" label="Python" %}
```python
generation_config = {
    "transcription_config": {
        "language_codes": ["es-ES"],
    }
}
```
{% /tab %}

{% tab filename="transcribe_language_hint.js" label="JavaScript" %}
```javascript
const generationConfig = {
  transcriptionConfig: {
    languageCodes: ["es-ES"],
  },
};
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := &interactions.GenerationConfig{
        TranscriptionConfig: &interactions.TranscriptionConfig{
            LanguageCodes: []string{"es-ES"},
        },
    }
    _ = generationConfig
}
```
{% /tab %}

{% tab filename="transcribe_language_hint.json" label="REST" %}
```json
{
  "generation_config": {
    "transcription_config": {
      "language_codes": ["es-ES"]
    }
  }
}
```
{% /tab %}
{% /tabs %}

## 自定义词汇  {% #custom-vocabulary %}

您可以将语音模型引导至不常见的单词、技术术语、品牌名称或专有名词。供应最多 1,000 条款 `custom_vocabulary` 数组（通常使用最多 100 项即可获得最佳结果）：

{% callout type="note" %}
你不能合并 `custom_vocabulary` 具有说话者分类或单词级时间戳。 API 拒绝包含以下内容的请求： `custom_vocabulary` 具有任一功能。
{% /callout %}

{% tabs %}
{% tab filename="transcribe_custom_vocab.py" label="Python" %}
```python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"],
        }
    },
)
```
{% /tab %}

{% tab filename="transcribe_custom_vocab.js" label="JavaScript" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      customVocabulary: ["Gemini", "Kubernetes", "BigQuery"],
    },
  },
});
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    CustomVocabulary: []string{"Gemini", "Kubernetes", "BigQuery"},
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab filename="transcribe_custom_vocab.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## 说话人分类  {% #speaker-diarization %}

说话人分类可识别录音中的不同声音，并用说话人标识符标记每个片段，例如 `spk_1` 或 `spk_2`。最多支持 8 扬声器（3 或更多扬声器的归属尚处于试验阶段）。

通过设置启用二值化 `diarization_mode` 到 `"speaker"` 之内 `mode`:

{% tabs %}
{% tab filename="transcribe_diarization.py" label="Python" %}
```python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "diarization_mode": "speaker",
            }
        }
    },
)
```
{% /tab %}

{% tab filename="transcribe_diarization.js" label="JavaScript" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      mode: {
        type: "verbatim",
        diarizationMode: "speaker",
      },
    },
  },
});
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                        DiarizationMode: genai.Ptr("speaker"),
                    }))),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab filename="transcribe_diarization.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "diarization_mode": "speaker"
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## 字级时间戳  {% #word-timestamps %}

字级时间戳为音频流中每个已识别的字提供准确的开始和结束偏移量。

{% callout type="note" %}
启用单词级时间戳可能会降低整体转录准确性。
{% /callout %}

通过设置启用时间戳 `timestamp_granularities` 到 `["word"]` 之内 `mode`:

{% tabs %}
{% tab filename="transcribe_timestamps.py" label="Python" %}
```python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "timestamp_granularities": ["word"],
            }
        }
    },
)
```
{% /tab %}

{% tab filename="transcribe_timestamps.js" label="JavaScript" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      mode: {
        type: "verbatim",
        timestampGranularities: ["word"],
      },
    },
  },
});
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                        TimestampGranularities: []string{"word"},
                    }))),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab filename="transcribe_timestamps.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "timestamp_granularities": ["word"]
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

你可以结合 `diarization_mode` 和 `timestamp_granularities` 在单个请求中接收说话者标签和单词时间戳：

{% tabs %}
{% tab filename="transcribe_diarization_timestamps.py" label="Python" %}
```python
generation_config = {
    "transcription_config": {
        "mode": {
            "type": "verbatim",
            "diarization_mode": "speaker",
            "timestamp_granularities": ["word"],
        },
    }
}
```
{% /tab %}

{% tab filename="transcribe_diarization_timestamps.js" label="JavaScript" %}
```javascript
const generationConfig = {
  transcriptionConfig: {
    mode: {
      type: "verbatim",
      diarizationMode: "speaker",
      timestampGranularities: ["word"],
    },
  },
};
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := &interactions.GenerationConfig{
        TranscriptionConfig: &interactions.TranscriptionConfig{
            Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                DiarizationMode:        genai.Ptr("speaker"),
                TimestampGranularities: []string{"word"},
            }))),
        },
    }
    _ = generationConfig
}
```
{% /tab %}

{% tab filename="transcribe_diarization_timestamps.json" label="REST" %}
```json
{
  "generation_config": {
    "transcription_config": {
      "mode": {
        "type": "verbatim",
        "diarization_mode": "speaker",
        "timestamp_granularities": ["word"]
      }
    }
  }
}
```
{% /tab %}
{% /tabs %}

## 转录模式  {% #transcription-modes %}

Gemini 3.5 Transcribe 支持两种转录模式 `mode` 参数：

* **`verbatim` （默认）**：返回所有所说内容的精确逐字记录，保留原始填充词（“嗯”、“呃”、“喜欢”、“你知道”）、重复、停顿和错误的开头。使用时间戳或说话人分类时需要。
* **`smart` （智能转录）**：通过应用智能后处理优化阅读文字记录：*   **消除不流畅**：去除会话填充词、口吃和错误的开头。
* **内联自我更正**：直接解决口头更正（例如， *“我们周二见面吧，其实不，周三两点见面”* 变成 *“我们周三在 2:00 PM 见面”*).
* **自动结构化格式化**：自动将口头想法构建为段落、编号列表、项目符号、格式化日期、货币和数字。
* **语法清理**：应用自然标点符号、句子大小写和流程。

{% doc-table %}
{% doc-row header="true" %}
{% doc-cell %}
语音音频
{% /doc-cell %}

{% doc-cell %}
`verbatim` 输出
{% /doc-cell %}

{% doc-cell %}
`smart` （智能转录）输出
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
“嗯，所以对于这次会议，我认为我们应该，呃，邀请爱丽丝，等等，鲍勃和卡罗尔。”
{% /doc-cell %}

{% doc-cell %}
“嗯，所以对于这次会议，我认为我们应该呃邀请爱丽丝，不要等待鲍勃和卡罗尔。”
{% /doc-cell %}

{% doc-cell %}
“对于这次会议，我认为我们应该邀请鲍勃和卡罗尔。”
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
“第一项审查预算第二项最终确定时间表第三项发送回顾”
{% /doc-cell %}

{% doc-cell %}
“第一项审查预算第二项最终确定时间表第三项发送回顾”
{% /doc-cell %}

{% doc-cell %}
1. 审查预算
1. 最终确定时间表
1. 发送回顾
{% /doc-cell %}
{% /doc-row %}
{% /doc-table %}

{% tabs %}
{% tab filename="transcribe_smart_mode.py" label="Python" %}
```python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

response = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[audio_file],
    generation_config={
        "transcription_config": {
            "mode": "smart",
        }
    },
)
print(response.output_text)
```
{% /tab %}

{% tab filename="transcribe_smart_mode.js" label="JavaScript" %}
```javascript
const response = await ai.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [audioFile],
  generationConfig: {
    transcriptionConfig: {
      mode: "smart",
    },
  },
});
console.log(response.outputText);
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.TranscriptionConfigModeEnumSmart)),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}
```
{% /tab %}

{% tab filename="transcribe_smart_mode.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-3.5-transcribe",
    "input": [
      {
        "type": "file",
        "file_uri": "YOUR_FILE_URI"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": "smart"
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

{% callout type="note" %}
智能转录（`"smart"`) 不兼容 `timestamp_granularities` 和 `diarization_mode`。如果您需要单词时间戳或说话人分类，请使用逐字模式（默认）。
{% /callout %}

## 解析转录输出  {% #parsing-output %}

完整的转录文本返回于 `response.output_text`.

当 `timestamp_granularities` 或 `diarization_mode` 启用后，API 还会返回附加到交互内容的详细字级注释。

以下是提取和迭代单词时间戳和发言者轮流的方法：

{% tabs %}
{% tab filename="transcribe_parse_output.py" label="Python" %}
```python
def extract_word_annotations(response):
    words = []
    for step in getattr(response, "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(response)

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}")
```
{% /tab %}

{% tab filename="transcribe_parse_output.js" label="JavaScript" %}
```javascript
function extractWordAnnotations(response) {
  const words = [];
  for (const step of response.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(response);

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}`);
}
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "fmt"

    "google.golang.org/genai/interactions/models/interactions"
)

func extractWordAnnotations(interaction *interactions.Interaction) []*interactions.WordInfo {
    var words []*interactions.WordInfo
    if interaction == nil {
        return words
    }
    for _, step := range interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    for _, annotation := range content.TextContent.Annotations {
                        if annotation.WordInfo != nil {
                            words = append(words, annotation.WordInfo)
                        }
                    }
                }
            }
        }
    }
    return words
}

func main() {
    var interaction *interactions.Interaction
    words := extractWordAnnotations(interaction)

    for _, w := range words {
        speaker := ""
        if w.Speaker != nil && *w.Speaker != "" {
            speaker = fmt.Sprintf("[%s] ", *w.Speaker)
        }
        timing := ""
        if w.StartOffset != nil && w.EndOffset != nil {
            timing = fmt.Sprintf("(%s -> %s) ", *w.StartOffset, *w.EndOffset)
        }
        fmt.Printf("%s%s%s\n", speaker, timing, w.GetText())
    }
}
```
{% /tab %}

{% tab filename="transcribe_parse_output.json" label="REST" %}
```json
{
  "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.400s"
            },
            {
              "type": "word_info",
              "text": "world",
              "speaker": "spk_1",
              "start_offset": "0.500s",
              "end_offset": "0.800s"
            }
          ]
        }
      ]
    }
  ]
}
```
{% /tab %}
{% /tabs %}

## 支持的语言  {% #supported-languages %}

Gemini 3.5 Transcribe 支持以下语言和 BCP-47 语言代码：

| 语言            | BCP-47 代码     | 语言          | BCP-47 代码     |
| ------------- | ------------- | ----------- | ------------- |
| 南非荷兰语         | `af-ZA`       | 日语          | `ja-JP`       |
| 阿姆哈拉语         | `am-ET`       | 爪哇语         | `jv-ID`       |
| 阿拉伯语（埃及）      | `ar-EG`       | 卡布韦尔迪亚努     | `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`       |

## 支持的音频格式  {% #supported-formats %}

Gemini 3.5 Transcribe 支持以下音频格式 MIME 类型：

* 音频- `audio/wav`
* MP3- `audio/mp3`
* 亚洲国际电影节- `audio/aiff`
* AA- `audio/aac`
* 奥格- `audio/ogg`
* FLAC- `audio/flac`
* MPEG- `audio/mpeg`
* M4A - `audio/m4a`
* L16 - `audio/l16`
* 作品- `audio/opus`
* 法律- `audio/alaw`
* 穆洛 - `audio/mulaw`
* 网络M- `audio/webm`

有关支持的 MIME 类型和参数架构的完整列表，请参阅 [Interactions API参考](/api-reference/interactions-api#Resource:Content).

## 参数参考  {% #parameter-reference %}

通过设置内的字段来配置转录 `transcription_config` 对象在 `generation_config`:

| 领域                             | 类型     | 说明                                                                |
| ------------------------------ | ------ | ----------------------------------------------------------------- |
| `language_codes`               | 字符串数组  | BCP-47 语言代码（例如， `["en-US"]`）。如果省略或为空 (`[]`），模型自动检测语言并处理代码切换。      |
| `custom_vocabulary`            | 字符串数组  | 最多 1,000 自定义术语、首字母缩写词或专有名称，以影响语音识别。与说话者分类和字级时间戳不兼容。               |
| `mode`                         | 对象或字符串 | 转录模式配置。接受 `"smart"` 或逐字模式对象（`{"type": "verbatim", ...}`）。默认为逐字转录。 |
| `mode.type`                    | 字符串    | *（仅限逐字模式）* 模式标识符。始终设置为 `"verbatim"`.                              |
| `mode.timestamp_granularities` | 字符串数组  | *（仅限逐字模式）* 要返回的时间戳的粒度。通行证 `["word"]` 启用单词开始和结束偏移。与自定义词汇不兼容。       |
| `mode.diarization_mode`        | 字符串    | *（仅限逐字模式）* 分类模式。通行证 `"speaker"` 识别并标记不同的说话者。与自定义词汇不兼容。            |

## 最佳实践  {% #best-practices %}

* **提供干净的音频：** 确保录音具有清晰的语音分离并避免严重的削波。
* **已知时提供语言提示：** 如果您事先知道音频语言，请指定 `language_codes` 以最大限度地提高准确性。
* **目标自定义词汇：** 仅包含不同的领域术语、品牌名称或专有名词 `custom_vocabulary` 而不是常见的日常用语。
* **选择正确的文件输入方式：** 上传本地录音 `client.files.upload`，或者通过传递跳过上传步骤 [外部 HTTP 或签名 URL](/docs/file-input-methods#external-urls) （高达 15 MB）， [已注册 Google Cloud 存储 URI](/docs/file-input-methods#registration) （最高至 2 GB），或 [内联 Base64 音频](/docs/file-input-methods#inline-data)。参见 [文件输入方式](/docs/file-input-methods) 了解详情。

## 限制  {% #limitations %}

* **音频时长：** 标准一元请求支持长达 1 小时的音频文件。当启用扬声器分类或字级时间戳等功能时，音频处理仅限于 30 分钟。超过这些限制的音频将在限制处被截断，同时仍然返回 `status: "completed"`，因此在发送请求之前将较长的录音分割成 30 分钟或更短的块。
* **字级时间戳：** 启用单词级时间戳可能会降低整体转录准确性。
* **说话人分类：** 扬声器分类最多支持 8 扬声器。 3 或更多扬声器的扬声器归属是实验性的。
* **自定义词汇：** 您最多可以提供 1,000 条款 `custom_vocabulary`，但通常使用最多 100 项即可获得最佳结果。你不能合并 `custom_vocabulary` 具有说话者分类或单词级时间戳； API 拒绝指定的请求 `custom_vocabulary` 与任一功能一起。
* **模式兼容性：** 智能转录（`"smart"`) 不能与 `timestamp_granularities` 或 `diarization_mode`.

## 后续步骤  {% #whats-next %}

* 使用流式传输实时音频 [实时转录指南](/docs/live-api/live-transcribe) 使用 Live API。
* 探索 [音频理解](/docs/audio) 分析、总结或查询音频内容。
* 了解如何使用文本合成音频 [文字转语音](/docs/speech-generation).
* 检查 [定价页面](/docs/pricing#gemini-3.5-transcribe) 了解型号定价和 token 限制。
* 比较 [文件输入方式](/docs/file-input-methods) 和 [Files API](/docs/files) 传递和管理音频文件的指南。
