Gemini 3.5 Transcribe API 가이드: 녹음 전사와 실시간 자막 구현

Gemini 3.5 Transcribe에는 서로 바꿔 쓸 수 없는 두 경로가 있다. 이미 존재하는 회의·통화·인터뷰 파일은 gemini-3.5-transcribe와 Interactions API로 처리한다. 사용자가 말하는 동안 텍스트를 갱신해야 하면 gemini-3.5-transcribe-live와 Live API를 사용한다.

두 모델은 speech-to-text 전용이다. 음성 파일을 요약하거나 질문에 답하는 일반 오디오 이해, 음성으로 대답하는 Live Agent, 실시간 음성 번역, TTS와는 목적이 다르다. 전사 후 요약이나 tool call이 필요하다면 검증된 transcript를 별도의 모델에 넘기는 단계형 구조가 더 명확하다.

Google은 2026년 8월 26일 개발자용 public preview를 공개했다. SDK와 제한이 바뀔 수 있으므로 배포 전에는 Gemini 3.5 Transcribe 모델 페이지를 다시 확인해야 한다.

코드보다 먼저 정할 네 가지

첫째, 결과가 녹음이 끝난 뒤 나와도 되는가? 그렇다면 파일 경로가 더 단순하다. 둘째, 읽기 좋은 정리문이 필요한가, 원음으로 되돌아갈 수 있는 transcript가 필요한가? 이 선택이 smart와 verbatim을 가른다. 셋째, 화자와 단어 시간이 필요한가? 필요하면 Live가 아니라 파일 경로다. 넷째, 실제 한국어 데이터와 민감도에 맞는 업로드·보관 정책이 있는가?

현재 공개된 핵심 한계는 다음과 같다.

실시간 화면과 정밀한 사후 분석이 모두 필요하면 한 모델에 억지로 맡기지 않는다. Live로 자막을 보여 주면서 원본을 저장하고, 종료 후 파일 모델로 화자·타임스탬프를 다시 얻는 것이 현재 계약에 맞는다.

첫 파일 요청은 기능이 아니라 연결을 검증한다

공식 audio transcription 가이드는 Files API 업로드 결과의 URI를 Interactions API에 전달한다.

bash
python -m pip install -U google-genai
export GEMINI_API_KEY="YOUR_API_KEY"

python
from google import genai

client = genai.Client()
audio_file = client.files.upload(file="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)

여기서 성공은 upload 완료, interaction 완료, 비어 있지 않은 output_text, 제출한 오디오와 일치하는 내용이다. model ID, 오디오 길이, MIME type, request status, 빈 출력 여부를 함께 기록한다. 첫 호출부터 언어 hint, vocabulary, smart, 화자, 타임스탬프를 모두 켜면 오류 원인을 찾기 어렵다.

언어를 생략하거나 빈 배열을 전달하면 자동 감지와 중간 언어 전환을 사용한다. 한국어가 중심임을 알고 있다면 현재 공식 목록의 ko-KR을 hint로 줄 수 있다. custom_vocabulary는 최대 1,000개 항목을 받지만 Google은 보통 100개 이하에서 좋은 결과를 본다고 설명한다. 사람 이름, 제품명, 약어, 주문번호처럼 틀렸을 때 손실이 큰 항목부터 넣는다.

output_text만 저장하면 구조를 잃을 수 있다

기본 verbatim은 반복, 머뭇거림, 자기 수정까지 원문에 가깝게 보존한다. 감사, 품질 관리, 자막 동기화, 발언 근거에 적합하다. smart는 군더더기를 제거하고 수정된 의도를 반영하며 숫자와 목록을 읽기 좋게 정돈한다.

하지만 smart mode는 diarization이나 word-level timestamps와 호환되지 않는다. 깔끔한 문서와 추적 가능한 transcript가 모두 필요하다면 verbatim + annotations를 원본으로 저장한 뒤 후처리에서 정리한다.

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", "BigQuery"],
            "mode": {
                "type": "verbatim",
                "diarization_mode": "speaker",
                "timestamp_granularities": ["word"],
            },
        }
    },
)

합쳐진 전체 문장은 interaction.output_text에 있고, 화자 라벨과 단어 시작·종료 offset은 content annotations에 있다. SRT, 클릭 시 오디오 이동, 화자별 시간 계산, 특정 발언 증빙이 목표라면 annotations를 별도로 저장해야 한다.

