# 使用 Gemini Live API 实时翻译

Gemini Live API 支持 70+ 语言之间的低延迟、实时语音翻译，使用 [`gemini-3.5-live-translate-preview`](/docs/models/gemini-3.5-live-translate-preview)
模型。通过为 Live API 配置翻译设置，您可以流式传输一种语言的音频并接收另一种语言的翻译后的音频输出，从而实现无缝的实时语音到语音翻译。

{% button
   href="https://aistudio.google.com/live?model=gemini-3.5-live-translate-preview"
   icon="mic"
   variant="primary" %}
尝试 Google AI Studio 中的实时翻译
{% /button %}

{% button
   href="https://github.com/google-gemini/gemini-live-api-examples"
   icon="code"
   variant="primary" %}
从 GitHub 克隆示例应用程序
{% /button %}

{% button
   href="/docs/coding-agents#gemini-live-api-dev"
   icon="terminal"
   variant="primary" %}
使用编码智能体技巧
{% /button %}

## 实时智能体与实时翻译  {% #live-agent-vs-live-translation %}

虽然两者都使用 Live API，但实时翻译的心理模型不同于对话式实时智能体交互。

| 直播智能体                                  | 实时翻译                                                                                          |
| -------------------------------------- | --------------------------------------------------------------------------------------------- |
| **模特充当助手。** 它代表您倾听、推理并采取行动。            | **该模型充当解释器。** 它充当实时翻译管道。                                                                      |
| **使用回合制交互。** 依赖暂停、意图检测并处理中断。           | **使用连续流处理。** 翻译为演讲者无需等待轮流即可讲话。                                                                |
| **支持工具和智能体。** 对函数调用、Google 搜索和指令的本机支持。 | **仅支持翻译。** 纯低延迟翻译；支持系统指令指导翻译，不支持工具。                                                           |
| **完全多式联运。** 支持文本、音频、视频和图像输入。           | **音频受限。** 输入仅限于音频，以确保严格的实时延迟阈值。                                                               |
| **粒度配置。** 使用生成、语音、工具和系统指令。             | **简化的配置。** 套装 `target_language_code`，像这样切换 `echo_target_language`，以及可选的 `system_instruction`. |

## 快速入门  {% #get-started %}

以下示例演示如何初始化客户端并使用转换配置连接到 Live API。

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

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

model = "gemini-3.5-live-translate-preview"
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=types.AudioTranscriptionConfig(),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    translation_config=types.TranslationConfig(
        target_language_code="pl",
        echo_target_language=True
    )
)

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started with translation")
        # Start receiving the translated audio stream
        async for response in session.receive():
            if response.server_content:
                if response.server_content.input_transcription:
                    print(f"Input transcript: {response.server_content.input_transcription.text}")
                if response.server_content.output_transcription:
                    print(f"Output transcript: {response.server_content.output_transcription.text}")
                if response.server_content.model_turn:
                    for part in response.server_content.model_turn.parts:
                        if part.inline_data:
                            audio_data = part.inline_data.data
                            # Play or process the translated audio chunk
                            print(f"Received audio chunk ({len(audio_data)} bytes)")

if __name__ == "__main__":
    asyncio.run(main())
```
{% /tab %}

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

const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const model = 'gemini-3.5-live-translate-preview';
const config = {
    responseModalities: [Modality.AUDIO],
    inputAudioTranscription: {},
    outputAudioTranscription: {},
    translationConfig: {
        targetLanguageCode: 'pl',
        echoTargetLanguage: true
    }
};

async function main() {
  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: {
      onopen: () => console.debug('Opened'),
      onmessage: (message) => {
        const content = message.serverContent;
        if (content?.inputTranscription) {
          console.log('Input transcript:', content.inputTranscription.text);
        }
        if (content?.outputTranscription) {
          console.log('Output transcript:', content.outputTranscription.text);
        }
        if (content?.modelTurn?.parts) {
          for (const part of content.modelTurn.parts) {
            if (part.inlineData) {
              const audioData = part.inlineData.data;
              // Play or process the translated audio chunk (base64 encoded)
              console.debug(`Received audio chunk (${audioData.length} bytes)`);
            }
          }
        }
      },
      onerror: (e) => console.debug('Error:', e.message),
      onclose: (e) => console.debug('Close:', e.reason),
    },
  });

  console.debug("Session started with translation");
}

await main();
```
{% /tab %}

