Tradução instantânea com a API Gemini Live

A API Gemini Live oferece suporte à tradução simultânea em tempo real e com baixa latência entre mais de 70 idiomas usando o modelo gemini-3.5-live-translate-preview. Ao configurar a API Live com as configurações de tradução, é possível transmitir áudio em um idioma e receber a saída de áudio traduzida em outro, permitindo uma tradução de voz para voz em tempo real.

Atendente x Tradução instantânea

Embora os dois usem a API Live, o modelo mental da tradução instantânea é diferente das interações de agentes em tempo real.

Agente em tempo real Tradução instantânea
O modelo age como um assistente.Ele ouve, raciocina e realiza ações em seu nome. O modelo atua como um intérprete e se comporta como um pipeline de tradução em tempo real.
Usa interações baseadas em turnos: depende de pausas, detecção de intents e processa interrupções. Usa o processamento de stream contínuo: traduz enquanto o falante fala, sem esperar a vez.
Suporte a ferramentas e agentes: suporte nativo para chamada de função, Pesquisa Google e instruções. Oferece suporte apenas à tradução. Tradução pura de baixa latência, sem suporte para ferramentas ou instruções.
Totalmente multimodal: aceita entradas de texto, áudio, vídeo e imagem. Áudio restrito.A entrada é limitada ao áudio para garantir limites rigorosos de latência em tempo real.
Configuração granular: usa geração, fala, ferramentas e instruções do sistema. Configuração simplificada.Defina target_language_code e alternâncias como echo_target_language.

Primeiros passos

Os exemplos a seguir demonstram como inicializar um cliente e se conectar à API Live com uma configuração de tradução.

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client()

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())

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
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");
}

main();

WebSockets

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}`,
      generationConfig: {
        responseModalities: ['AUDIO'],
        inputAudioTranscription: {},
        outputAudioTranscription: {},
        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)`);
        }
      }
    }
  }
};

Enviando áudio

Para transmitir entradas de voz para tradução, envie áudio PCM bruto, little-endian e de 16 bits.

  • Formato de áudio de entrada: PCM bruto de 16 bits a 16 kHz (mono, little-endian).
  • Formato de áudio de saída: PCM bruto de 16 bits a 24 kHz (mono, little endian).
  • Tamanho do bloco e latência: envie áudio em blocos de 100 ms.

Os exemplos a seguir mostram como enviar partes de áudio para a sessão.

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"
    )
)

JavaScript

// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});

WebSockets

// 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));
  }
}

Configuração

Para ativar a tradução, especifique o translationConfig no generationConfig durante a configuração da sessão.

Configurar mensagens

O generationConfig é compatível com os seguintes campos para ativar as transcrições:

  • inputAudioTranscription: um objeto que, quando presente, permite que o modelo envie transcrições de texto do áudio de entrada.
  • outputAudioTranscription: um objeto que, quando presente, permite que o modelo envie transcrições de texto do áudio de saída (traduzido).

O translationConfig é compatível com os seguintes campos:

  • targetLanguageCode: o código de idioma BCP-47 do idioma para o qual você quer que o modelo traduza (por exemplo, "pl" para polonês e "es" para espanhol). O valor padrão é "en".
  • echoTargetLanguage: um booleano que indica como o áudio de entrada que já está no idioma de destino deve ser processado. Se definido como true, o modelo vai repetir o áudio de entrada que já está no idioma de destino. Se definido como false, o modelo vai ficar em silêncio quando a fala de entrada já estiver no idioma de destino. O padrão é false.

Confira um exemplo da estrutura da mensagem de configuração:

"setup": {
    "model": "models/gemini-3.5-live-translate-preview",
    "generationConfig": {
      "responseModalities": [
        "AUDIO"
      ],
      "inputAudioTranscription": {},
      "outputAudioTranscription": {},
      "translationConfig": {
        "targetLanguageCode": "pl",
        "echoTargetLanguage": true
      }
    }
}

