Transcripción de audio

La API de Gemini convierte el habla de los archivos de audio en texto con el modelo Gemini 3.5 Transcribe (gemini-3.5-transcribe). Gracias a las capacidades de comprensión de audio de Gemini, ofrece una transcripción precisa con identificación automática del idioma, segmentación por orador, marcas de tiempo a nivel de palabras y sugerencias de vocabulario personalizadas. También proporciona un modo de transcripción inteligente que incluye la eliminación de las disfluencias y el formato inteligente.

Para transcribir un archivo de audio, sube el audio y pásalo a gemini-3.5-transcribe:

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

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

const response = await ai.models.generateContent({
  model: "gemini-3.5-transcribe",
  contents: [audioFile],
});

console.log(response.text);

REST

# First upload the file via the Files API, then pass its URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "fileData": {
              "fileUri": "YOUR_FILE_URI",
              "mimeType": "audio/mp3"
            }
          }
        ]
      }
    ]
  }'

Descripción general

Gemini 3.5 Transcribe está optimizado para tareas de voz a texto. Maneja diversos acentos, ruido de fondo y conversaciones en varios idiomas.

Las siguientes son algunas de las funciones clave:

  • Reconocimiento de voz automático (ASR): Detecta automáticamente idiomas en más de 85 configuraciones regionales. Maneja el cambio de código dentro de una oración y entre oraciones sin configuración manual.
  • Vocabulario personalizado: Incluye hasta 1,000 frases para sesgar el reconocimiento hacia términos específicos del dominio, acrónimos y nombres propios.
  • Identificación de interlocutores: Distingue entre varios interlocutores y atribuye los segmentos hablados a etiquetas distintas.
  • Marcas de tiempo a nivel de la palabra: Genera compensaciones de tiempo de inicio y finalización precisas para cada palabra reconocida.
  • Transcripción inteligente: Elimina las disfluencias, las muletillas y las repeticiones, y aplica un formato estructurado.
  • Formato y normalización: Aplica el uso de mayúsculas, la puntuación y la normalización inversa del texto, como convertir "veintiséis millones de dólares" a "USD 26 M".

Para el razonamiento de audio general o la búsqueda de respuestas sobre contenido de audio, usa Comprensión de audio. Para la síntesis de audio de texto a voz, usa Text-to-speech.

Sugerencias y detección de idioma

De forma predeterminada, el modelo detecta automáticamente el idioma hablado. Cambia de idioma de forma dinámica cuando los oradores cambian de código.