{% tab filename="live_translate.js" label="WebSocket" %}
```javascript
const API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.5-live-translate-preview";
const WS_URL = `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=${API_KEY}`;

const websocket = new WebSocket(WS_URL);

websocket.onopen = () => {
  console.log('WebSocket Connected');

  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      inputAudioTranscription: {},
      outputAudioTranscription: {},
      generationConfig: {
        responseModalities: ['AUDIO'],
        translationConfig: {
          targetLanguageCode: 'pl',
          echoTargetLanguage: true
        }
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  if (response.serverContent) {
    const content = response.serverContent;
    if (content.inputTranscription) {
      console.log('Input transcript:', content.inputTranscription.text, `(${content.inputTranscription.languageCode})`);
    }
    if (content.outputTranscription) {
      console.log('Output transcript:', content.outputTranscription.text, `(${content.outputTranscription.languageCode})`);
    }
    if (content.modelTurn?.parts) {
      for (const part of content.modelTurn.parts) {
        if (part.inlineData) {
          const audioData = part.inlineData.data;
          // Play or process the translated audio chunk (base64 encoded)
          console.debug(`Received audio chunk (${audioData.length} bytes)`);
        }
      }
    }
  }
};
```
{% /tab %}
{% /tabs %}

## 发送音频  {% #sending-audio %}

要流式传输语音输入以进行翻译，您可以发送原始、小端、16 位 PCM 音频。

* **输入音频格式**：原始 16 位 PCM，16kHz（单声道、小端）。
* **输出音频格式**：原始 16 位 PCM，24kHz（单声道、小端）。
* **块大小和延迟**：以 100 毫秒为单位发送音频。

{% callout type="note" %}
翻译仅支持音频输入。不支持文本输入。
{% /callout %}

以下示例演示如何将音频块发送到会话。

{% tabs %}
{% tab filename="live_translate.py" label="Python" %}
```python
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)
```
{% /tab %}

{% tab filename="live_translate.js" label="JavaScript" %}
```js
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});
```
{% /tab %}

{% tab filename="live_translate.js" label="WebSocket" %}
```javascript
// Assuming 'chunk' is a Buffer of raw PCM audio
function sendAudioChunk(chunk) {
  if (websocket.readyState === WebSocket.OPEN) {
    const audioMessage = {
      realtimeInput: {
        audio: {
          data: chunk.toString('base64'),
          mimeType: 'audio/pcm;rate=16000'
        }
      }
    };
    websocket.send(JSON.stringify(audioMessage));
  }
}
```
{% /tab %}
{% /tabs %}

## 配置  {% #configuration %}

要启用翻译，您必须指定 `translationConfig` 内 `generationConfig` 在会话设置期间。

### 设置消息配置  {% #setup-message-configuration %}

