# AI SDK with Gemini API

Gemini models are accessible using the [AI SDK](https://ai-sdk.dev) by Vercel. This guide will help you get started with 
the AI SDK and Gemini.

For more information, see the following resources:

- [AI SDK docs](https://ai-sdk.dev/docs)
- [AI SDK Google Generative AI docs](https://ai-sdk.dev/providers/ai-sdk-providers/google-generative-ai)

## Setup

Install the AI SDK and the Google Generative AI integration:

```bash
npm install ai
npm install @ai-adk/google
// pnpm: pnpm add ai @ai-sdk/google
// yarn: yarn add ai @ai-sdk/google
```

Set the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable with your API key:

```bash
# MacOS/Linux
export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY_HERE"

# Powershell
setx GOOGLE_GENERATIVE_AI_API_KEY "YOUR_API_KEY_HERE"
```


## Getting Started

Here's a basic example that takes a single text input:

```ts
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';

const model = google('gemini-2.0-flash');

const { text } = await generateText({
  model: model,
  prompt: 'Why is the sky blue?',
  // system: 'You are a friendly assistant!',
  // temperature: 0.7,
});

console.log(text);
```

## Streaming

Here's a basic streaming example:

```ts
import { streamText } from 'ai';
import { google } from '@ai-sdk/google';

const model = google('gemini-2.0-flash');

const { textStream }  = streamText({
  model: model,
  prompt: 'Why is the sky blue?',
});

for await (const textPart of textStream) {
  console.log(textPart);
}
```

## Document / PDF understanding

The AI SDK supports file inputs, e.g. PDF files:

```ts
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';
import { readFile } from 'fs/promises';  // npm install @types/node

const model = google('gemini-2.0-flash');

const { text }  = await generateText({
  model: model,
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Extract the date and price from the invoice',
        },
        {
          type: 'file',
          data: await readFile('./invoice.pdf'),
          mimeType: 'application/pdf',
        },
      ],
    },
  ],
});

console.log(text);
```

## Image understanding

The AI SDK supports image inputs:

```ts
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';
import { readFile } from 'fs/promises';  // npm install @types/node

const model = google('gemini-2.0-flash');

const { text }  = await generateText({
  model: model,
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'List all items from the picture',
        },
        {
          type: 'image',
          image: await readFile('./veggies.jpeg'),
          mimeType: 'image/jpeg',
        },
      ],
    },
  ],
});

console.log(text);
```

## Structured output

The AI SDK supports structured outputs:

```ts
import { generateObject } from 'ai';
import { z } from 'zod';
import { google } from '@ai-sdk/google';
import { readFile } from 'fs/promises';

const model = google('gemini-2.0-flash');

const { object } = await generateObject({
  model: model,
  schema: z.object({
    date: z.string(),
    total_gross_worth: z.number(),
    invoice_number: z.string()
  }),
  messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: 'Extract the structured data from the following PDF file',
          },
          {
            type: 'file',
            data: await readFile('./invoice.pdf'),
            mimeType: 'application/pdf',
          },
        ],
      },
    ],
});

console.log(object)
```

See the [AI SDK structured data guide](https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data) for further resources.

## Grounding with Google Search

You can configure [Search grounding](https://ai.google.dev/gemini-api/docs/grounding) with Google Search:

```ts
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';

const model = google('gemini-2.0-flash', { useSearchGrounding: true });

const { text, sources, providerMetadata } = await generateText({
  model: model,
  prompt: 'Who won the Super Bowl in 2025?',
});

console.log(text);

console.log("Sources:")
console.log(sources);

console.log("Metadata:")
console.log(providerMetadata?.google.groundingMetadata);
```

## Thinking

You can use [thinking models](https://ai.google.dev/gemini-api/docs/thinking) with support for thinking budgets and thought summaries:

```ts
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';
import { GoogleGenerativeAIProviderOptions } from '@ai-sdk/google';

const model = google('gemini-2.5-flash-preview-05-20');

const response = await generateText({
  model: model,
  prompt: 'Why is the sky blue?',
  providerOptions: {
    google: {
      thinkingConfig: {
        thinkingBudget: 2024,
        includeThoughts: true
      },
    } satisfies GoogleGenerativeAIProviderOptions,
  },
});

console.log(response.text);

// Log the reasoning summary
console.log("Reasoning");
console.log(response.reasoning);
```

## Tools and function calling

The AI SDK supports function calling:

```ts
import { z } from 'zod';
import { generateText, tool } from 'ai';
import { google } from '@ai-sdk/google';

const model = google('gemini-2.5-flash-preview-05-20');

const result = await generateText({
  model: model,
  prompt: 'What is the weather in San Francisco?',
  tools: {
    weather: tool({
      description: 'Get the weather in a location',
      parameters: z.object({
        location: z.string().describe('The location to get the weather for'),
      }),
      // execute: An optional async function that is called with the arguments from the tool call.
      execute: async ({ location }) => ({
        location,
        temperature: 72 + Math.floor(Math.random() * 21) - 10,
      }),
    }),
  },
  maxSteps: 5, // Optional, enables multi step calling
});

console.log(result.text)

// Inspect the different messages, this will contain messages from the different steps
// here:
// Step 1 with tool-call and tool-result messages
// Step 2 with the final generated text based on the tool result
for (const message of result.response.messages) {
    console.log(message.content);
}
```

See the [AI SDK tool calling guide](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling) for further resources.

## Limitations

The Vercel AI SDK and the AI SDK Google integration are third-party libraries developed and maintained by the Vercel team. While designed to work seamlessly with the Gemini API, it is not an official Google product.

We cannot guarantee complete feature parity or identical behavior between the Vercel AI SDK's implementation and the official Gemini API. Certain features, newly released capabilities, or specific API parameters might not be immediately available or fully supported within the SDK.