Para usar la detección automática, omite language_codes o proporciona una lista vacía:

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            language_codes=[],
        )
    ),
)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.5-transcribe",
  contents: [audioFile],
  config: {
    audioTranscriptionConfig: {
      languageCodes: [],
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "fileData": {
              "fileUri": "YOUR_FILE_URI",
              "mimeType": "audio/mp3"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "audioTranscriptionConfig": {
        "languageCodes": []
      }
    }
  }'

Si conoces el idioma de antemano, especifica los códigos de idioma BCP-47 en language_codes para mejorar la precisión de la transcripción (consulta Idiomas admitidos):

Python

config = types.GenerateContentConfig(
    audio_transcription_config=types.AudioTranscriptionConfig(
        language_codes=["es-ES"],
    )
)

JavaScript

const config = {
  audioTranscriptionConfig: {
    languageCodes: ["es-ES"],
  },
};

REST

{
  "generationConfig": {
    "audioTranscriptionConfig": {
      "languageCodes": ["es-ES"]
    }
  }
}

Vocabulario personalizado

Puedes dirigir el modelo de voz hacia palabras poco comunes, jerga técnica, nombres de marcas o nombres propios. Proporciona hasta 1,000 términos en el array custom_vocabulary (por lo general, se obtienen los mejores resultados con hasta 100 términos):

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            custom_vocabulary=["Gemini", "Kubernetes", "BigQuery"],
        )
    ),
)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.5-transcribe",
  contents: [audioFile],
  config: {
    audioTranscriptionConfig: {
      customVocabulary: ["Gemini", "Kubernetes", "BigQuery"],
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "fileData": {
              "fileUri": "YOUR_FILE_URI",
              "mimeType": "audio/mp3"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "audioTranscriptionConfig": {
        "customVocabulary": ["Gemini", "Kubernetes", "BigQuery"]
      }
    }
  }'

Identificación de interlocutores

La identificación de interlocutores identifica las diferentes voces en la grabación y etiqueta cada segmento con un identificador de interlocutor, como spk_1 o spk_2. Se admiten hasta 8 oradores (la atribución para 3 o más oradores es experimental).

Para habilitar la identificación del interlocutor, establece diarization en True:

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            diarization=True,
        )
    ),
)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.5-transcribe",
  contents: [audioFile],
  config: {
    audioTranscriptionConfig: {
      diarization: true,
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "fileData": {
              "fileUri": "YOUR_FILE_URI",
              "mimeType": "audio/mp3"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "audioTranscriptionConfig": {
        "diarization": true
      }
    }
  }'

Marcas de tiempo a nivel de la palabra

Las marcas de tiempo a nivel de la palabra proporcionan compensaciones exactas de inicio y finalización para cada palabra reconocida en la transmisión de audio.

Para habilitar las marcas de tiempo, establece word_timestamp en True:

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            word_timestamp=True,
        )
    ),
)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.5-transcribe",
  contents: [audioFile],
  config: {
    audioTranscriptionConfig: {
      wordTimestamp: true,
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "fileData": {
              "fileUri": "YOUR_FILE_URI",
              "mimeType": "audio/mp3"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "audioTranscriptionConfig": {
        "wordTimestamp": true
      }
    }
  }'

Puedes combinar diarization y word_timestamp en una sola solicitud para recibir etiquetas de interlocutor y marcas de tiempo de palabras:

Python

config = types.GenerateContentConfig(
    audio_transcription_config=types.AudioTranscriptionConfig(
        diarization=True,
        word_timestamp=True,
        custom_vocabulary=["Gemini"],
    )
)

JavaScript

const config = {
  audioTranscriptionConfig: {
    diarization: true,
    wordTimestamp: true,
    customVocabulary: ["Gemini"],
  },
};

REST

{
  "generationConfig": {
    "audioTranscriptionConfig": {
      "diarization": true,
      "wordTimestamp": true,
      "customVocabulary": ["Gemini"]
    }
  }
}

Modos de transcripción

Gemini 3.5 Transcribe admite dos modos de transcripción a través del parámetro mode:

  • VERBATIM (predeterminado): Devuelve una transcripción palabra por palabra exacta de todo lo que se dice, y conserva las palabras de relleno sin procesar (“eh”, “um”, “como”, “sabes”), las repeticiones, las pausas y los comienzos en falso. Se requiere cuando se usan marcas de tiempo o la diarización del orador.
  • SMART (Transcripción inteligente): Optimiza la transcripción para su lectura aplicando un posprocesamiento inteligente:
    • Eliminación de disfluencias: Elimina las palabras de relleno, los tartamudeos y los inicios en falso de las conversaciones.
    • Autocorrecciones intercaladas: Resuelve las correcciones habladas directamente (por ejemplo, "Reunámonos el martes, no, el miércoles a las dos" se convierte en "Reunámonos el miércoles a las 2 p.m.").
    • Formato estructurado automático: Estructura automáticamente los pensamientos hablados en párrafos, listas numeradas, viñetas, fechas, monedas y números con formato.
    • Limpieza gramatical: Aplica puntuación, mayúsculas al inicio de las oraciones y flujo naturales.
Audio hablado Resultado de VERBATIM Resultado de SMART (Transcripción inteligente)
"Eh, entonces, para la reunión, creo que deberíamos, eh, invitar a Alice y, no, espera, a Bob y Carol". "Eh, para la reunión, creo que deberíamos invitar a Alicia y, no, a Bob y a Carol". "Para la reunión, creo que deberíamos invitar a Bob y a Carol".
"Revisar el primer elemento, presupuestar el segundo elemento, finalizar el cronograma, enviar el resumen" "revisar el primer elemento, presupuestar el segundo elemento, finalizar el cronograma, enviar el resumen" "1. Revisa el presupuesto
2. Finaliza el cronograma
3. Enviar resumen"

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            mode="SMART",
        )
    ),
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.5-transcribe",
  contents: [audioFile],
  config: {
    audioTranscriptionConfig: {
      mode: "SMART",
    },
  },
});
console.log(response.text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "fileData": {
              "fileUri": "YOUR_FILE_URI",
              "mimeType": "audio/mp3"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "audioTranscriptionConfig": {
        "mode": "SMART"
      }
    }
  }'