현재 모델 페이지는 최대 8명 화자를 적지만 3명 이상 attribution을 experimental로 표시한다. word timestamps 역시 전체 정확도를 낮출 수 있다. 다자 회의는 별도 합격 기준을 두고 테스트해야 한다.

Live 자막은 두 개의 텍스트 버퍼가 필요하다

Live transcription 문서의 현재 입력은 raw 16-bit PCM, 16 kHz, mono, little-endian, 100 ms chunk다. 브라우저의 WebM/Opus나 전화망의 8 kHz codec을 그대로 보내면 안 된다. 실제 bytes를 decode와 resample한 뒤 audio/pcm;rate=16000으로 보내야 한다.

python
import asyncio
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        language_codes=["ko-KR"],
    ),
)


async def receive(session):
    async for response in session.receive():
        content = response.server_content
        if content and content.interim_input_transcription:
            replace_preview(content.interim_input_transcription.text)
        if content and content.input_transcription:
            append_final(content.input_transcription.text)


async def main():
    async with client.aio.live.connect(
        model="gemini-3.5-transcribe-live",
        config=config,
    ) as session:
        receiver = asyncio.create_task(receive(session))
        async for chunk in your_pcm_source():
            await session.send_realtime_input(
                audio=types.Blob(
                    data=chunk,
                    mime_type="audio/pcm;rate=16000",
                )
            )
        await session.send_realtime_input(audio_stream_end=True)
        await receiver


asyncio.run(main())

interim_input_transcription은 말하는 동안 계속 바뀌는 추정치다. UI의 현재 preview를 교체해야 한다. input_transcription은 확정된 segment이므로 committed transcript에 추가한다. interim을 모두 append하면 같은 말이 여러 번 저장되고 나중에 수정된 글자도 남는다.

브라우저나 모바일 앱에서 직접 Live 연결을 열 때 장기 API key를 넣지 않는다. 공식 문서는 신뢰할 수 있는 서버가 발급하는 제한된 ephemeral token을 안내한다. 실제 서비스에는 10분 전에 session 교체, reconnect, final dedupe, audio_stream_end, partial/final latency 측정이 추가로 필요하다.

분당 가격보다 전체 파이프라인을 계산한다

2026년 8월 27일 Gemini Developer API 가격표는 녹음 Transcribe를 audio input 약 $0.003/min, text output 약 $0.002/min, 합계 약 $0.005/min으로 추정한다. Live는 input 약 $0.005/min, output 약 $0.004/min, 합계 약 $0.009/min이다. 실제 청구는 token 사용량을 따른다.

단순 환산으로 100시간은 녹음 약 $30, Live 약 $54다. 저장, 변환, 미디어 서버, 실패 재시도, 후속 요약, 모니터링, 사람 수정 비용은 포함하지 않는다. Free Tier는 입력과 출력이 무료지만 데이터가 Google 제품 개선에 사용된다고 표시되고, Paid Tier는 사용되지 않는다고 표시된다. 고객 통화나 내부 회의를 업로드할 때 무료 여부보다 동의, 보관, 지역 규정, 조직 정책을 먼저 확인해야 한다.

한국어 gold set이 통과해야 배포한다

Google은 Artificial Analysis를 인용해 streaming 평균 WER 4.0%, non-streaming 2.6%를 보고했다. 특정 한국어 억양, 전문 용어, 마이크, 소음 환경에 대한 보증은 아니다.

실제 분포에서 20~50개 sample을 고른다. 조용한 녹음, 원거리 마이크, 전화 codec, 빠른 말, 한영 전환, 여러 사람의 겹침을 포함한다. 사람 이름, 금액, 날짜, 주소, 상품 코드, 약속 내용은 전체 WER와 별도 채점한다. Live에서는 interim churn, final 중복, 끊김 복구, 확정 지연도 측정한다.

안전한 순서는 짧고 민감하지 않은 녹음으로 전체 연결을 확인하고, 필요한 mode와 annotations만 추가한 다음, 즉시 표시가 필수일 때 Live를 별도로 검증하는 것이다. 실시간 화자 분리, 실시간 단어 타임스탬프, 교체할 수 없는 10분 초과 session, 전사와 tool call을 한 모델이 동시에 수행해야 한다면 현재 Transcribe 계약과 맞지 않는다.