Gemini API 음성 전사

Gemini API 음성 전사 (Transcribe)

Gemini API는 Gemini 3.5 Transcribe 모델(gemini-3.5-transcribe)로 오디오 파일의 음성을 텍스트로 변환해요. Gemini의 오디오 이해 능력에 기반해 자동 언어 식별, 화자 분리(diarization), 단어 수준 타임스탬프, 커스텀 어휘 힌트와 함께 정확한 전사를 제공합니다. 또한 비유창성 제거와 스마트 포맷팅을 제공하는 스마트 전사 모드도 지원해요.

출처: 문서

본문

오디오 파일을 전사하려면 오디오를 업로드하고 gemini-3.5-transcribe에 전달하세요.

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)

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

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

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

참고: 마이크나 라이브 오디오 스트림에서 실시간·저지연 스트리밍 음성 인식이 필요하다면 Live API와 gemini-3.5-transcribe-live를 사용하는 Live transcription을 참고하세요.

개요

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

주요 기능:

• 자동 음성 인식 (ASR): 85개 이상의 로케일에서 언어를 자동 감지해요. 문장 내·문장 간 코드 스위칭을 수동 구성 없이 처리해요.
• 커스텀 어휘 (Custom vocabulary): 최대 1,000개의 구문을 전달해 인식을 도메인 특정 용어, 약어, 고유명사 쪽으로 편향시켜요.
• 화자 분리 (Speaker diarization): 여러 화자를 구분하고 발화 구간을 서로 다른 라벨에 귀속시켜요.
• 단어 수준 타임스탬프 (Word-level timestamps): 각 인식 단어의 정확한 시작·끝 시간 오프셋을 생성해요.
• 스마트 전사 (Smart transcription): 비유창성, 잡음 단어, 반복을 정리하고 구조화된 포맷팅을 적용해요.
• 포맷팅과 정규화 (Formatting and normalization): 대문자화, 구두점, 역 텍스트 정규화를 적용해요(예: "twenty six million dollars"를 "$26M"으로 변환).

오디오 콘텐츠에 대한 일반 오디오 추론이나 질의응답은 Audio understanding을, 텍스트→음성 오디오 합성은 Text-to-speech를 참고하세요.

언어 감지와 힌트

기본적으로 모델은 음성 언어를 자동 감지해요. 화자가 코드 스위칭하면 언어 사이를 동적으로 전환합니다.

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

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

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: [],
    },
  },
});

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    LanguageCodes: []string{},
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

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

언어를 미리 안다면 language_codes에 BCP-47 언어 코드를 지정해 전사 정확도를 높일 수 있어요(지원 언어 참고).

generation_config = {
    "transcription_config": {
        "language_codes": ["es-ES"],
    }
}

const generationConfig = {
  transcription_config: {
    language_codes: ["es-ES"],
  },
};

package main

import (
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := &interactions.GenerationConfig{
        TranscriptionConfig: &interactions.TranscriptionConfig{
            LanguageCodes: []string{"es-ES"},
        },
    }
    _ = generationConfig
}

{
  "generation_config": {
    "transcription_config": {
      "language_codes": ["es-ES"]
    }
  }
}

커스텀 어휘

음성 모델을 드문 단어, 기술 용어, 브랜드명, 고유명사 쪽으로 유도할 수 있어요. custom_vocabulary 배열에 최대 1,000개의 용어를 제공하세요(보통 최대 100개 용어에서 최상의 결과가 나와요).

참고: custom_vocabulary는 화자 분리나 단어 수준 타임스탬프와 결합할 수 없어요. API는 custom_vocabulary를 두 기능 중 하나와 함께 포함한 요청을 거부해요.

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

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

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    CustomVocabulary: []string{"Gemini", "Kubernetes", "BigQuery"},
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

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

화자 분리 (Speaker diarization)

화자 분리는 녹음에서 서로 다른 목소리를 식별하고 각 구간에 spk_1이나 spk_2 같은 화자 식별자를 붙여요. 최대 8명의 화자를 지원해요(3명 이상 화자의 귀속은 실험적).

mode 안에서 diarization_mode를 구성해 분리를 활성화하세요.

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

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",
      },
    },
  },
});

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                        DiarizationMode: genai.Ptr("speaker"),
                    }))),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

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

단어 수준 타임스탬프

단어 수준 타임스탬프는 오디오 스트림에서 인식된 모든 단어의 정확한 시작·끝 오프셋을 제공해요.

참고: 단어 수준 타임스탬프를 켜면 전체 전사 정확도가 저하될 수 있어요.