Cómo analizar el resultado de la transcripción

El texto completo de la transcripción se muestra en response.text.

Cuando se habilitan word_timestamp o diarization, la API también devuelve anotaciones detalladas a nivel de la palabra y etiquetas de interlocutor adjuntas a las partes candidatas.

A continuación, se explica cómo extraer las marcas de tiempo de las palabras y los turnos de los oradores, y cómo iterar sobre ellos:

Python

def extract_word_transcriptions(response):
    words = []
    for candidate in getattr(response, "candidates", []) or []:
        content = getattr(candidate, "content", None)
        for part in getattr(content, "parts", []) or []:
            transcription = getattr(part, "audio_transcription", None)
            if transcription:
                speaker = getattr(transcription, "speaker_label", "")
                for word_info in getattr(transcription, "words", []) or []:
                    word = getattr(word_info, "word", "")
                    start = getattr(word_info, "start_offset", "")
                    end = getattr(word_info, "end_offset", "")
                    words.append({
                        "word": word,
                        "speaker": speaker,
                        "start_offset": start,
                        "end_offset": end,
                    })
    return words

words = extract_word_transcriptions(response)

for w in words:
    speaker = f"[{w['speaker']}] " if w["speaker"] else ""
    timing = f"({w['start_offset']} -> {w['end_offset']}) " if w["start_offset"] and w["end_offset"] else ""
    print(f"{speaker}{timing}{w['word']}")

JavaScript

function extractWordTranscriptions(response) {
  const words = [];
  for (const candidate of response.candidates ?? []) {
    for (const part of candidate.content?.parts ?? []) {
      const transcription = part.audioTranscription;
      if (transcription) {
        const speaker = transcription.speakerLabel ?? "";
        for (const wordInfo of transcription.words ?? []) {
          words.push({
            word: wordInfo.word ?? "",
            speaker: speaker,
            startOffset: wordInfo.startOffset ?? "",
            endOffset: wordInfo.endOffset ?? "",
          });
        }
      }
    }
  }
  return words;
}

const words = extractWordTranscriptions(response);

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

REST

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "audioTranscription": {
              "speakerLabel": "spk_1",
              "words": [
                {
                  "word": "Hello",
                  "startOffset": "0.100s",
                  "endOffset": "0.450s"
                },
                {
                  "word": "world",
                  "startOffset": "0.500s",
                  "endOffset": "0.850s"
                }
              ]
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ]
}

Idiomas admitidos

Los siguientes idiomas y códigos de idioma BCP-47 son compatibles con Gemini 3.5 Transcribe:

Idioma Código BCP-47 Idioma Código BCP-47
Afrikaans af-ZA Japonés ja-JP
Amárico am-ET Javanés jv-ID
Árabe (Egipto) ar-EG Kabuverdianu kea-CV
Armenio hy-AM Canarés kn-IN
Asamés as-IN Kazajo kk-KZ
Azerí az-AZ Coreano ko-KR
Bielorruso be-BY Kirguís ky-KG
Bengalí (Bangladés) bn-BD Letón lv-LV
Bengalí (India) bn-IN Lingala ln-CD
Bosnio bs-BA Lituano lt-LT
Búlgaro bg-BG Macedonio mk-MK
Búlgaro (arrumano) rup-BG Malayo ms-MY
Birmano my-MM Malayalam ml-IN
Cantonés (tradicional) yue-Hant-HK Maltés mt-MT
Catalán ca-ES Chino mandarín (simplificado) cmn-Hans-CN
Cebuano ceb Maratí mr-IN
Camboyano km-KH Mongol mn-MN
Croata hr-HR Nepalí ne-NP
Checo cs-CZ Noruego nb-NO
Danés da-DK Oriya or-IN
Holandés nl-NL Polaco pl-PL
Inglés (Gran Bretaña) en-GB Portugués (Brasil) pt-BR
Inglés (India) en-IN Portugués (Portugal) pt-PT
Inglés (Estados Unidos) en-US Punyabí pa-IN
Estonio et-EE Panyabí (alfabeto gurmukhi) pa-Guru-IN
Persa fa-IR Rumano ro-RO
Filipino fil-PH Ruso ru-RU
Finlandés fi-FI Serbio sr-RS
Francés fr-FR Sindhi (alfabeto árabe) sd-Arab-IN
Gallego gl-ES Eslovaco sk-SK
Georgiano ka-GE Esloveno sl-SI
Alemán de-DE Español (Latinoamérica) es-419
Griego el-GR Español (Estados Unidos) es-US
Gujarati gu-IN Suajili (Kenia) sw-KE
Hausa ha-NG Sueco sv-SE
Hebreo he-IL Tayiko tg-TJ
Hindi hi-IN Telugu te-IN
Húngaro hu-HU Tailandés th-TH
Islandés is-IS Turco tr-TR
tu idioma o tu país en-IN Ucraniano uk-UA
Indonesio id-ID Uzbeko uz-UZ
Italiano it-IT Vietnamita vi-VN

