> ## AI Agent Context > - Full documentation index: https://aistudio.google.com/llms.txt > - Gemini Docs MCP server (consistent live info): https://gemini-api-docs-mcp.dev > - Coding agent skills & setup guide: https://aistudio.google.com/docs/coding-agents.md # Audio transcription The Gemini API converts speech in audio files into text using the Gemini 3.5 Transcribe model (`gemini-3.5-transcribe`). Based on Gemini's audio understanding capabilities, it delivers accurate transcription with automatic language identification, speaker diarization, word-level timestamps, and custom vocabulary hints. It also provides a [smart transcription](/docs/transcribe#transcription-modes) mode featuring disfluency removal and smart formatting. To transcribe an audio file, upload the audio and pass it to `gemini-3.5-transcribe`: {% tabs %} {% tab filename="transcribe_quickstart.py" label="Python" %} ```python from google import genai client = genai.Client(http_options={"api_version": "v1beta"}) 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) ``` {% /tab %} {% tab filename="transcribe_quickstart.js" label="JavaScript" %} ```javascript import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }); 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); ``` {% /tab %} {% tab filename="transcribe_quickstart.sh" label="REST" %} ```bash # 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" } } ] } ] }' ``` {% /tab %} {% /tabs %} {% callout type="note" %} For real-time, low-latency streaming speech recognition from a microphone or live audio stream, see [Live transcription](/docs/live-api/live-transcribe) using the Live API and `gemini-3.5-transcribe-live`. {% /callout %} ## Overview {% id="overview" %} Gemini 3.5 Transcribe is optimized for speech-to-text tasks. It handles diverse accents, background noise, and multi-language conversations. Key capabilities include: * **Automatic speech recognition (ASR):** Automatically detects languages across [85+ locales](/docs/transcribe#supported-languages). Handles intra-sentence and inter-sentential code-switching without manual configuration. * **Custom vocabulary:** Biases recognition toward domain-specific terms, acronyms, and proper names by passing up to 1,000 phrases. * **Speaker diarization:** Distinguishes between multiple speakers and attributes spoken segments to distinct labels. * **Word-level timestamps:** Generates precise start and end time offsets for each recognized word. * **Smart transcription:** Cleans up disfluencies, filler words, repetitions, and applies structured formatting. * **Voice editing:** Enabled by default in Smart transcription mode. Edits, rewrites, or formats dictated speech or existing reference text (`source_text`) using spoken instructions. * **Formatting and normalization:** Applies capitalization, punctuation, and inverse text normalization, such as converting "twenty six million dollars" to "$26M". For general audio reasoning or question answering over audio content, use [Audio understanding](/docs/audio). For text-to-speech audio synthesis, use [Text-to-speech](/docs/speech-generation). ## Language detection and hints {% id="language-detection" %} By default, the model detects the spoken language automatically. It switches between languages dynamically when speakers code-switch. To use automatic detection, omit `language_codes` or provide an empty list: {% tabs %} {% tab filename="transcribe_language_auto.py" label="Python" %} ```python from google import genai from google.genai import types client = genai.Client(http_options={"api_version": "v1beta"}) response = client.models.generate_content( model="gemini-3.5-transcribe", contents=[audio_file], config=types.GenerateContentConfig( audio_transcription_config=types.AudioTranscriptionConfig( language_codes=[], ) ), ) ``` {% /tab %} {% tab filename="transcribe_language_auto.js" label="JavaScript" %} ```javascript const response = await ai.models.generateContent({ model: "gemini-3.5-transcribe", contents: [audioFile], config: { audioTranscriptionConfig: { languageCodes: [], }, }, }); ``` {% /tab %} {% tab filename="transcribe_language_auto.sh" label="REST" %} ```bash 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": [] } } }' ``` {% /tab %} {% /tabs %} If you know the language in advance, specify BCP-47 language codes in `language_codes` to improve transcription accuracy (see [Supported languages](/docs/transcribe#supported-languages)): {% tabs %} {% tab filename="transcribe_language_hint.py" label="Python" %} ```python config = types.GenerateContentConfig( audio_transcription_config=types.AudioTranscriptionConfig( language_codes=["es-ES"], ) ) ``` {% /tab %} {% tab filename="transcribe_language_hint.js" label="JavaScript" %} ```javascript const config = { audioTranscriptionConfig: { languageCodes: ["es-ES"], }, }; ``` {% /tab %} {% tab filename="transcribe_language_hint.json" label="REST" %} ```json { "generationConfig": { "audioTranscriptionConfig": { "languageCodes": ["es-ES"] } } } ``` {% /tab %} {% /tabs %} ## Custom vocabulary {% id="custom-vocabulary" %} You can steer the speech model toward uncommon words, technical jargon, brand names, or proper nouns. Supply up to 1,000 terms in the `custom_vocabulary` array (best results are typically achieved with up to 100 terms): {% callout type="note" %} You cannot combine `custom_vocabulary` with speaker diarization or word-level timestamps. The API rejects requests that include `custom_vocabulary` with either feature. {% /callout %} {% tabs %} {% tab filename="transcribe_custom_vocab.py" label="Python" %} ```python from google import genai from google.genai import types client = genai.Client(http_options={"api_version": "v1beta"}) 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"], ) ), ) ``` {% /tab %} {% tab filename="transcribe_custom_vocab.js" label="JavaScript" %} ```javascript const response = await ai.models.generateContent({ model: "gemini-3.5-transcribe", contents: [audioFile], config: { audioTranscriptionConfig: { customVocabulary: ["Gemini", "Kubernetes", "BigQuery"], }, }, }); ``` {% /tab %} {% tab filename="transcribe_custom_vocab.sh" label="REST" %} ```bash 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"] } } }' ``` {% /tab %} {% /tabs %} ## Speaker diarization {% id="speaker-diarization" %} Speaker diarization identifies different voices in the recording and tags each segment with a speaker identifier like `spk_1` or `spk_2`. Up to 8 speakers are supported (attribution for 3 or more speakers is experimental). Enable diarization by setting `diarization` to `True`: {% tabs %} {% tab filename="transcribe_diarization.py" label="Python" %} ```python from google import genai from google.genai import types client = genai.Client(http_options={"api_version": "v1beta"}) response = client.models.generate_content( model="gemini-3.5-transcribe", contents=[audio_file], config=types.GenerateContentConfig( audio_transcription_config=types.AudioTranscriptionConfig( diarization=True, ) ), ) ``` {% /tab %} {% tab filename="transcribe_diarization.js" label="JavaScript" %} ```javascript const response = await ai.models.generateContent({ model: "gemini-3.5-transcribe", contents: [audioFile], config: { audioTranscriptionConfig: { diarization: true, }, }, }); ``` {% /tab %} {% tab filename="transcribe_diarization.sh" label="REST" %} ```bash 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 } } }' ``` {% /tab %} {% /tabs %} ## Word-level timestamps {% id="word-timestamps" %} Word-level timestamps provide exact start and end offsets for every recognized word in the audio stream. {% callout type="note" %} Enabling word-level timestamps may degrade overall transcription accuracy. {% /callout %} Enable timestamps by setting `word_timestamp` to `True`: {% tabs %} {% tab filename="transcribe_timestamps.py" label="Python" %} ```python from google import genai from google.genai import types client = genai.Client(http_options={"api_version": "v1beta"}) response = client.models.generate_content( model="gemini-3.5-transcribe", contents=[audio_file], config=types.GenerateContentConfig( audio_transcription_config=types.AudioTranscriptionConfig( word_timestamp=True, ) ), ) ``` {% /tab %} {% tab filename="transcribe_timestamps.js" label="JavaScript" %} ```javascript const response = await ai.models.generateContent({ model: "gemini-3.5-transcribe", contents: [audioFile], config: { audioTranscriptionConfig: { wordTimestamp: true, }, }, }); ``` {% /tab %} {% tab filename="transcribe_timestamps.sh" label="REST" %} ```bash 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 } } }' ``` {% /tab %} {% /tabs %} You can combine `diarization` and `word_timestamp` in a single request to receive both speaker labels and word timestamps: {% tabs %} {% tab filename="transcribe_diarization_timestamps.py" label="Python" %} ```python config = types.GenerateContentConfig( audio_transcription_config=types.AudioTranscriptionConfig( diarization=True, word_timestamp=True, ) ) ``` {% /tab %} {% tab filename="transcribe_diarization_timestamps.js" label="JavaScript" %} ```javascript const config = { audioTranscriptionConfig: { diarization: true, wordTimestamp: true, }, }; ``` {% /tab %} {% tab filename="transcribe_diarization_timestamps.json" label="REST" %} ```json { "generationConfig": { "audioTranscriptionConfig": { "diarization": true, "wordTimestamp": true } } } ``` {% /tab %} {% /tabs %} ## Transcription modes {% id="transcription-modes" %} Gemini 3.5 Transcribe supports two transcription modes via the `mode` parameter: * **`VERBATIM` (default)**: Returns an exact word-for-word transcript of everything spoken, preserving raw filler words ("um", "uh", "like", "you know"), repetitions, pauses, and false starts. Required when using timestamps or speaker diarization. * **`SMART` (Smart transcription)**: Optimizes the transcript for reading by applying intelligent post-processing: * **Disfluency removal**: Strips conversational filler words, stuttering, and false starts. * **Inline self-corrections**: Resolves spoken corrections directly (for example, *"Let's meet on Tuesday, actually no, Wednesday at two"* becomes *"Let's meet on Wednesday at 2:00 PM"*). * **Automatic structured formatting**: Automatically structures spoken thoughts into paragraphs, numbered lists, bullet points, formatted dates, currencies, and numbers. * **Grammatical cleanup**: Applies natural punctuation, sentence casing, and flow. * **Voice editing (enabled by default)**: Applies spoken editing, rewriting, and formatting commands to dictated speech or existing reference text (`source_text`). {% table %} * Spoken audio * `VERBATIM` output * `SMART` (Smart transcription) output --- * "Um, so for the meeting, I think we should, uh, invite Alice and, wait no, Bob and Carol." * "Um so for the meeting I think we should uh invite Alice and wait no Bob and Carol." * "For the meeting, I think we should invite Bob and Carol." --- * "First item review budget second item finalize timeline third item send recap" * "first item review budget second item finalize timeline third item send recap" * 1. Review budget 2. Finalize timeline 3. Send recap {% /table %} {% tabs %} {% tab filename="transcribe_smart_mode.py" label="Python" %} ```python from google import genai from google.genai import types client = genai.Client(http_options={"api_version": "v1beta"}) 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.candidates[0].content.parts[0].audio_transcription.text) ``` {% /tab %} {% tab filename="transcribe_smart_mode.js" label="JavaScript" %} ```javascript const response = await ai.models.generateContent({ model: "gemini-3.5-transcribe", contents: [audioFile], config: { audioTranscriptionConfig: { mode: "SMART", }, }, }); console.log(response.candidates[0].content.parts[0].audioTranscription.text); ``` {% /tab %} {% tab filename="transcribe_smart_mode.sh" label="REST" %} ```bash 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" } } }' ``` {% /tab %} {% /tabs %} {% callout type="note" %} Smart transcription (`mode: "SMART"`) is incompatible with `word_timestamp` and `diarization`. If you need word timestamps or speaker diarization, use `VERBATIM` mode (default). {% /callout %} ### Voice editing {% id="voice-editing" %} Voice editing is enabled by default whenever Smart transcription mode (`mode: "SMART"`) is active. Speakers can dictate text and give spoken editing instructions within the same recording, or pass existing text in the optional `source_text` field to edit, rewrite, or format that text using voice commands. Instead of only transcribing spoken words verbatim, the model applies the spoken instructions and returns the complete updated text in `response.candidates[0].content.parts[0].audio_transcription.text`. #### Enable voice editing {% id="enable-voice-editing" %} Setting `mode="SMART"` enables voice editing by default for new dictation. To edit or rewrite pre-existing text, set `mode` to `"SMART"` and provide the text to modify in `source_text` (up to 64 KiB) within `audio_transcription_config`: {% tabs %} {% tab filename="transcribe_voice_edit.py" label="Python" %} ```python from google import genai from google.genai import types client = genai.Client(http_options={"api_version": "v1beta"}) audio_file = client.files.upload(file="path/to/edit_command.mp3") response = client.models.generate_content( model="gemini-3.5-transcribe", contents=[audio_file], config=types.GenerateContentConfig( audio_transcription_config=types.AudioTranscriptionConfig( mode="SMART", source_text="The meeting is at 2:00 PM tomorrow in building 42.", ) ), ) print(response.candidates[0].content.parts[0].audio_transcription.text) ``` {% /tab %} {% tab filename="transcribe_voice_edit.js" label="JavaScript" %} ```javascript import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }); const audioFile = await ai.files.upload({ file: "path/to/edit_command.mp3", config: { mimeType: "audio/mp3" }, }); const response = await ai.models.generateContent({ model: "gemini-3.5-transcribe", contents: [audioFile], config: { audioTranscriptionConfig: { mode: "SMART", sourceText: "The meeting is at 2:00 PM tomorrow in building 42.", }, }, }); console.log(response.candidates[0].content.parts[0].audioTranscription.text); ``` {% /tab %} {% tab filename="transcribe_voice_edit.sh" label="REST" %} ```bash 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", "sourceText": "The meeting is at 2:00 PM tomorrow in building 42." } } }' ``` {% /tab %} {% /tabs %} #### Voice edit prompt examples {% id="voice-edit-prompt-examples" %} Voice editing supports targeted word replacements, tone adjustments, structural formatting, appending new dictated text, and deletions: {% table %} * Edit type * `source_text` * Spoken audio prompt * Output (`audio_transcription.text`) --- * **Targeted replacement** * "The meeting is at 2:00 PM tomorrow in building 42." * "Change the time to 3:30 PM and mention video conferencing is available." * "The meeting is at 3:30 PM tomorrow in building 42, with video conferencing available." --- * **Tone and style transfer** * "The new park downtown is finally open, and I've heard it has some really cool features." * "Make it sound more formal." * "The new downtown park has officially opened and reportedly features several impressive amenities." --- * **Structural formatting** * "We need to review the Q3 budget, finalize the launch timeline, and send the recap email." * "Format the action items as a numbered list." * We need to: 1. Review the Q3 budget 2. Finalize the launch timeline 3. Send the recap email --- * **Appending dictation** * "Hi Alex, thanks for sending over the design doc." * "Add a sentence asking if we can review the latency numbers tomorrow morning." * "Hi Alex, thanks for sending over the design doc. Can we review the latency numbers tomorrow morning?" --- * **Deletion** * "Let's schedule the sync for Monday afternoon. We also need to invite the security team." * "Delete the second sentence." * "Let's schedule the sync for Monday afternoon." {% /table %} #### Multi-turn voice editing {% id="multi-turn-voice-editing" %} Because each unary `generate_content` request is independent, `source_text` is not persisted automatically between separate unary API calls. To apply sequential voice edits across multiple turns, pass the transcript returned from each turn (`candidates[0].content.parts[0].audio_transcription.text`) as the `source_text` in the next request: {% tabs %} {% tab filename="transcribe_voice_edit_multiturn.py" label="Python" %} ```python from google import genai from google.genai import types client = genai.Client(http_options={"api_version": "v1beta"}) current_text = "The new park downtown is finally open, and I've heard it has some really cool features." # Turn 1: Spoken instruction "Make it more professional." turn1_audio = client.files.upload(file="path/to/turn1_edit.mp3") turn1_response = client.models.generate_content( model="gemini-3.5-transcribe", contents=[turn1_audio], config=types.GenerateContentConfig( audio_transcription_config=types.AudioTranscriptionConfig( mode="SMART", source_text=current_text, ) ), ) current_text = turn1_response.candidates[0].content.parts[0].audio_transcription.text print("After Turn 1:", current_text) # Turn 2: Pass Turn 1's transcript as source_text for the next spoken edit # Spoken instruction "Add a sentence inviting the team to visit on Friday." turn2_audio = client.files.upload(file="path/to/turn2_edit.mp3") turn2_response = client.models.generate_content( model="gemini-3.5-transcribe", contents=[turn2_audio], config=types.GenerateContentConfig( audio_transcription_config=types.AudioTranscriptionConfig( mode="SMART", source_text=current_text, ) ), ) current_text = turn2_response.candidates[0].content.parts[0].audio_transcription.text print("After Turn 2:", current_text) ``` {% /tab %} {% tab filename="transcribe_voice_edit_multiturn.js" label="JavaScript" %} ```javascript import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }); let currentText = "The new park downtown is finally open, and I've heard it has some really cool features."; // Turn 1: Spoken instruction "Make it more professional." const turn1AudioFile = await ai.files.upload({ file: "path/to/turn1_edit.mp3", config: { mimeType: "audio/mp3" }, }); const turn1Response = await ai.models.generateContent({ model: "gemini-3.5-transcribe", contents: [turn1AudioFile], config: { audioTranscriptionConfig: { mode: "SMART", sourceText: currentText, }, }, }); currentText = turn1Response.candidates[0].content.parts[0].audioTranscription.text; console.log("After Turn 1:", currentText); // Turn 2: Pass Turn 1's transcript as sourceText for the next spoken edit const turn2AudioFile = await ai.files.upload({ file: "path/to/turn2_edit.mp3", config: { mimeType: "audio/mp3" }, }); const turn2Response = await ai.models.generateContent({ model: "gemini-3.5-transcribe", contents: [turn2AudioFile], config: { audioTranscriptionConfig: { mode: "SMART", sourceText: currentText, }, }, }); currentText = turn2Response.candidates[0].content.parts[0].audioTranscription.text; console.log("After Turn 2:", currentText); ``` {% /tab %} {% /tabs %} {% callout type="note" %} In bidirectional streaming sessions using the [Live API](/docs/live-api/live-transcribe#voice-editing), multi-turn voice editing is enabled by default in Smart mode (`mode: "SMART"`). You can start dictating from an empty text box or provide initial `source_text` once during session setup, and the server automatically updates the active source text to the latest finalized transcript after each turn. {% /callout %} ## Parsing transcription output {% id="parsing-output" %} The complete transcript text is returned in `response.candidates[0].content.parts[0].audio_transcription.text` (or `response.text` when `word_timestamp` or `diarization` is enabled). When `word_timestamp` or `diarization` is enabled, the API also returns detailed word-level annotations and speaker labels attached to the candidate parts. Here is how to extract and iterate over word timestamps and speaker turns: {% tabs %} {% tab filename="transcribe_parse_output.py" label="Python" %} ```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']}") ``` {% /tab %} {% tab filename="transcribe_parse_output.js" label="JavaScript" %} ```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}`); } ``` {% /tab %} {% tab filename="transcribe_parse_output.json" label="REST" %} ```json { "candidates": [ { "content": { "parts": [ { "audioTranscription": { "speakerLabel": "spk_1", "words": [ { "word": "Hello", "startOffset": "0.100s", "endOffset": "0.400s" }, { "word": "world", "startOffset": "0.500s", "endOffset": "0.800s" } ] } } ], "role": "model" }, "finishReason": "STOP" } ] } ``` {% /tab %} {% /tabs %} ## Supported languages {% id="supported-languages" %} The following languages and BCP-47 language codes are supported for Gemini 3.5 Transcribe: | Language | BCP-47 Code | Language | BCP-47 Code | | :--- | :--- | :--- | :--- | | Afrikaans | `af-ZA` | Japanese | `ja-JP` | | Amharic | `am-ET` | Javanese | `jv-ID` | | Arabic (Egypt) | `ar-EG` | Kabuverdianu | `kea-CV` | | Armenian | `hy-AM` | Kannada | `kn-IN` | | Assamese | `as-IN` | Kazakh | `kk-KZ` | | Azerbaijani | `az-AZ` | Korean | `ko-KR` | | Belarusian | `be-BY` | Kyrgyz | `ky-KG` | | Bengali (Bangladesh) | `bn-BD` | Latvian | `lv-LV` | | Bengali (India) | `bn-IN` | Lingala | `ln-CD` | | Bosnian | `bs-BA` | Lithuanian | `lt-LT` | | Bulgarian | `bg-BG` | Macedonian | `mk-MK` | | Bulgarian (Aromanian) | `rup-BG` | Malay | `ms-MY` | | Burmese | `my-MM` | Malayalam | `ml-IN` | | Cantonese (Traditional) | `yue-Hant-HK` | Maltese | `mt-MT` | | Catalan | `ca-ES` | Mandarin Chinese (Simplified) | `cmn-Hans-CN` | | Cebuano | `ceb` | Marathi | `mr-IN` | | Central Khmer | `km-KH` | Mongolian | `mn-MN` | | Croatian | `hr-HR` | Nepali | `ne-NP` | | Czech | `cs-CZ` | Norwegian | `nb-NO` | | Danish | `da-DK` | Oriya | `or-IN` | | Dutch | `nl-NL` | Polish | `pl-PL` | | English (Great Britain) | `en-GB` | Portuguese (Brazil) | `pt-BR` | | English (India) | `en-IN` | Portuguese (Portugal) | `pt-PT` | | English (United States) | `en-US` | Punjabi | `pa-IN` | | Estonian | `et-EE` | Punjabi (Gurmukhi script) | `pa-Guru-IN` | | Farsi | `fa-IR` | Romanian | `ro-RO` | | Filipino | `fil-PH` | Russian | `ru-RU` | | Finnish | `fi-FI` | Serbian | `sr-RS` | | French | `fr-FR` | Sindhi (Arabic script) | `sd-Arab-IN` | | Galician | `gl-ES` | Slovak | `sk-SK` | | Georgian | `ka-GE` | Slovenian | `sl-SI` | | German | `de-DE` | Spanish (Latin America) | `es-419` | | Greek | `el-GR` | Spanish (United States) | `es-US` | | Gujarati | `gu-IN` | Swahili (Kenya) | `sw-KE` | | Hausa | `ha-NG` | Swedish | `sv-SE` | | Hebrew | `he-IL` | Tajik | `tg-TJ` | | Hindi | `hi-IN` | Telugu | `te-IN` | | Hungarian | `hu-HU` | Thai | `th-TH` | | Icelandic | `is-IS` | Turkish | `tr-TR` | | Indian English | `en-IN` | Ukrainian | `uk-UA` | | Indonesian | `id-ID` | Uzbek | `uz-UZ` | | Italian | `it-IT` | Vietnamese | `vi-VN` | ## Supported audio formats {% id="supported-formats" %} Gemini 3.5 Transcribe supports the following audio format MIME types: * 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` For the complete list of supported MIME types and parameter schemas, see the [Interactions API reference](/api-reference/interactions-api#Resource:Content). ## Parameter reference {% id="parameter-reference" %} Configure transcription by setting fields within the `audio_transcription_config` object in `GenerateContentConfig`: | Field | Type | Description | | :--- | :--- | :--- | | `language_codes` | Array of strings | BCP-47 language codes (e.g., `["en-US"]`). If omitted or empty (`[]`), the model automatically detects the language and handles code-switching. | | `custom_vocabulary` | Array of strings | Up to 1,000 custom terms, acronyms, or proper names to bias speech recognition. Incompatible with speaker diarization and word-level timestamps. | | `word_timestamp` | Boolean | Set to `True` to include word start and end offsets. If omitted or `False`, no word timestamps are returned. Incompatible with custom vocabulary. | | `diarization` | Boolean | Set to `True` to identify and label distinct speakers. Incompatible with custom vocabulary. | | `mode` | String | Transcription mode. Supported values: `"VERBATIM"` (default) and `"SMART"` (enables Smart transcription and voice editing by default). Incompatible with timestamps and diarization. | | `source_text` | String | *(Smart mode only)* Optional pre-existing reference text (up to 64 KiB) to edit, rewrite, or format using spoken voice instructions. Requires `mode` to be set to `"SMART"`. | ## Best practices {% id="best-practices" %} * **Provide clean audio:** Ensure audio recordings have clear voice separation and avoid severe clipping. * **Provide language hints when known:** If you know the audio language in advance, specify `language_codes` to maximize accuracy. * **Target custom vocabulary:** Include only distinct domain terms, brand names, or proper nouns in `custom_vocabulary` rather than common everyday words. * **Choose the right file input method:** Upload local recordings with `client.files.upload`, or skip the upload step by passing [external HTTP or signed URLs](/docs/file-input-methods#external-urls) (up to 15 MB), [registered Google Cloud Storage URIs](/docs/file-input-methods#registration) (up to 2 GB), or [inline base64 audio](/docs/file-input-methods#inline-data). See [File input methods](/docs/file-input-methods) for details. ## Limitations {% id="limitations" %} * **Audio duration:** Standard unary requests support audio files up to 1 hour. Audio processing is limited to 30 minutes when features like speaker diarization or word-level timestamps are enabled. Audio exceeding these limits is truncated at the limit while still returning a completed response, so split longer recordings into chunks of 30 minutes or less before sending requests. * **Word-level timestamps:** Enabling word-level timestamps may degrade overall transcription accuracy. * **Speaker diarization:** Speaker diarization supports up to 8 speakers. Speaker attribution for 3 or more speakers is experimental. * **Custom vocabulary:** You can provide up to 1,000 terms in `custom_vocabulary`, but best results are typically achieved with up to 100 terms. You cannot combine `custom_vocabulary` with speaker diarization or word-level timestamps; the API rejects requests that specify `custom_vocabulary` alongside either feature. * **Mode compatibility:** Smart transcription (`mode: "SMART"`) cannot be combined with `word_timestamp` or `diarization`. * **Voice editing (`source_text`):** Voice editing is enabled by default in `"SMART"` mode. Passing pre-existing `source_text` is supported only when `mode` is explicitly set to `"SMART"`, with a maximum `source_text` size of 64 KiB (65,536 bytes). ## What's next {% id="whats-next" %} * Stream real-time audio with the [Live transcription guide](/docs/live-api/live-transcribe) using the Live API. * Explore [Audio understanding](/docs/audio) to analyze, summarize, or query audio content. * Learn how to synthesize audio from text using [Text-to-speech](/docs/speech-generation). * Check the [Pricing page](/docs/pricing#gemini-3.5-transcribe) for model pricing and token limits. * Compare [File input methods](/docs/file-input-methods) and the [Files API](/docs/files) guide for passing and managing audio files.