Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

gemini.md

283 lines6.0 KB

The Google Gemini adapter provides access to Google's Gemini models, including text generation, image generation with Imagen, and experimental text-to-speech.

Installation

npm install @tanstack/ai-gemini

Basic Usage

import { chat } from "@tanstack/ai";
import { geminiText } from "@tanstack/ai-gemini";

const stream = chat({
  adapter: geminiText("gemini-2.5-pro"),
  messages: [{ role: "user", content: "Hello!" }],
});

Basic Usage - Custom API Key

import { chat } from "@tanstack/ai";
import { createGeminiChat } from "@tanstack/ai-gemini";

const adapter = createGeminiChat(process.env.GEMINI_API_KEY!, {
  // ... your config options
});

const stream = chat({
  adapter: adapter("gemini-2.5-pro"),
  messages: [{ role: "user", content: "Hello!" }],
});

Configuration

import { createGeminiChat, type GeminiChatConfig } from "@tanstack/ai-gemini";

const config: Omit<GeminiChatConfig, 'apiKey'> = {
  baseURL: "https://generativelanguage.googleapis.com/v1beta", // Optional
};

const adapter = createGeminiChat(process.env.GEMINI_API_KEY!, config);

Example: Chat Completion

import { chat, toStreamResponse } from "@tanstack/ai";
import { geminiText } from "@tanstack/ai-gemini";

export async function POST(request: Request) {
  const { messages } = await request.json();

  const stream = chat({
    adapter: geminiText("gemini-2.5-pro"),
    messages,
  });

  return toStreamResponse(stream);
}

Example: With Tools

import { chat, toolDefinition } from "@tanstack/ai";
import { geminiText } from "@tanstack/ai-gemini";
import { z } from "zod";

const getCalendarEventsDef = toolDefinition({
  name: "get_calendar_events",
  description: "Get calendar events for a date",
  inputSchema: z.object({
    date: z.string(),
  }),
});

const getCalendarEvents = getCalendarEventsDef.server(async ({ date }) => {
  // Fetch calendar events
  return { events: [] };
});

const stream = chat({
  adapter: geminiText("gemini-2.5-pro"),
  messages,
  tools: [getCalendarEvents],
});

Model Options

Gemini supports various model-specific options:

const stream = chat({
  adapter: geminiText("gemini-2.5-pro"),
  messages,
  modelOptions: {
    maxOutputTokens: 2048,
    temperature: 0.7,
    topP: 0.9,
    topK: 40,
    stopSequences: ["END"],
  },
});

Thinking

Enable thinking for models that support it:

modelOptions: {
  thinking: {
    includeThoughts: true,
  },
}

Structured Output

Configure structured output format:

modelOptions: {
  responseMimeType: "application/json",
}

Summarization

Summarize long text content:

import { summarize } from "@tanstack/ai";
import { geminiSummarize } from "@tanstack/ai-gemini";

const result = await summarize({
  adapter: geminiSummarize("gemini-2.5-pro"),
  text: "Your long text to summarize...",
  maxLength: 100,
  style: "concise", // "concise" | "bullet-points" | "paragraph"
});

console.log(result.summary);

Image Generation

Generate images with Imagen:

import { generateImage } from "@tanstack/ai";
import { geminiImage } from "@tanstack/ai-gemini";

const result = await generateImage({
  adapter: geminiImage("imagen-3.0-generate-002"),
  prompt: "A futuristic cityscape at sunset",
  numberOfImages: 1,
});

console.log(result.images);

Image Model Options

const result = await generateImage({
  adapter: geminiImage("imagen-3.0-generate-002"),
  prompt: "...",
  modelOptions: {
    aspectRatio: "16:9", // "1:1" | "3:4" | "4:3" | "9:16" | "16:9"
    personGeneration: "DONT_ALLOW", // Control person generation
    safetyFilterLevel: "BLOCK_SOME", // Safety filtering
  },
});

Text-to-Speech (Experimental)

Note: Gemini TTS is experimental and may require the Live API for full functionality.

Generate speech from text:

import { generateSpeech } from "@tanstack/ai";
import { geminiSpeech } from "@tanstack/ai-gemini";

const result = await generateSpeech({
  adapter: geminiSpeech("gemini-2.5-flash-preview-tts"),
  text: "Hello from Gemini TTS!",
});

console.log(result.audio); // Base64 encoded audio

Environment Variables

Set your API key in environment variables:

GEMINI_API_KEY=your-api-key-here
# or
GOOGLE_API_KEY=your-api-key-here

Getting an API Key

  1. Go to Google AI Studio
  2. Create a new API key
  3. Add it to your environment variables

API Reference

geminiText(config?)

Creates a Gemini text/chat adapter using environment variables.

Returns: A Gemini text adapter instance.

createGeminiText(apiKey, config?)

Creates a Gemini text/chat adapter with an explicit API key.

Parameters:

  • apiKey - Your Gemini API key
  • config.baseURL? - Custom base URL (optional)

Returns: A Gemini text adapter instance.

geminiSummarize(config?)

Creates a Gemini summarization adapter using environment variables.

Returns: A Gemini summarize adapter instance.

createGeminiSummarize(apiKey, config?)

Creates a Gemini summarization adapter with an explicit API key.

Returns: A Gemini summarize adapter instance.

geminiImage(config?)

Creates a Gemini image generation adapter using environment variables.

Returns: A Gemini image adapter instance.

createGeminiImage(apiKey, config?)

Creates a Gemini image generation adapter with an explicit API key.

Returns: A Gemini image adapter instance.

geminiTTS(config?)

Creates a Gemini TTS adapter using environment variables.

Returns: A Gemini TTS adapter instance.

createGeminiTTS(apiKey, config?)

Creates a Gemini TTS adapter with an explicit API key.

Returns: A Gemini TTS adapter instance.

Next Steps