Formatos de audio compatibles

Gemini 3.5 Transcribe admite los siguientes tipos de MIME de formato de audio:

  • WAV - audio/wav
  • MP3 - audio/mp3
  • AIFF - audio/aiff
  • AAC - audio/aac
  • OGG - audio/ogg
  • FLAC - audio/flac
  • MPEG - audio/mpeg
  • M4A - audio/m4a
  • L16: audio/l16
  • Opus - audio/opus
  • ALAW - audio/alaw
  • MULAW - audio/mulaw
  • WebM - audio/webm

Para obtener la lista completa de los tipos de MIME y los esquemas de parámetros admitidos, consulta la referencia de la API de Interactions.

Referencia del parámetro

Configura la transcripción estableciendo campos dentro del objeto audio_transcription_config en GenerateContentConfig:

Campo Tipo Descripción
language_codes Arreglo de strings Códigos de idioma BCP-47 (p.ej., ["en-US"]). Si se omite o está vacío ([]), el modelo detecta automáticamente el idioma y controla el cambio de código.
custom_vocabulary Arreglo de strings Hasta 1,000 términos, acrónimos o nombres propios personalizados para sesgar el reconocimiento de voz
word_timestamp Booleano Se establece en True para incluir las compensaciones de inicio y finalización de palabras. Si se omite o se establece en False, no se devuelven marcas de tiempo de palabras.
diarization Booleano Se establece en True para identificar y etiquetar a los distintos interlocutores.
mode String Modo de transcripción. Valores admitidos: "VERBATIM" (predeterminado) y "SMART". No es compatible con las marcas de tiempo ni la identificación del orador.

Prácticas recomendadas

  • Proporciona audio nítido: Asegúrate de que las grabaciones de audio tengan una separación de voz clara y evita el recorte grave.
  • Proporciona sugerencias de idioma cuando lo sepas: Si conoces el idioma del audio de antemano, especifica language_codes para maximizar la precisión.
  • Vocabulario personalizado objetivo: Incluye solo términos distintos del dominio, nombres de marcas o nombres propios en custom_vocabulary en lugar de palabras comunes de uso diario.
  • Usa la API de Files para grabaciones grandes: Para archivos de más de unos segundos, sube el archivo con client.files.upload y pasa el archivo devuelto al contenido del modelo.

Limitaciones

  • Duración del audio: Las solicitudes unarias estándar admiten archivos de audio de hasta 1 hora. El procesamiento de audio se limita a 30 minutos cuando se habilitan funciones como la identificación de interlocutores o las marcas de tiempo a nivel de palabra.
  • Marcas de tiempo a nivel de la palabra: Habilitar las marcas de tiempo a nivel de la palabra puede reducir la precisión general de la transcripción.
  • Identificación de interlocutores: La identificación de interlocutores admite hasta 8 interlocutores. La atribución de oradores para 3 o más oradores es experimental.
  • Vocabulario personalizado: Puedes proporcionar hasta 1,000 términos en custom_vocabulary, pero, por lo general, se obtienen mejores resultados con hasta 100 términos.
  • Compatibilidad de modos: La transcripción inteligente (mode: "SMART") no se puede combinar con word_timestamp ni diarization.

¿Qué sigue?