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

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

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

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

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

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

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

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

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, configura diarization_mode dentro de 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"
        }
      }
    }
  }'

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, configura timestamp_granularities dentro de 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"]
        }
      }
    }
  }'

Puedes combinar diarization_mode y timestamp_granularities en mode para recibir etiquetas de interlocutor y marcas de tiempo de palabras:

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 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. Las marcas de tiempo y la identificación de interlocutores se configuran en este modo ({"type": "verbatim", ...}).
  • 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

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

Cómo analizar el resultado de la transcripción

El texto completo de la transcripción se muestra en interaction.output_text.

Cuando se habilitan timestamp_granularities o diarization_mode, la API también devuelve anotaciones detalladas a nivel de la palabra adjuntas al contenido de la interacción.

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_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 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

Referencia del parámetro

Configura la transcripción estableciendo campos dentro del objeto transcription_config en generation_config:

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
mode Objeto o cadena Es la configuración del modo de transcripción. Acepta "smart" o un objeto de modo literal ({"type": "verbatim", ...}). La configuración predeterminada es la transcripción literal.
mode.type String (Solo en el modo literal) Es el identificador del modo. Siempre se establece en "verbatim".
mode.timestamp_granularities Arreglo de strings (Solo en modo literal) Es el nivel de detalle de las marcas de tiempo que se devolverán. Pasa ["word"] para habilitar las compensaciones de inicio y fin de palabras.
mode.diarization_mode String (Solo en modo literal) Modo de diarización. Pasa "speaker" para identificar y etiquetar a los distintos interlocutores.

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 URI del archivo que se devolvió al 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 ("smart") no se puede combinar con timestamp_granularities ni diarization_mode.

¿Qué sigue?