Transcrição de áudio

A API Gemini converte a fala em arquivos de áudio em texto usando o modelo Gemini 3.5 Transcribe (gemini-3.5-transcribe). Com base nos recursos de compreensão de áudio do Gemini, ela oferece transcrição precisa com identificação automática de idioma, diarização de falantes, carimbos de data/hora no nível da palavra e dicas de vocabulário personalizadas. Ele também oferece um modo de transcrição inteligente com remoção de disfluências e formatação inteligente.

Para transcrever um arquivo de áudio, faça upload dele e transmita para 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"
      }
    ]
  }'

Visão geral

O Gemini 3.5 Transcribe é otimizado para tarefas de conversão de voz em texto. Ele lida com diversos sotaques, ruídos de fundo e conversas em vários idiomas.

As principais capacidades incluem:

  • Reconhecimento automático de fala (ASR): detecta automaticamente idiomas em mais de 85 localidades. Lida com a troca de código intrafrasal e interfrasal sem configuração manual.
  • Vocabulário personalizado:favorece o reconhecimento de termos específicos do domínio, acrônimos e nomes próprios ao transmitir até 1.000 frases.
  • Diarização de locutor:distingue entre vários locutores e atribui segmentos falados a identificadores distintos.
  • Carimbos de data/hora no nível da palavra:geram ajustes de horário de início e término precisos para cada palavra reconhecida.
  • Transcrição inteligente:limpa disfluências, palavras desnecessárias, repetições e aplica formatação estruturada.
  • Formatação e normalização:aplica o uso de maiúsculas e minúsculas, pontuação e normalização inversa de texto, como converter "vinte e seis milhões de dólares" em "US$ 26 milhões".

Para raciocínio geral sobre áudio ou respostas a perguntas sobre conteúdo de áudio, use o Entendimento de áudio. Para síntese de áudio de conversão de texto em voz, use a Text-to-Speech.

Detecção e dicas de idioma

Por padrão, o modelo detecta o idioma falado automaticamente. Ele alterna entre idiomas dinamicamente quando os falantes mudam de código.

Para usar a detecção automática, omita language_codes ou forneça uma lista vazia:

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": []
      }
    }
  }'

Se você souber o idioma com antecedência, especifique os códigos de idioma BCP-47 em language_codes para melhorar a precisão da transcrição. Consulte Idiomas aceitos:

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"]
    }
  }
}

Vocabulário personalizado

Você pode orientar o modelo de fala para palavras incomuns, jargão técnico, nomes de marcas ou substantivos próprios. Forneça até 1.000 termos na matriz custom_vocabulary. Os melhores resultados geralmente são alcançados com até 100 termos:

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"]
      }
    }
  }'

Diarização de locutor

A diarização de locutor identifica vozes diferentes na gravação e marca cada segmento com um identificador de locutor, como spk_1 ou spk_2. É possível usar até oito alto-falantes. A atribuição para três ou mais alto-falantes é experimental.

Para ativar a diarização, configure diarization_mode em 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"
        }
      }
    }
  }'

Carimbos de data/hora no nível da palavra

Os carimbos de data/hora no nível da palavra fornecem ajustes de início e fim exatos para cada palavra reconhecida no fluxo de áudio.

Para ativar as marcas de tempo, configure timestamp_granularities em 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",
                "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"]
        }
      }
    }
  }'

É possível combinar diarization_mode e timestamp_granularities em mode para receber identificadores de locutor e carimbos de data/hora de palavras:

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"]
      }
    }
  }
}

Modos de transcrição

O Gemini 3.5 Transcribe é compatível com dois modos de transcrição usando o parâmetro mode:

  • verbatim (padrão): retorna uma transcrição exata de tudo o que foi dito, preservando palavras de preenchimento ("hum", "ãh", "tipo", "sabe"), repetições, pausas e falsos começos. Os carimbos de data/hora e a diarização de locutor são configurados nesse modo ({"type": "verbatim", ...}).
  • smart (Transcrição inteligente): otimiza a transcrição para leitura aplicando pós-processamento inteligente:
    • Remoção de disfluências: remove palavras de preenchimento, gaguejos e falsos inícios de conversa.
    • Autocorreções inline: resolvem correções faladas diretamente. Por exemplo, "Vamos nos encontrar na terça-feira, não, na quarta-feira às duas" se torna "Vamos nos encontrar na quarta-feira às 14h".
    • Formatação estruturada automática: organiza automaticamente os pensamentos falados em parágrafos, listas numeradas, marcadores, datas, moedas e números formatados.
    • Limpeza gramatical: aplica pontuação, capitalização de frases e fluxo naturais.
Áudio falado Saída verbatim Saída smart (transcrição inteligente)
"Hum, então, para a reunião, acho que devemos convidar Alice e, não, Bob e Carol." "Um so for the meeting I think we should uh invite Alice and wait no Bob and Carol." "Para a reunião, acho que devemos convidar o Bob e a Carol."
"Primeiro item revisar orçamento segundo item finalizar cronograma terceiro item enviar resumo" "primeiro item revisar orçamento segundo item finalizar linha do tempo terceiro item enviar resumo" "1. Revisar o orçamento
2. Finalizar linha do tempo
3. Enviar resumo"

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"
      }
    }
  }'

Analisando a saída da transcrição

O texto completo da transcrição é retornado em interaction.output_text.

