Skip to main content

Google logoGoogle

Access 39 Google models through Mastra's model router. Authentication is handled automatically using one of the following environment variables: GOOGLE_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY.

Learn more in the Google documentation.

.env
GOOGLE_API_KEY=your-api-key
GOOGLE_GENERATIVE_AI_API_KEY=your-api-key
src/mastra/agents/my-agent.ts
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "google/deep-research-max-preview-04-2026"
});

// Generate a response
const response = await agent.generate("Hello!");

// Stream a response
const stream = await agent.stream("Tell me a story");
for await (const chunk of stream) {
  console.log(chunk);
}

Models
Direct link to Models

ModelContextToolsReasoningImageAudioVideoInput $/1MOutput $/1M
google/deep-research-max-preview-04-2026131K$2$12
google/deep-research-preview-04-2026131K$2$12
google/gemini-2.5-computer-use-preview-10-2025131K$1$10
google/gemini-2.5-flash1.0M$0.30$3
google/gemini-2.5-flash-image33K$0.30$30
google/gemini-2.5-flash-lite1.0M$0.10$0.40
google/gemini-2.5-flash-preview-tts8K$0.50$10
google/gemini-2.5-pro1.0M$1$10
google/gemini-2.5-pro-preview-tts8K$1$20
google/gemini-3-flash-preview1.0M$0.50$3
google/gemini-3-pro-image131K$2$120
google/gemini-3-pro-image-preview131K$2$120
google/gemini-3.1-flash-image66K$0.50$60
google/gemini-3.1-flash-image-preview66K$0.50$60
google/gemini-3.1-flash-lite1.0M$0.25$2
google/gemini-3.1-flash-lite-image66K$0.25$30
google/gemini-3.1-flash-live-preview131K$0.75$5
google/gemini-3.1-flash-tts-preview8K$1$20
google/gemini-3.1-pro-preview1.0M$2$12
google/gemini-3.1-pro-preview-customtools1.0M$2$12
google/gemini-3.5-flash1.0M$2$9
google/gemini-3.5-flash-lite1.0M$0.30$3
google/gemini-3.5-live-translate-preview16K$4$21
google/gemini-3.6-flash1.0M$0.75$4
google/gemini-3.7-flash1.0M$0.75$4
google/gemini-3.8-flash1.0M$0.75$4
google/gemini-embedding-0012K$0.15—
google/gemini-embedding-28K$0.20—
google/gemini-flash-latest1.0M$0.75$4
google/gemini-flash-lite-latest1.0M$0.30$3
google/gemini-omni-flash-preview131K$2$18
google/gemma-4-26b-a4b-it262K——
google/gemma-4-31b-it262K——
google/lyria-3-clip-preview1.0M——
google/lyria-3-pro-preview1.0M——
google/veo-3.1-fast-generate-preview480——
google/veo-3.1-generate-preview480——
google/veo-3.1-lite-generate-preview480——
38 available models

Model availability, capabilities, context windows, and pricing are sourced from models.dev and may change.

Advanced configuration
Direct link to Advanced configuration

Custom headers
Direct link to Custom headers

src/mastra/agents/my-agent.ts
const agent = new Agent({
  id: "custom-agent",
  name: "custom-agent",
  model: {
    id: "google/deep-research-max-preview-04-2026",
    apiKey: process.env.GOOGLE_API_KEY,GOOGLE_GENERATIVE_AI_API_KEY,
    headers: {
      "X-Custom-Header": "value"
    }
  }
});

Dynamic model selection
Direct link to Dynamic model selection

src/mastra/agents/my-agent.ts
const agent = new Agent({
  id: "dynamic-agent",
  name: "Dynamic Agent",
  model: ({ requestContext }) => {
    const useAdvanced = requestContext.task === "complex";
    return useAdvanced
      ? "google/veo-3.1-lite-generate-preview"
      : "google/deep-research-max-preview-04-2026";
  }
});

Provider Options
Direct link to Provider Options

Google supports the following provider-specific options via the providerOptions parameter:

const response = await agent.generate("Hello!", {
  providerOptions: {
    google: {
      // See available options in the table below
    }
  }
});

Available Options
Direct link to Available Options

responseModalities?:

("TEXT" | "IMAGE")[] | undefined

thinkingConfig?:

{ thinkingBudget?: number | undefined; includeThoughts?: boolean | undefined; thinkingLevel?: "minimal" | "low" | "medium" | "high" | undefined; } | undefined

cachedContent?:

string | undefined

structuredOutputs?:

boolean | undefined

safetySettings?:

{ category: "HARM_CATEGORY_UNSPECIFIED" | "HARM_CATEGORY_HATE_SPEECH" | "HARM_CATEGORY_DANGEROUS_CONTENT" | "HARM_CATEGORY_HARASSMENT" | "HARM_CATEGORY_SEXUALLY_EXPLICIT" | "HARM_CATEGORY_CIVIC_INTEGRITY"; threshold: "HARM_BLOCK_THRESHOLD_UNSPECIFIED" | ... 4 more ... | "OFF"; }[] | undefined

threshold?:

"HARM_BLOCK_THRESHOLD_UNSPECIFIED" | "BLOCK_LOW_AND_ABOVE" | "BLOCK_MEDIUM_AND_ABOVE" | "BLOCK_ONLY_HIGH" | "BLOCK_NONE" | "OFF" | undefined

audioTimestamp?:

boolean | undefined

labels?:

Record<string, string> | undefined

mediaResolution?:

"MEDIA_RESOLUTION_UNSPECIFIED" | "MEDIA_RESOLUTION_LOW" | "MEDIA_RESOLUTION_MEDIUM" | "MEDIA_RESOLUTION_HIGH" | undefined

imageConfig?:

{ aspectRatio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "4:5" | "5:4" | "9:16" | "16:9" | "21:9" | "1:8" | "8:1" | "1:4" | "4:1" | undefined; imageSize?: "1K" | "2K" | "4K" | "512" | undefined; personGeneration?: "PERSON_GENERATION_UNSPECIFIED" | ... 3 more ... | undefined; prominentPeople?: "PROMINENT_PEOPLE_UNSPEC...

retrievalConfig?:

{ latLng?: { latitude: number; longitude: number; } | undefined; } | undefined

streamFunctionCallArguments?:

boolean | undefined

serviceTier?:

"standard" | "flex" | "priority" | undefined

sharedRequestType?:

"standard" | "flex" | "priority" | undefined

requestType?:

"shared" | undefined
On this page