이제 Interactions API가 정식 버전으로 출시되었습니다. 이 API를 사용하여 모든 최신 기능과 모델에 액세스하는 것이 좋습니다.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

오디오 스크립트 작성

Gemini API는 Gemini 3.5 Transcribe 모델 (gemini-3.5-transcribe)을 사용하여 오디오 파일의 음성을 텍스트로 변환합니다. Gemini의 오디오 이해 기능을 기반으로 자동 언어 식별, 화자 분리, 단어 수준 타임스탬프, 맞춤 어휘 힌트를 사용하여 정확한 변환을 제공합니다. 또한 머뭇거림 삭제 및 스마트 서식 지정 기능이 포함된 스마트 스크립트 모드도 제공합니다.

오디오 파일을 텍스트로 변환하려면 오디오를 업로드하고 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)

자바스크립트

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

개요

Gemini 3.5 Transcribe는 음성 텍스트 변환 작업에 최적화되어 있습니다. 다양한 억양, 배경 소음, 다국어 대화를 처리합니다.

주요 기능은 다음과 같습니다.

자동 음성 인식 (ASR): 85개 이상의 언어를 자동으로 감지합니다. 수동 구성 없이 문장 내 및 문장 간 코드 전환을 처리합니다.
맞춤 어휘: 최대 1, 000개의 구문을 전달하여 도메인별 용어, 약어,고유명사에 대한 인식을 편향시킵니다.
화자 분리: 여러 화자를 구분하고 발화된 세그먼트를 고유한 라벨에 속성으로 지정합니다.
단어 수준 타임스탬프: 인식된 각 단어의 정확한 시작 및 종료 타임스탬프를 생성합니다.
스마트 스크립트: 유창하지 않은 부분, 추임새, 반복을 정리하고 구조화된 서식을 적용합니다.
형식 지정 및 정규화: 대문자, 구두점, 역 텍스트 정규화(예: '2천6백만 달러'를 '2, 600만 달러'로 변환)를 적용합니다.

오디오 콘텐츠에 대한 일반적인 오디오 추론 또는 질의 응답에는 오디오 이해를 사용하세요. 텍스트 음성 변환 오디오 합성에는 텍스트 음성 변환을 사용합니다.

언어 감지 및 힌트

기본적으로 모델은 음성 언어를 자동으로 감지합니다. 화자가 코드 전환을 하면 언어를 동적으로 전환합니다.

자동 감지를 사용하려면 language_codes를 생략하거나 빈 목록을 제공하세요.

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=[],
        )
    ),
)

자바스크립트

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

언어를 미리 알고 있는 경우 language_codes에 BCP-47 언어 코드를 지정하여 전사 정확도를 높이세요 (지원되는 언어 참고).

Python

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

자바스크립트

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

REST

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

커스텀 어휘

음성 모델이 흔하지 않은 단어, 전문 용어, 브랜드 이름 또는 고유 명사를 인식하도록 조정할 수 있습니다. custom_vocabulary 배열에 최대 1,000개의 용어를 제공합니다 (최상의 결과는 일반적으로 최대 100개의 용어로 달성됨).

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

자바스크립트

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

화자 분할

화자 분할은 녹음 파일에서 서로 다른 음성을 식별하고 각 세그먼트에 spk_1 또는 spk_2와 같은 화자 식별자로 태그를 지정합니다. 최대 8명의 화자가 지원됩니다 (3명 이상의 화자에 대한 속성은 실험적임).

diarization을 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,
        )
    ),
)

자바스크립트

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

단어 수준 타임스탬프

단어 수준 타임스탬프는 오디오 스트림에서 인식된 모든 단어의 정확한 시작 및 종료 오프셋을 제공합니다.

word_timestamp을 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,
        )
    ),
)

자바스크립트

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

단일 요청에서 diarization와 word_timestamp을 결합하여 화자 라벨과 단어 타임스탬프를 모두 수신할 수 있습니다.

Python

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

자바스크립트

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

REST

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

스크립트 작성 모드

Gemini 3.5 Transcribe는 mode 파라미터를 통해 두 가지 스크립트 모드를 지원합니다.