Quando timestamp_granularities ou diarization_mode está ativado, a API também retorna anotações detalhadas no nível da palavra anexadas ao conteúdo da interação.

Veja como extrair e iterar carimbos de data/hora de palavras e turnos de falas:

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"
            }
          ]
        }
      ]
    }
  ]
}

Idiomas compatíveis

Os seguintes idiomas e códigos de idioma BCP-47 são compatíveis com o Gemini 3.5 Transcribe:

Idioma Código BCP-47 Idioma Código BCP-47
Africâner af-ZA Japonês ja-JP
Amárico am-ET Javanês jv-ID
Árabe (Egito) ar-EG Kabuverdianu kea-CV
Armênio hy-AM Canarês kn-IN
Assamês as-IN Cazaque kk-KZ
Azerbaijano az-AZ Coreano ko-KR
Bielorrusso be-BY Quirguiz ky-KG
Bengali (Bangladesh) bn-BD Letão lv-LV
Bengali (Índia) bn-IN Lingala ln-CD
Bósnio bs-BA Lituano lt-LT
Búlgaro bg-BG Macedônio mk-MK
Búlgaro (aromaniano) rup-BG Malaio ms-MY
Birmanês my-MM Malaiala ml-IN
Cantonês (tradicional) yue-Hant-HK Maltês mt-MT
Catalão ca-ES Chinês mandarim (simplificado) cmn-Hans-CN
Cebuano ceb Marati mr-IN
Khmer central km-KH Mongol mn-MN
Croata hr-HR Nepalês ne-NP
Tcheco cs-CZ Norueguês nb-NO
Dinamarquês da-DK Oriá or-IN
Holandês nl-NL Polonês pl-PL
Inglês (Grã-Bretanha) en-GB Português (Brasil) pt-BR
Inglês (Índia) en-IN Português (Portugal) pt-PT
Inglês (EUA) en-US Punjabi pa-IN
Estoniano et-EE Punjabi (script gurmukhi) pa-Guru-IN
Farsi fa-IR Romeno ro-RO
Filipino fil-PH Russo ru-RU
Finlandês fi-FI Sérvio sr-RS
Francês fr-FR Sindi (escrita árabe) sd-Arab-IN
Galego gl-ES Eslovaco sk-SK
Georgiano ka-GE Esloveno sl-SI
Alemão de-DE Espanhol (América Latina) es-419
Grego el-GR Espanhol (Estados Unidos) es-US
Gujarati gu-IN Suaíli (Quênia) sw-KE
Hauçá ha-NG Sueco sv-SE
Hebraico he-IL Tadjique tg-TJ
Hindi hi-IN Télugo te-IN
Húngaro hu-HU Tailandês th-TH
Islandês is-IS Turco tr-TR
Inglês indiano en-IN Ucraniano uk-UA
Indonésio id-ID Usbeque uz-UZ
Italiano it-IT Vietnamita vi-VN

Referência de parâmetros

Configure a transcrição definindo campos no objeto transcription_config em generation_config:

Campo Tipo Descrição
language_codes Matriz de strings Códigos de idioma BCP-47 (por exemplo, ["en-US"]). Se omitido ou vazio ([]), o modelo detecta automaticamente o idioma e processa a troca de código.
custom_vocabulary Matriz de strings Até 1.000 termos personalizados, acrônimos ou nomes próprios para polarizar o reconhecimento de fala.
mode Objeto ou string Configuração do modo de transcrição. Aceita "smart" ou um objeto de modo textual ({"type": "verbatim", ...}). O padrão é a transcrição textual.
mode.type String (Somente no modo literal) Identificador do modo. Sempre definido como "verbatim".
mode.timestamp_granularities Matriz de strings (somente no modo literal) Granularidade dos carimbos de data/hora a serem retornados. Transmita ["word"] para ativar os ajustes de início e fim de palavras.
mode.diarization_mode String (Somente no modo literal) Modo de diarização. Transmita "speaker" para identificar e rotular falantes diferentes.

Práticas recomendadas

  • Forneça áudio limpo:garanta que as gravações de áudio tenham separação de voz clara e evite cortes graves.
  • Forneça dicas de idioma quando souber: se você souber o idioma do áudio com antecedência, especifique language_codes para maximizar a precisão.
  • Vocabulário personalizado de destino:inclua apenas termos de domínio, nomes de marcas ou substantivos próprios distintos em custom_vocabulary, em vez de palavras comuns do dia a dia.
  • Use a API Files para gravações longas:para arquivos com mais de alguns segundos, faça upload usando client.files.upload e transmita o URI do arquivo retornado ao modelo.

Limitações

  • Duração do áudio:as solicitações unárias padrão são compatíveis com arquivos de áudio de até 1 hora. O processamento de áudio é limitado a 30 minutos quando recursos como diarização de locutor ou carimbos de data/hora no nível da palavra estão ativados.
  • Carimbos de data/hora no nível da palavra:ativar esse recurso pode reduzir a acurácia geral da transcrição.
  • Diarização de locutor:a diarização de locutor é compatível com até oito locutores. A atribuição de falante para três ou mais pessoas está em fase experimental.
  • Vocabulário personalizado:é possível fornecer até 1.000 termos em custom_vocabulary, mas os melhores resultados geralmente são alcançados com até 100 termos.
  • Compatibilidade de modo:a transcrição inteligente ("smart") não pode ser combinada com timestamp_granularities ou diarization_mode.

A seguir