该 `setup` 留言支持 [`systemInstruction`](/docs/live-api/live-translate#system-instructions) 在会话开始时提供自定义翻译上下文（例如词汇表、术语和注册）。

该 `setup` 消息还支持以下字段来启用转录：

* **`inputAudioTranscription`**：一个对象，当存在时，使模型能够发送输入音频的文本转录。
* **`outputAudioTranscription`**：一个对象，当存在时，使模型能够发送输出（翻译）音频的文本转录。

该 `translationConfig` 支持以下字段：

* **`targetLanguageCode`**: 的 [BCP-47 语言代码](/docs/live-api/live-translate#supported-languages) 您希望模型翻译成的语言（例如， `"pl"` 对于波兰语， `"es"` 西班牙语）。默认为 `"en"`.
* **`echoTargetLanguage`**：一个布尔值，指示应如何处理目标语言中已有的输入音频。如果设置为 `true`，模型将回显（鹦鹉学舌）已经采用目标语言的输入音频。如果设置为 `false`，当输入语音已经是目标语言时，模型将保持沉默。默认为 `false`.

以下是设置消息结构的示例：

```json
{
  "setup": {
    "model": "models/gemini-3.5-live-translate-preview",
    "systemInstruction": {
      "parts": [
        {
          "text": "Translate for a conference audience using formal Spanish (usted/ustedes). Always translate 'deployment pipeline' as 'canalización de despliegue' and keep product names like 'Cloud Run' untranslated."
        }
      ]
    },
    "inputAudioTranscription": {},
    "outputAudioTranscription": {},
    "generationConfig": {
      "responseModalities": [
        "AUDIO"
      ],
      "translationConfig": {
        "targetLanguageCode": "es",
        "echoTargetLanguage": false
      }
    }
  }
}
```

### 系统指令  {% #system-instructions %}

你可以通过 `system_instruction` (`systemInstruction` 在 WebSocket 中）在会话设置期间指导模型如何翻译语音。使用系统指令指定：

* **自定义术语和术语表**：定义应如何翻译特定行业术语、品牌名称或技术术语（例如，翻译 `"deployment pipeline"` 作为 `"canalización de despliegue"` 或保留产品名称，例如 `"Cloud Run"` 未翻译）。
* **手续和登记**：指定目标语气、代词形式或受众设置（例如，在演示文稿中使用正式的单数或复数地址）。
* **说话人和受话人的背景**：提供有关设置和参与者的上下文，以便模型准确地保留直接地址。

{% callout type="note" %}
系统指令只能在初始状态下设置 `setup` 消息。在会话中更新系统指令（包括通过 `clientContent` 或 `realtimeInput` 短信）不支持；要更改系统指令，请启动新会话。此外，仅指导翻译行为和匹配的指令 `target_language_code` 被支持——与冲突的指令 `target_language_code`、更改输出格式或要求模型执行非翻译任务不受支持，可能会被忽略或降低翻译输出质量。
{% /callout %}

{% tabs %}
{% tab filename="live_translate_si.py" label="Python" %}
```python
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    system_instruction=(
        "You are translating a live conference presentation into Spanish. "
        "Use formal address (usted/ustedes), always translate "
        "'deployment pipeline' as 'canalización de despliegue', and keep "
        "product names like 'Cloud Run' untranslated."
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    translation_config=types.TranslationConfig(
        target_language_code="es",
        echo_target_language=False,
    ),
)
```
{% /tab %}

{% tab filename="live_translate_si.js" label="JavaScript" %}
```javascript
const config = {
  responseModalities: [Modality.AUDIO],
  systemInstruction:
    "You are translating a live conference presentation into Spanish. " +
    "Use formal address (usted/ustedes), always translate " +
    "'deployment pipeline' as 'canalización de despliegue', and keep " +
    "product names like 'Cloud Run' untranslated.",
  inputAudioTranscription: {},
  outputAudioTranscription: {},
  translationConfig: {
    targetLanguageCode: 'es',
    echoTargetLanguage: false,
  },
};
```
{% /tab %}

{% tab filename="live_translate_si_ws.js" label="WebSocket" %}
```javascript
const setupMessage = {
  setup: {
    model: `models/${MODEL_NAME}`,
    systemInstruction: {
      parts: [
        {
          text:
            "You are translating a live conference presentation into Spanish. " +
            "Use formal address (usted/ustedes), always translate " +
            "'deployment pipeline' as 'canalización de despliegue', and keep " +
            "product names like 'Cloud Run' untranslated.",
        },
      ],
    },
    inputAudioTranscription: {},
    outputAudioTranscription: {},
    generationConfig: {
      responseModalities: ['AUDIO'],
      translationConfig: {
        targetLanguageCode: 'es',
        echoTargetLanguage: false,
      },
    },
  },
};
websocket.send(JSON.stringify(setupMessage));
```
{% /tab %}
{% /tabs %}

## 在客户端应用程序中使用临时 token  {% #ephemeral-tokens-for-client-side-applications %}

对于客户端到服务器的应用程序，您可以使用 [短暂的 token](/docs/live-api/ephemeral-tokens) （目前在 `v1beta`）以避免暴露您的 API 密钥。

将临时 token 与实时翻译结合使用时：

1. 您必须使用 `v1beta` 端点。
1. **锁定配置：** 默认情况下，您应该指定 `translationConfig` （以及可选的 `systemInstruction`）在服务器上的 token 创建约束中。当 `live_connect_constraints` 设置为无 `lock_additional_fields`，服务器锁定整个 `setup` 配置并忽略任何 `system_instruction` 或 `translationConfig` 客户端在连接时传递的字段。
1. **解锁配置：** 如果你想设置 `translationConfig` 或 `system_instruction` 在客户端（例如，让用户选择自己的目标语言或自定义术语），从 token 创建请求中省略这些字段并设置 `"lock_additional_fields": []` 相反。这仅锁定服务器上指定的字段，并解锁要在客户端设置的其余字段。

### 创建受约束的临时 token  {% #creating-a-constrained-ephemeral-token %}

以下示例演示如何创建具有平移约束的临时 token。

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

now = datetime.datetime.now(tz=datetime.timezone.utc)

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

token = client.auth_tokens.create(
    config = {
        'uses': 1,
        'expire_time': now + datetime.timedelta(minutes=30),
        'live_connect_constraints': {
            'model': 'gemini-3.5-live-translate-preview',
            'config': {
                'translation_config': {
                    'target_language_code': 'pl',
                    'echo_target_language': True
                }
            }
        },
    }
)
```
{% /tab %}

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

const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

const token = await client.authTokens.create({
    config: {
        uses: 1,
        expireTime: expireTime,
        liveConnectConstraints: {
            model: 'gemini-3.5-live-translate-preview',
            config: {
                responseModalities: ['AUDIO'],
                inputAudioTranscription: {},
                outputAudioTranscription: {},
                translationConfig: {
                    targetLanguageCode: 'pl',
                    echoTargetLanguage: true
                }
            }
        },
    },
});
```
{% /tab %}

{% tab filename="live_translate.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "bidiGenerateContentSetup": {
      "model": "models/gemini-3.5-live-translate-preview",
      "inputAudioTranscription": {},
      "outputAudioTranscription": {},
      "generationConfig": {
        "responseModalities": ["AUDIO"],
        "translationConfig": {
          "targetLanguageCode": "pl",
          "echoTargetLanguage": true
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

## 限制  {% #limitations %}

* **输入方式**：仅支持音频输入进行翻译。不支持文本输入。
* **系统说明**：系统指令只能在初始状态下设置 `setup` 消息。在会话中更新系统指令（包括通过 `clientContent` 或 `realtimeInput` 短信）不支持；开始一个新的会话来更改指令。仅指导翻译行为和匹配的指令 `target_language_code` 被支持——与冲突的指令 `target_language_code`、更改输出格式或请求非翻译任务不受支持，可能会被忽略或降低翻译输出质量。
* **语音复制**：语音复制可能不一致。长时间停顿后声音可能会发生变化，根据演讲的开始方式分配错误的性别，或者在快速的多人对话中卡在一个声音上。

{% callout type="note" %}
提醒一下，开发商有责任在需要时获得各方的同意。开发者不得以违反适用法律、法规或第三方权利的方式使用API。
{% /callout %}

* **语言检测**：语言检测会遇到重口音、相似语言（例如西班牙语与葡萄牙语）或快速语言切换的问题。 **注意：** 这应该只会影响输入记录。语言代码和最终翻译应该仍然准确。
* **背景音频**：该模型旨在过滤掉噪音和音乐以产生干净的语音，但并非所有背景音频都可以被忽略。
* **回显目标语言**: 当 `echoTargetLanguage: true`当输入音频已经是目标语言时，背景噪音或音乐可能会在翻译的音频中引入伪影。

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

实时翻译支持以下语言。

| 语言      | BCP-47 代码 | 语言        | BCP-47 代码 |
| ------- | --------- | --------- | --------- |
| 南非荷兰语   | AF        | 哈萨克语      | kk        |
| 阿寒      | AK        | 高棉语       | 公里        |
| 阿尔巴尼亚语  | 平方        | 基尼亚卢旺达语   | 读写        |
| 阿姆哈拉语   | 上午        | 韩语        | 科         |
| 阿拉伯语    | 阿尔        | 老挝        | 罗         |
| 亚美尼亚语   | 嘿         | 拉脱维亚语     | LV        |
| 阿塞拜疆语   | 阿兹        | 立陶宛语      | 其         |
| 巴斯克语    | 欧盟        | 马其顿语      | MK        |
| 白俄罗斯语   | 是         | 马来语       | 女士        |
| 孟加拉语    | BN        | 马拉雅拉姆语    | 毫升        |
| 保加利亚语   | 背景        | 马拉地语      | 先生        |
| 缅甸语（缅甸） | 我的        | 蒙古语       | 锰         |
| 加泰罗尼亚语  | 加州        | 尼泊尔语      | 讷         |
| 中文（简体）  | zh-汉斯     | 挪威语       | 不，注意      |
| 中文（繁体）  | zh-汉特     | 波斯语       | 发         |
| 克罗地亚语   | 小时        | 波兰语       | PL        |
| 捷克语     | CS        | 葡萄牙语（巴西）  | PT-BR     |
| 丹麦语     | 达         | 葡萄牙语（葡萄牙） | PT-PT     |
| 荷兰语     | NL        | 旁遮普语      | 帕         |
| 英语      | zh        | 罗马尼亚语     | 罗         |
| 爱沙尼亚语   | 等         | 俄语        | 茹         |
| 菲律宾人    | 菲尔        | 塞尔维亚语     | 高级        |
| 芬兰语     | 菲         | 信德语       | 标准差       |
| 法语      | FR        | 僧伽罗语      | 斯         |
| 加利西亚语   | 格         | 斯洛伐克语     | 斯克        |
| 格鲁吉亚语   | 卡         | 斯洛文尼亚语    | 斯尔        |
| 德语      | 德         | 西班牙语      | 英语        |
| 希腊语     | 埃尔        | 巽他语       | 苏         |
| 古吉拉特语   | 顾         | 斯瓦希里语     | SW        |
| 豪萨语     | 哈         | 瑞典语       | SV        |
| 希伯来语    | 他         | 泰米尔语      | 塔         |
| 印地语     | 嗨         | 泰卢固语      | 特         |
| 匈牙利语    | 胡         | 泰语        | th        |
| 冰岛语     | 是         | 土耳其语      | t         |
| 印度尼西亚语  | 编号        | 乌克兰语      | 英国        |
| 意大利语    | 它         | 乌尔都语      | 你的        |
| 日语      | 贾         | 乌兹别克语     | 乌兹        |
| 爪哇语     | 合资企业      | 越南语       | 六         |
| 卡纳达语    | 千         | 祖鲁语       | 祖         |

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

* 阅读完整的 Live API [功能](/docs/live-api/capabilities) 指导。
* 阅读 [开始使用 SDK](/docs/live-api/get-started-sdk) 指导。
* 阅读 [开始使用 WebSocket](/docs/live-api/get-started-websocket)
  指导。
* 阅读 [临时 token](/docs/live-api/ephemeral-tokens) 客户端到服务器应用程序中的安全身份验证指南。
* 克隆 [Live API 示例](https://github.com/google-gemini/gemini-live-api-examples)
  来自 GitHub。