Tokens temporários para aplicativos do lado do cliente

Para aplicativos cliente-servidor, use tokens efêmeros (atualmente em v1alpha) para evitar expor sua chave de API.

Ao usar tokens temporários com a Tradução Instantânea:

  1. É preciso usar o endpoint v1alpha.
  2. Configuração de bloqueio:por padrão, especifique o translationConfig nas restrições de criação de token no seu servidor. Isso garante que a configuração de tradução esteja bloqueada e não possa ser adulterada pelo cliente.
  3. Configuração de desbloqueio:se você quiser definir o translationConfig no lado do cliente (por exemplo, para permitir que um usuário escolha o próprio idioma de destino), omita-o da solicitação de criação de token e defina "lock_additional_fields": []. Isso vai desbloquear o translationConfig para ser definido no lado do cliente.

Como criar um token temporário restrito

Os exemplos a seguir mostram como criar um token efêmero com restrições de tradução.

Python

import datetime
from google import genai

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

client = genai.Client(
    http_options={'api_version': 'v1alpha'}
)

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
                }
            }
        },
        'http_options': {'api_version': 'v1alpha'},
    }
)

JavaScript

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

const client = new GoogleGenAI({});
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
                }
            }
        },
        httpOptions: {
            apiVersion: 'v1alpha'
        }
    },
});

Limitações

  • Modalidades de entrada: somente a entrada de áudio é compatível com a tradução. Não é possível inserir texto.
  • Replicação de voz: a replicação de voz pode ser inconsistente. As vozes podem mudar após longas pausas, atribuir o gênero errado com base em como a fala começa ou ficar presa em uma voz durante conversas rápidas com vários falantes.
  • Detecção de idioma: a detecção de idioma tem dificuldades com sotaques fortes, idiomas semelhantes (por exemplo, espanhol e português) ou mudanças rápidas de idioma. Observação:isso só afeta a transcrição de entrada. Os códigos de idioma e a tradução final ainda precisam ser precisos.
  • Áudio em segundo plano: o modelo foi projetado para filtrar ruídos e músicas e produzir uma fala limpa, mas nem todo o áudio em segundo plano pode ser ignorado.
  • Repetir o idioma de destino: quando echoTargetLanguage: true, o ruído de fundo ou a música podem introduzir artefatos no áudio traduzido quando o áudio de entrada já está no idioma de destino.

Idiomas compatíveis

Os seguintes idiomas são compatíveis com a Tradução instantânea.

Idioma Código BCP-47 Idioma Código BCP-47
Africâner af Cazaque kk
Akan ak Khmer km
Albanês sq Quiniaruanda rw
Amárico sou Coreano ko
Árabe ar Laosiano lo
Armênio hy Letão lv
Azerbaijano az Lituano lt
Basco eu Macedônio mk
Bielorrusso be Malaio ms
Bengali bn Malaiala ml
Búlgaro bg Marati mr
Birmanês (Mianmar) my Mongol mn
Catalão ca Nepalês ne
Chinês (simplificado) zh-Hans Norueguês não, nb
Chinês (tradicional) zh-Hant Persa fa
Croata h Polonês pl
Tcheco cs Português (Brasil) pt-BR
Dinamarquês da Português (Portugal) pt-PT
Holandês nl Punjabi pa
Inglês en Romeno ro
Estoniano et Russo ru
Filipino fil Sérvio sr
Finlandês fi Sindi sd
Francês fr Cingalês si
Galego gl Eslovaco sk
Georgiano ka Esloveno sl
Alemão de Espanhol es
Grego el Sundanês su
Gujarati gu Suaíli sw
Hauçá ha Sueco sv
Hebraico ele Tâmil ta
Hindi hi Télugo te
Húngaro hu Tailandês th
Islandês é Turco tr
Indonésio ID Ucraniano uk
Italiano it Urdu ur
Japonês ja Usbeque uz
Javanês jv Vietnamita vi
Canarês kn Zulu zu

A seguir