VERBATIM (기본값): 말한 모든 내용을 단어별로 정확하게 기록하며, 원시 필러 단어 ('음', '어', '그', '알잖아'), 반복, 일시중지, 잘못된 시작을 보존합니다. 타임스탬프 또는 화자 분리를 사용하는 경우 필요합니다.
SMART (스마트 스크립트): 지능형 후처리를 적용하여 읽기용 스크립트를 최적화합니다.
- 말더듬기 제거: 대화형 필러 단어, 말더듬기, 잘못된 시작을 제거합니다.
- 인라인 자체 수정: 말한 수정사항을 직접 해결합니다 (예:'화요일에 만나자. 아니, 수요일 2시에 만나자'가 '수요일 오후 2시에 만나자'가 됨).
- 자동 구조화된 형식 지정: 음성으로 말한 생각을 단락, 번호 매기기 목록, 글머리 기호, 형식화된 날짜, 통화, 숫자로 자동 구조화합니다.
- 문법 정리: 자연스러운 구두점, 문장 대소문자, 흐름을 적용합니다.

음성 오디오	`VERBATIM` 출력	`SMART` (스마트 스크립트) 출력
'음, 회의에는 앨리스를 초대해야 할 것 같아. 아니, 밥과 캐롤을 초대해야 해.'	'음, 회의에는 앨리스를 초대해야 할 것 같아. 아니, 밥과 캐롤을 초대해야 해.'	'회의에 김민수와 이수진을 초대하는 게 좋을 것 같아.'
'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. 예산 검토 2. 타임라인을 마무리합니다. 3. 요약 보내기'

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)

자바스크립트

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

스크립트 출력 파싱

전체 스크립트 텍스트가 response.text에 반환됩니다.

word_timestamp 또는 diarization가 사용 설정되면 API는 후보 부분에 연결된 자세한 단어 수준 주석과 화자 라벨도 반환합니다.

단어 타임스탬프와 화자 전환을 추출하고 반복하는 방법은 다음과 같습니다.

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

자바스크립트

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

지원 언어

Gemini 3.5 Transcribe에서 지원되는 언어와 BCP-47 언어 코드는 다음과 같습니다.

언어	BCP-47 코드	언어	BCP-47 코드
아프리칸스어	`af-ZA`	일본어	`ja-JP`
암하라어	`am-ET`	자바어	`jv-ID`
아랍어(이집트)	`ar-EG`	Kabuverdianu	`kea-CV`
아르메니아어	`hy-AM`	칸나다어	`kn-IN`
아삼어	`as-IN`	카자흐어	`kk-KZ`
아제르바이잔어	`az-AZ`	한국어	`ko-KR`
벨라루스어	`be-BY`	키르기스어	`ky-KG`
벵골어(방글라데시)	`bn-BD`	라트비아어	`lv-LV`
벵골어(인도)	`bn-IN`	링갈라어	`ln-CD`
보스니아어	`bs-BA`	리투아니아어	`lt-LT`
불가리아어	`bg-BG`	마케도니아어	`mk-MK`
불가리아어 (아로마어)	`rup-BG`	말레이어	`ms-MY`
버마어	`my-MM`	말라얄람어	`ml-IN`
광둥어 (번체)	`yue-Hant-HK`	몰타어	`mt-MT`
카탈로니아어	`ca-ES`	중국어 (간체)	`cmn-Hans-CN`
세부아노어	`ceb`	마라타어	`mr-IN`
표준 크메르어	`km-KH`	몽골어	`mn-MN`
크로아티아어	`hr-HR`	네팔어	`ne-NP`
체코어	`cs-CZ`	노르웨이어	`nb-NO`
덴마크어	`da-DK`	오리야어	`or-IN`
네덜란드어	`nl-NL`	폴란드어	`pl-PL`
영어(영국)	`en-GB`	포르투갈어(브라질)	`pt-BR`
영어(인도)	`en-IN`	포르투갈어(포르투갈)	`pt-PT`
영어(미국)	`en-US`	펀자브어	`pa-IN`
에스토니아어	`et-EE`	펀자브어 (구르무키 문자)	`pa-Guru-IN`
페르시아어	`fa-IR`	루마니아어	`ro-RO`
필리핀어	`fil-PH`	러시아어	`ru-RU`
핀란드어	`fi-FI`	세르비아어	`sr-RS`
프랑스어	`fr-FR`	신디어 (아랍 문자)	`sd-Arab-IN`
갈리시아어	`gl-ES`	슬로바키아어	`sk-SK`
조지아어	`ka-GE`	슬로베니아어	`sl-SI`
독일어	`de-DE`	스페인어(라틴 아메리카)	`es-419`
그리스어	`el-GR`	스페인어(미국)	`es-US`
구자라트어	`gu-IN`	스와힐리어(케냐)	`sw-KE`
하우사어	`ha-NG`	스웨덴어	`sv-SE`
히브리어	`he-IL`	타지크어	`tg-TJ`
힌디어	`hi-IN`	텔루구어	`te-IN`
헝가리어	`hu-HU`	태국어	`th-TH`
아이슬란드어	`is-IS`	튀르키예어	`tr-TR`
인도 영어	`en-IN`	우크라이나어	`uk-UA`
인도네시아어	`id-ID`	우즈베크어	`uz-UZ`
이탈리아어	`it-IT`	베트남어	`vi-VN`

