Google GenAI Transcriptions
Spring AI supports audio transcription with Google’s Gemini Transcribe models through the GoogleGenAiTranscriptionModel, an implementation of the portable TranscriptionModel interface.
The audio is sent inline to a Gemini transcription model through the Google Gen AI SDK (com.google.genai), and the model replies with the transcription text.
Both the Gemini Developer API and Vertex AI are supported.
This implementation provides two authentication modes:
-
Gemini Developer API: Use an API key for quick prototyping and development
-
Vertex AI: Use Google Cloud credentials for production deployments with enterprise features
Prerequisites
Choose one of the following authentication methods:
Option 1: Gemini Developer API (API Key)
-
Obtain an API key from the Google AI Studio
-
Set the API key as an environment variable or in your application properties
Option 2: Vertex AI (Google Cloud)
-
Install the gcloud CLI, appropriate for your OS.
-
Authenticate by running the following command. Replace
PROJECT_IDwith your Google Cloud project ID andACCOUNTwith your Google Cloud username.
gcloud config set project <PROJECT_ID> &&
gcloud auth application-default login <ACCOUNT>
Alternatively, point spring.ai.google.genai.transcription.credentials-uri at a service account JSON, together with spring.ai.google.genai.transcription.project-id.
The default Vertex AI location is global.
Add Repositories and BOM
Spring AI artifacts are published in Maven Central and Spring Snapshot repositories. Refer to the Artifact Repositories section to add these repositories to your build system.
To help with dependency management, Spring AI provides a BOM (bill of materials) to ensure that a consistent version of Spring AI is used throughout the entire project. Refer to the Dependency Management section to add the Spring AI BOM to your build system.
Auto-configuration
|
There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information. |
Spring AI provides Spring Boot auto-configuration for the Google GenAI Transcription Model.
To enable it add the following dependency to your project’s Maven pom.xml file:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-google-genai-transcription</artifactId>
</dependency>
or to your Gradle build.gradle build file:
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-google-genai-transcription'
}
| Refer to the Dependency Management section to add the Spring AI BOM to your build file. |
Transcription Properties
Connection Properties
The prefix spring.ai.google.genai.transcription is used as the property prefix that lets you connect to the Gemini API.
| Property | Description | Default |
|---|---|---|
spring.ai.google.genai.transcription.api-key |
API key for Gemini Developer API. When provided, the client uses the Gemini Developer API instead of Vertex AI. |
- |
spring.ai.google.genai.transcription.project-id |
Google Cloud Platform project ID (required for Vertex AI mode). |
- |
spring.ai.google.genai.transcription.location |
Google Cloud region (required for Vertex AI mode), e.g. |
global |
spring.ai.google.genai.transcription.credentials-uri |
URI to a Google Cloud credentials JSON. When provided, it is used to create a |
- |
spring.ai.google.genai.transcription.vertex-ai |
Explicitly enable Vertex AI mode. Useful when both an API key and Vertex AI configuration are present; otherwise the mode is determined automatically (API key wins). |
false |
Enabling and Disabling Transcription Auto-Configuration
Spring AI uses the configuration property spring.ai.model.audio.transcription to let you enable or disable the transcription model.
To enable, spring.ai.model.audio.transcription set to google-genai (It is enabled by default).
To disable, spring.ai.model.audio.transcription set to none (or any value which doesn’t match google-genai).
This configuration is useful to allow multiple different transcription providers.
spring.ai.model.audio.transcription=google-genai
Transcription Generation Properties
The prefix spring.ai.google.genai.transcription is the property prefix that lets you configure the transcription model.
| Property | Description | Default |
|---|---|---|
spring.ai.google.genai.transcription.model |
The Gemini transcription model to use ( |
gemini-3.5-transcribe |
spring.ai.google.genai.transcription.prompt |
Natural-language instruction guiding the transcription (e.g. formatting, vocabulary hints). |
Transcribe the audio. |
spring.ai.google.genai.transcription.language |
BCP-47 language code of the audio (e.g. |
- |
spring.ai.google.genai.transcription.temperature |
Sampling temperature to use for the transcription request. |
- |
spring.ai.google.genai.transcription.top-p |
The maximum cumulative probability of tokens to consider when sampling (nucleus sampling). |
- |
spring.ai.google.genai.transcription.top-k |
The maximum number of tokens to consider when sampling (top-k sampling). |
- |
spring.ai.google.genai.transcription.candidate-count |
Number of transcription candidates to generate. |
- |
spring.ai.google.genai.transcription.max-output-tokens |
The maximum number of tokens to generate in the transcription. |
- |
spring.ai.google.genai.transcription.stop-sequences |
Sequences where the model stops generating the transcription. |
- |
spring.ai.google.genai.transcription.response-mime-type |
The MIME type of the transcription response (e.g. |
- |
spring.ai.google.genai.transcription.presence-penalty |
Penalty applied to tokens based on their presence in the generated transcription. |
- |
spring.ai.google.genai.transcription.frequency-penalty |
Penalty applied to tokens based on their frequency in the generated transcription. |
- |
spring.ai.google.genai.transcription.seed |
Seed used for deterministic sampling. |
- |
Model Selection
Two Gemini transcription models are available:
-
gemini-3.5-transcribe(the default) transcribes audio files through a standardgenerateContentrequest. -
gemini-3.5-transcribe-liveis designed for real-time (streaming) speech-to-text through the Gemini Live API.
Runtime Options
The GoogleGenAiAudioTranscriptionOptions class provides the options to use when making a transcription.
On start up, the options specified by the spring.ai.google.genai.transcription properties are used, but you can override these at runtime.
For example:
GoogleGenAiAudioTranscriptionOptions transcriptionOptions = GoogleGenAiAudioTranscriptionOptions.builder()
.model("gemini-3.5-transcribe")
.prompt("Transcribe this interview verbatim, including speaker labels.")
.language("en-US")
.temperature(0.1f)
.build();
AudioTranscriptionPrompt transcriptionRequest = new AudioTranscriptionPrompt(audioFile, transcriptionOptions);
AudioTranscriptionResponse response = transcriptionModel.call(transcriptionRequest);
Sample Controller
Create a new Spring Boot project and add the spring-ai-starter-model-google-genai-transcription to your dependencies.
Add an application.properties file under src/main/resources to enable and configure the Google GenAI transcription model:
Using Gemini Developer API (API Key)
spring.ai.google.genai.transcription.api-key=YOUR_API_KEY
spring.ai.google.genai.transcription.model=gemini-3.5-transcribe
spring.ai.google.genai.transcription.language=en-US
Using Vertex AI
spring.ai.google.genai.transcription.project-id=YOUR_PROJECT_ID
spring.ai.google.genai.transcription.location=YOUR_PROJECT_LOCATION
spring.ai.google.genai.transcription.model=gemini-3.5-transcribe
@RestController
public class TranscriptionController {
private final GoogleGenAiTranscriptionModel transcriptionModel;
@Value("classpath:/speech/jfk.flac")
private Resource audioFile;
TranscriptionController(GoogleGenAiTranscriptionModel transcriptionModel) {
this.transcriptionModel = transcriptionModel;
}
@GetMapping("/ai/transcription")
public String transcribe() {
AudioTranscriptionPrompt prompt = new AudioTranscriptionPrompt(this.audioFile);
AudioTranscriptionResponse response = this.transcriptionModel.call(prompt);
return response.getResult().getOutput();
}
}
Manual Configuration
Add the spring-ai-google-genai-transcription dependency to your project’s Maven pom.xml file:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-google-genai-transcription</artifactId>
</dependency>
or to your Gradle build.gradle build file:
dependencies {
implementation 'org.springframework.ai:spring-ai-google-genai-transcription'
}
| Refer to the Dependency Management section to add the Spring AI BOM to your build file. |
Next, create a GoogleGenAiTranscriptionModel:
Using API Key
var connectionDetails = GoogleGenAiTranscriptionConnectionDetails.builder()
.apiKey(System.getenv("GOOGLE_API_KEY"))
.build();
var options = GoogleGenAiAudioTranscriptionOptions.builder()
.model("gemini-3.5-transcribe")
.language("en-US")
.build();
var transcriptionModel = new GoogleGenAiTranscriptionModel(connectionDetails, options);
var audioFile = new FileSystemResource("/path/to/audio.wav");
AudioTranscriptionResponse response = transcriptionModel
.call(new AudioTranscriptionPrompt(audioFile));
System.out.println(response.getResult().getOutput());
Using Vertex AI
var connectionDetails = GoogleGenAiTranscriptionConnectionDetails.builder()
.projectId(System.getenv("GOOGLE_CLOUD_PROJECT"))
.location(System.getenv("GOOGLE_CLOUD_LOCATION"))
.build();
var options = GoogleGenAiAudioTranscriptionOptions.builder()
.model("gemini-3.5-transcribe")
.language("en-US")
.build();
var transcriptionModel = new GoogleGenAiTranscriptionModel(connectionDetails, options);
var audioFile = new FileSystemResource("/path/to/audio.wav");
AudioTranscriptionResponse response = transcriptionModel
.call(new AudioTranscriptionPrompt(audioFile));
System.out.println(response.getResult().getOutput());