mode 안에서 timestamp_granularities를 구성해 타임스탬프를 활성화하세요.

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

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

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                        TimestampGranularities: []string{"word"},
                    }))),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

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

mode에서 diarization_mode와 timestamp_granularities를 결합해 화자 라벨과 단어 타임스탬프를 모두 받을 수 있어요.

generation_config = {
    "transcription_config": {
        "mode": {
            "type": "verbatim",
            "diarization_mode": "speaker",
            "timestamp_granularities": ["word"],
        },
    }
}

const generationConfig = {
  transcription_config: {
    mode: {
      type: "verbatim",
      diarization_mode: "speaker",
      timestamp_granularities: ["word"],
    },
  },
};

package main

import (
    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
)

func main() {
    generationConfig := &interactions.GenerationConfig{
        TranscriptionConfig: &interactions.TranscriptionConfig{
            Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.NewTranscriptionMode(interactions.VerbatimTranscriptionMode{
                DiarizationMode:        genai.Ptr("speaker"),
                TimestampGranularities: []string{"word"},
            }))),
        },
    }
    _ = generationConfig
}

{
  "generation_config": {
    "transcription_config": {
      "mode": {
        "type": "verbatim",
        "diarization_mode": "speaker",
        "timestamp_granularities": ["word"]
      }
    }
  }
}

전사 모드 (Transcription modes)

Gemini 3.5 Transcribe는 mode 파라미터로 두 가지 전사 모드를 지원해요.

• verbatim (기본값): 말한 모든 것을 단어 그대로 정확히 전사해 생(raw) 잡음 단어("um", "uh", "like", "you know"), 반복, 일시정지, 잘못된 시작을 보존해요. 타임스탬프와 화자 분리는 이 모드 안에서 구성돼요({"type": "verbatim", ...}).
• smart (스마트 전사): 지능적 후처리를 적용해 읽기 좋은 전사를 최적화해요.
  • 비유창성 제거: 대화 잡음 단어, 더듬거림, 잘못된 시작을 제거해요.
  • 인라인 자기 수정: 말로 한 수정을 직접 해결해요(예: "Let's meet on Tuesday, actually no, Wednesday at two" → "Let's meet on Wednesday at 2:00 PM").
  • 자동 구조화 포맷팅: 말로 한 생각을 단락, 번호 목록, 글머리 기호, 형식화된 날짜·통화·숫자로 자동 구조화해요.
  • 문법 정리: 자연스러운 구두점, 문장 시작 대문자, 흐름을 적용해요.