지원되는 오디오 형식

Gemini 3.5 Transcribe는 다음 오디오 형식 MIME 유형을 지원합니다.

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

지원되는 MIME 유형 및 매개변수 스키마의 전체 목록은 Interactions API 참조를 참고하세요.

파라미터 참조

GenerateContentConfig에서 audio_transcription_config 객체 내 필드를 설정하여 트랜스크립션을 구성합니다.

필드	유형	설명
`language_codes`	문자열 배열	BCP-47 언어 코드 (예: `["en-US"]`)입니다. 생략되거나 비어 있는 경우 (`[]`) 모델이 언어를 자동으로 감지하고 코드 전환을 처리합니다.
`custom_vocabulary`	문자열 배열	음성 인식을 편향시킬 수 있는 최대 1,000개의 맞춤 용어, 약어 또는 고유 이름
`word_timestamp`	불리언	단어 시작 및 종료 오프셋을 포함하려면 `True`로 설정합니다. 생략되거나 `False`인 경우 단어 타임스탬프가 반환되지 않습니다.
`diarization`	불리언	명확히 구분되는 발화자를 식별하고 라벨을 지정하려면 `True`로 설정합니다.
`mode`	문자열	스크립트 작성 모드입니다. 지원되는 값은 `"VERBATIM"` (기본값) 및 `"SMART"`입니다. 타임스탬프 및 분할과 호환되지 않습니다.

권장사항

깔끔한 오디오 제공: 오디오 녹음에서 음성 분리가 명확하고 심각한 클리핑이 없는지 확인합니다.
언어를 알고 있는 경우 언어 힌트 제공: 오디오 언어를 미리 알고 있는 경우 language_codes를 지정하여 정확도를 극대화하세요.
타겟 맞춤 어휘: 일반적인 일상 단어 대신 custom_vocabulary에 고유한 도메인 용어, 브랜드 이름 또는 고유명사만 포함합니다.
대규모 녹음 파일에 Files API 사용: 몇 초보다 긴 파일의 경우 client.files.upload를 사용하여 파일을 업로드하고 반환된 파일을 모델 콘텐츠에 전달합니다.

제한사항

오디오 길이: 표준 단항 요청은 최대 1시간 길이의 오디오 파일을 지원합니다. 화자 분할 또는 단어 수준 타임스탬프와 같은 기능을 사용 설정하면 오디오 처리가 30분으로 제한됩니다.
단어 수준 타임스탬프: 단어 수준 타임스탬프를 사용 설정하면 전체 변환 텍스트의 정확도가 저하될 수 있습니다.
화자 분할: 화자 분할은 최대 8명의 화자를 지원합니다. 3명 이상의 화자에 대한 화자 속성은 실험 단계에 있습니다.
맞춤 어휘: custom_vocabulary에 최대 1,000개의 단어를 제공할 수 있지만 일반적으로 최대 100개의 단어로 최상의 결과를 얻을 수 있습니다.
모드 호환성: 스마트 스크립트 (mode: "SMART")는 word_timestamp 또는 diarization와 함께 사용할 수 없습니다.

다음 단계

Live API를 사용하여 실시간 스크립트 가이드로 실시간 오디오를 스트리밍합니다.
오디오 이해를 살펴보고 오디오 콘텐츠를 분석, 요약하거나 쿼리하세요.
Text-to-speech를 사용하여 텍스트에서 오디오를 합성하는 방법을 알아봅니다.
모델 가격 및 토큰 한도는 가격 책정 페이지를 확인하세요.
미디어 파일 업로드 및 관리에 관한 자세한 내용은 Files API 가이드를 참고하세요.