말한 오디오	verbatim 출력	smart (스마트 전사) 출력
"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"

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)

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

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    audioFile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp3", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.5-transcribe"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.AudioContent{
                    URI:      genai.Ptr(audioFile.URI),
                    MimeType: interactions.AudioContentMimeType(audioFile.MIMEType).ToPointer(),
                }),
            }),
            GenerationConfig: &interactions.GenerationConfig{
                TranscriptionConfig: &interactions.TranscriptionConfig{
                    Mode: genai.Ptr(interactions.NewTranscriptionConfigMode(interactions.TranscriptionConfigModeEnumSmart)),
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(res.Interaction.GetOutputText())
}

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

참고: 스마트 전사("smart")는 timestamp_granularities와 diarization_mode와 호환되지 않아요. 단어 타임스탬프나 화자 분리가 필요하면 mode를 {"type": "verbatim", ...}으로 구성하세요.

전사 출력 파싱

전체 전사 텍스트는 interaction.output_text에 반환돼요.

timestamp_granularities나 diarization_mode를 켜면 API도 상호작용 콘텐츠에 붙은 상세한 단어 수준 어노테이션을 반환해요.

단어 타임스탬프와 화자 턴을 추출·반복하는 방법은 다음과 같아요.

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

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}`);
}

package main

import (
    "fmt"

    "google.golang.org/genai/interactions/models/interactions"
)

func extractWordAnnotations(interaction *interactions.Interaction) []*interactions.WordInfo {
    var words []*interactions.WordInfo
    if interaction == nil {
        return words
    }
    for _, step := range interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    for _, annotation := range content.TextContent.Annotations {
                        if annotation.WordInfo != nil {
                            words = append(words, annotation.WordInfo)
                        }
                    }
                }
            }
        }
    }
    return words
}

func main() {
    var interaction *interactions.Interaction
    words := extractWordAnnotations(interaction)

    for _, w := range words {
        speaker := ""
        if w.Speaker != nil && *w.Speaker != "" {
            speaker = fmt.Sprintf("[%s] ", *w.Speaker)
        }
        timing := ""
        if w.StartOffset != nil && w.EndOffset != nil {
            timing = fmt.Sprintf("(%s -> %s) ", *w.StartOffset, *w.EndOffset)
        }
        fmt.Printf("%s%s%s\n", speaker, timing, w.GetText())
    }
}

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

지원 언어

Gemini 3.5 Transcribe는 다음 언어와 BCP-47 언어 코드를 지원해요.

언어	BCP-47 코드	언어	BCP-47 코드
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

지원 오디오 형식

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 참조를 참고하세요.

파라미터 참조

generation_config의 transcription_config 객체 안에서 필드를 설정해 전사를 구성해요.

필드	유형	설명
language_codes	문자열 배열	BCP-47 언어 코드(예: ["en-US"]). 생략하거나 비우면([]) 모델이 언어를 자동 감지하고 코드 스위칭을 처리해요.
custom_vocabulary	문자열 배열	음성 인식을 편향시킬 최대 1,000개의 커스텀 용어·약어·고유명사. 화자 분리와 단어 수준 타임스탬프와 호환 불가.
mode	객체 또는 문자열	전사 모드 구성. "smart" 또는 verbatim 모드 객체({"type": "verbatim", ...})를 받음. 기본값은 verbatim 전사.
mode.type	문자열	(Verbatin 모드 전용) 모드 식별자. 항상 "verbatim"으로 설정.
mode.timestamp_granularities	문자열 배열	(Verbatin 모드 전용) 반환할 타임스탬프의 세분성. ["word"]를 전달하면 단어 시작·끝 오프셋 활성화. 커스텀 어휘와 호환 불가.
mode.diarization_mode	문자열	(Verbatin 모드 전용) 분리 모드. "speaker"를 전달하면 서로 다른 화자를 식별·라벨링. 커스텀 어휘와 호환 불가.

모범 사례

• 깨끗한 오디오 제공: 음성 분리가 명확한 녹음을 확보하고 심한 클리핑을 피하세요.
• 알고 있을 때 언어 힌트 제공: 오디오 언어를 미리 안다면 language_codes를 지정해 정확도를 최대화하세요.
• 커스텀 어휘 타겟팅: 일상 단어 대신 custom_vocabulary에 구별되는 도메인 용어, 브랜드명, 고유명사만 포함하세요.
• 큰 녹음에는 Files API 사용: 몇 초보다 긴 파일은 client.files.upload로 업로드하고 반환된 파일 URI를 모델에 전달하세요.

제한 사항

• 오디오 길이: 표준 유너리 요청은 최대 1시간의 오디오 파일을 지원해요. 화자 분리나 단어 수준 타임스탬프 같은 기능을 켜면 오디오 처리는 30분으로 제한돼요.
• 단어 수준 타임스탬프: 단어 수준 타임스탬프를 켜면 전체 전사 정확도가 저하될 수 있어요.
• 화자 분리: 최대 8명의 화자를 지원해요. 3명 이상의 화자 귀속은 실험적이에요.
• 커스텀 어휘: custom_vocabulary에 최대 1,000개의 용어를 제공할 수 있지만, 보통 최대 100개 용어에서 최상의 결과가 나와요. custom_vocabulary를 화자 분리나 단어 수준 타임스탬프와 결합할 수는 없어요. API는 두 기능 중 하나와 함께 custom_vocabulary를 지정한 요청을 거부해요.
• 모드 호환성: 스마트 전사("smart")는 timestamp_granularities나 diarization_mode와 결합할 수 없어요.

다음 단계

• Live API를 사용해 Live transcription guide로 실시간 오디오를 스트리밍하세요.
• 오디오 콘텐츠를 분석·요약·조회하려면 Audio understanding을 살펴보세요.
• 텍스트에서 오디오를 합성하는 방법은 Text-to-speech를 참고하세요.
• 모델 가격과 토큰 한도는 Pricing page를 확인하세요.
• 미디어 파일 업로드·관리 자세한 내용은 Files API 가이드를 확인하세요.

더 알아보기 (Learn more)

gemini-3.5-transcribe는 음성→텍스트 전용 모델로, 자동 언어 감지·화자 분리·단어 타임스탬프·스마트 전사 같은 강력한 기능을 제공해요. custom_vocabulary는 화자 분리나 타임스탬프와 함께 쓸 수 없다는 점을 기억하세요. 실시간 전사가 필요하다면 Live API의 gemini-3.5-transcribe-live를 살펴보는 걸 추천해요.