본문으로 건너뛰기

Google Gemini

Google Gemini 어댑터를 사용하면 Google의 Gemini 모델에 액세스할 수 있습니다. 텍스트 생성, Imagen 및 Gemini 네이티브 이미지 모델(NanoBanana)을 사용한 이미지 생성, 실험적 텍스트 음성 변환을 지원합니다.

이미지 생성이 포함된 전체 작동 예제는 미디어 생성 예제 앱을 참조합니다.

설치​

npm install @tanstack/ai-gemini

Vertex AI에서 Gemini가 필요합니까(리전 엔드포인트 및 Google Cloud 자격 증명)? Vertex 어댑터를 사용합니다.

기본 사용법​

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

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

기본 사용법 - 사용자 지정 API 키​

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

const adapter = createGeminiChat("gemini-3.1-pro-preview", process.env.GEMINI_API_KEY!, {
  // ... your config options
});

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

구성​

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

const config: Omit<GeminiTextConfig, "apiKey"> = {
  httpOptions: {
    baseUrl: "https://generativelanguage.googleapis.com/v1beta", // Optional
  },
};

const adapter = createGeminiChat("gemini-3.1-pro-preview", process.env.GEMINI_API_KEY!, config);

예제: 채팅 완성​

import { chat, toServerSentEventsResponse } 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-3.1-pro-preview"),
    messages,
  });

  return toServerSentEventsResponse(stream);
}

예제: 도구 사용​

import { chat, toServerSentEventsResponse, 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: [] };
});

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

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

  return toServerSentEventsResponse(stream);
}

상태 저장 대화 — Interactions API(실험적)​

Gemini의 Interactions API(현재 베타)는 서버 측 대화 상태를 제공합니다. 이는 OpenAI Responses API에 해당하는 Gemini 기능입니다. 매 턴마다 전체 메시지 기록을 재생하는 대신 previous_interaction_id를 전달하면 서버가 대화 기록을 보존합니다. 반복되는 접두사의 캐시 적중률도 향상됩니다.

geminiTextInteractions 어댑터는 client.interactions.create를 통해 요청을 전달하고, RUN_FINISHED 직전에 발생하는 AG-UI CUSTOM 이벤트(name: 'gemini.interactionId')로 서버가 할당한 상호작용 ID를 노출하므로 턴을 연결할 수 있습니다.

⚠️ 실험적 기능입니다. Google은 Interactions API를 베타로 표시하며 정식 출시될 때까지 호환성이 깨지는 변경이 발생할 수 있다고 명시합니다. 이 어댑터는 @tanstack/ai-gemini/experimental 하위 경로에서 내보내므로 편집기와 번들에서도 실험적 상태가 유지됩니다. 텍스트 출력, 함수 도구, 기본 제공 도구 google_search, code_execution, url_context, file_search, computer_use를 지원합니다. 이 어댑터에서는 google_search_retrieval, google_maps, mcp_server가 여전히 예외를 발생시키므로 해당 도구에는 geminiText()를 사용하거나 후속 작업을 기다립니다.

기본 사용법​

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

// Turn 1: introduce yourself, capture the interaction id.
let interactionId: string | undefined;

for await (const chunk of chat({
  adapter: geminiTextInteractions("gemini-3.5-flash"),
  messages: [{ role: "user", content: "Hi, my name is Amir." }],
})) {
  if (
    chunk.type === "CUSTOM" &&
    chunk.name === "gemini.interactionId" &&
    chunk.value &&
    typeof chunk.value === "object" &&
    "interactionId" in chunk.value
  ) {
    interactionId = String(chunk.value.interactionId);
  }
}

// Turn 2: only send the new turn's content — the server has the history.
for await (const chunk of chat({
  adapter: geminiTextInteractions("gemini-3.5-flash"),
  messages: [{ role: "user", content: "What is my name?" }],
  modelOptions: {
    previous_interaction_id: interactionId,
  },
})) {
  // ...stream "Your name is Amir." back to the client.
}

useChat 연결(React)​

Interactions API 는 상태 기반이며 previous_interaction_id 없이 다중 턴 히스토리를 받아들이지 않습니다 — 새로운 상호작용에 채팅 클라이언트가 [user, assistant, user] 를 보내면 어댑터가 cannot send prior conversation history on a fresh interaction 를 던집니다. useChat 을 작동시키려면 서버 할당 id 를 영속화하고 다음 턴에 다시 보내세요:

서버 라우트(예: TanStack Start 핸들러):

import {
  chat,
  chatParamsFromRequestBody,
  toServerSentEventsResponse,
} from "@tanstack/ai";
import { geminiTextInteractions } from "@tanstack/ai-gemini/experimental";

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

  // The client sends body.previousInteractionId; AG-UI maps `body` into
  // `forwardedProps` on the wire.
  const previousInteractionId =
    typeof params.forwardedProps.previousInteractionId === "string"
      ? params.forwardedProps.previousInteractionId
      : undefined;

  const stream = chat({
    adapter: geminiTextInteractions("gemini-3.5-flash"),
    messages: params.messages,
    modelOptions: {
      previous_interaction_id: previousInteractionId,
      store: true, // required for chaining on the next turn
    },
  });

  return toServerSentEventsResponse(stream);
}

React 클라이언트:

import { useEffect, useMemo, useState } from "react";
import { fetchServerSentEvents, useChat } from "@tanstack/ai-react";

function GeminiChat() {
  const [interactionId, setInteractionId] = useState<string | undefined>();

  const body = useMemo(
    () => (interactionId ? { previousInteractionId: interactionId } : {}),
    [interactionId],
  );

  const { messages, setMessages, sendMessage } = useChat({
    connection: fetchServerSentEvents("/api/chat"),
    body,
    onCustomEvent: (eventType, data) => {
      if (
        eventType === "gemini.interactionId" &&
        typeof data === "object" &&
        data !== null &&
        "interactionId" in data
      ) {
        setInteractionId(String(data.interactionId));
      }
    },
  });

  // Switching provider/model resets the server-side chain — drop the id
  // AND the local message history together, otherwise the next turn
  // ships multi-turn messages with no previous_interaction_id and the
  // adapter errors out.
  const [provider, setProvider] = useState("gemini-interactions");
  useEffect(() => {
    setInteractionId(undefined);
    setMessages([]);
  }, [provider]);

  // ...render messages, call sendMessage(input)
}

전체 작동 예제는 examples/ts-react-chat에 있습니다. 클라이언트는 src/routes/index.tsx, 라우트는 src/routes/api.tanchat.ts를 참조합니다.

geminiText와의 차이​

항목geminiTextgeminiTextInteractions
기본 엔드포인트models:generateContentinteractions:create
대화 상태상태 비저장 — 매 턴 전체 기록 전송상태 저장 — 서버가 previous_interaction_id로 기록 보존
프로바이더 옵션 형태camelCase (stopSequences, responseModalities, safetySettings)snake_case (generation_config, response_modalities, previous_interaction_id)
기본 제공 도구google_search, code_execution, url_context, file_search, google_maps, google_search_retrieval, computer_usegoogle_search, code_execution, url_context, file_search, computer_use(처음 네 도구만 CUSTOM 이벤트 활동을 스트리밍하며 computer_use는 요청에서 허용되지만 현재 델타별 이벤트를 발생시키지 않음)
안정성GA실험적 기능(Google 베타)

프로바이더 옵션​

어댑터는 modelOptions 에서 Interactions 전용 옵션을 노출합니다:

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

const stream = chat({
  adapter: geminiTextInteractions("gemini-3.5-flash"),
  messages: [{ role: "user", content: "Hello!" }],
  modelOptions: {
    // Stateful chaining — passed only on turn 2+.
    previous_interaction_id: "int_abc123",

    // Persist the interaction server-side (default true). Must be true for
    // previous_interaction_id to work on the *next* turn.
    store: true,

    // Per-request system instruction (interaction-scoped — re-specify each turn).
    system_instruction: "You are a helpful assistant.",

    // snake_case generation config distinct from geminiText's camelCase one.
    generation_config: {
      thinking_level: "low",
      thinking_summaries: "auto",
      stop_sequences: ["<done>"],
    },

    response_modalities: ["text"],
  },
});

상호작용 ID 읽기​

서버의 상호작용 ID는 AG-UI CUSTOM 이벤트로 전달되며, 이 이벤트는 RUN_FINISHED 직전에 발생합니다.

for await (const chunk of stream) {
  if (
    chunk.type === "CUSTOM" &&
    chunk.name === "gemini.interactionId" &&
    typeof chunk.value === "object" &&
    chunk.value !== null &&
    "interactionId" in chunk.value
  ) {
    const id = String(chunk.value.interactionId);
    // Persist `id` wherever you store per-user conversation pointers —
    // pass it back on the next turn as `previous_interaction_id`.
  }
}

주의 사항​

  • 여러 턴의 기록에는 previous_interaction_id가 필요합니다. Interactions API에는 상태 비저장 재생 경로가 없으므로 previous_interaction_id 없이 messages에 둘 이상의 메시지를 보내면 예외가 발생합니다. 로컬 기록을 유지하는 채팅 UI는 서버가 할당한 ID를 캡처하고 연결해야 합니다(useChat 연결 참조). 프로바이더 또는 모델을 전환할 때는 로컬 메시지 버퍼도 지웁니다.
  • 도구, system_instruction, generation_config는 상호작용 범위에 속합니다. Google 문서에 따르면 이러한 값은 previous_interaction_id를 통해 이전 상호작용에서 상속되지 않으므로 필요한 각 턴에 다시 전달합니다.
  • store: false는 previous_interaction_id(회수할 상태가 없음) 및 background: true와 호환되지 않습니다.
  • 보존 기간(이 문서 작성 시점): 유료 등급은 55일, 무료 등급은 1일입니다. 현재 보존 정책은 Google Interactions API 문서를 참조합니다.
  • 범위 내 기본 제공 도구(google_search, code_execution, url_context, file_search, computer_use)는 요청 도구로 연결됩니다. 검색/실행 도구 네 개의 델타별 활동은 AG-UI CUSTOM 이벤트(gemini.googleSearchCall / gemini.googleSearchResult, 그리고 이에 대응하는 codeExecutionCall/Result, urlContextCall/Result, fileSearchCall/Result)로 원시 Interactions 델타를 담아 스트리밍됩니다. computer_use는 요청에서 허용되지만 현재 델타별 CUSTOM 이벤트를 발생시키지 않습니다. 함수 도구의 TOOL_CALL_* 이벤트는 변경되지 않으며 기본 제공 도구만 실행된 경우 finishReason은 stop으로 유지됩니다.
  • google_search_retrieval, google_maps, mcp_server는 이 어댑터에서 여전히 대상 지정 오류를 발생시킵니다. 처음 두 도구에는 geminiText()를 사용하고, mcp_server는 전용 후속 작업을 기다립니다.
  • 아직 Interactions를 통한 이미지 및 오디오 출력은 이 어댑터로 전달되지 않으며 텍스트만 지원합니다. 현재는 텍스트가 아닌 생성을 위해 geminiImage / geminiSpeech를 사용합니다.

모델 옵션​

Gemini는 다양한 모델별 옵션을 지원합니다. 샘플링 매개변수인 temperature, topP, maxOutputTokens도 chat()의 최상위 속성이 아니라 여기에 지정합니다.

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

const stream = chat({
  adapter: geminiText("gemini-3.1-pro-preview"),
  messages: [{ role: "user", content: "Hello!" }],
  modelOptions: {
    maxOutputTokens: 2048,
    temperature: 0.7,
    topP: 0.9,
    topK: 40,
    stopSequences: ["END"],
  },
});

이전에 chat()의 최상위에 temperature / topP / maxTokens를 전달했다면 샘플링 옵션을 modelOptions로 이동을 참조합니다.

사고​

지원하는 모델에서 사고 기능을 활성화합니다.

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

구조화된 출력​

구조화된 출력 형식을 구성합니다.

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

요약​

긴 텍스트 콘텐츠를 요약합니다.

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

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

console.log(result.summary);

임베딩​

gemini-embedding-001을 사용해 임베딩 벡터를 생성합니다.

import { embed } from "@tanstack/ai";
import { geminiEmbedding } from "@tanstack/ai-gemini";

const result = await embed({
  adapter: geminiEmbedding("gemini-embedding-001"),
  input: "a red guitar",
  dimensions: 1536,
  modelOptions: {
    taskType: "RETRIEVAL_DOCUMENT",
  },
});

console.log(result.embeddings[0]?.vector);

Gemini API의 임베딩 엔드포인트는 토큰 사용량을 보고하지 않으므로 result.usage가 없습니다. Vertex 전용 멀티모달 임베딩 모델 (multimodalembedding@001)은 이 어댑터에서 지원되지 않습니다.

전체 API는 임베딩 가이드를 참조합니다.

이미지 생성​

Gemini 어댑터는 두 가지 이미지 생성을 지원합니다.

  • Gemini 네이티브 이미지 모델(NanoBanana) — gemini-3.1-flash-image와 같은 모델에서 generateContent API를 사용합니다. 화면 비율 제어와 해상도 단계(512, 1K, 2K, 4K)를 지원하며, 허용되는 비율과 단계는 모델마다 다르고 컴파일 시 적용됩니다.
  • Imagen 모델 — imagen-4.0-generate-001과 같은 모델에서 generateImages API를 사용합니다. WIDTHxHEIGHT 크기를 사용하는 전용 이미지 생성 모델입니다.

모델이 GEMINI_NATIVE_IMAGE_MODELS에 포함되어 있으면 어댑터는 generateContent로 요청을 전달합니다. Imagen 모델과 이 패키지가 알 수 없는 모든 ID에는 generateImages를 사용합니다. 목록 또는 isGeminiNativeImageModel을 @tanstack/ai-gemini에서 가져옵니다.

예제: Gemini 네이티브 이미지 생성(NanoBanana)​

미디어 생성 예제 앱 에서:

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

const result = await generateImage({
  adapter: geminiImage("gemini-3.1-flash-image"),
  prompt: "A futuristic cityscape at sunset",
  numberOfImages: 1,
  size: "16:9_4K",
});

console.log(result.images);

예제: Imagen​

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

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

console.log(result.images);

이미지 크기 옵션​

Gemini 네이티브 모델(NanoBanana)​

Gemini 네이티브 이미지 모델은 화면 비율과 해상도 단계를 결합한 템플릿 리터럴 크기 형식을 사용합니다.

// Format: "aspectRatio_resolution"
size: "16:9_4K"
size: "1:1_2K"
size: "9:16_1K"

허용되는 집합은 모델마다 다르며 각 모델의 size는 컴파일 시 해당 집합으로 제한됩니다.

모델Aspect ratiosResolutions
gemini-3.1-flash-image1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1512, 1K, 2K, 4K
gemini-3.1-flash-lite-image위와 동일한 14개(참고 참조)1K만
gemini-3-pro-image1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:91K, 2K, 4K
gemini-2.5-flash-image위와 동일한 10개없음 — 비율만 전달합니다(예: size: "16:9")

K는 대소문자를 구분하며(1k는 API에서 거부됨), 가장 작은 단계의 토큰은 512(512px 또는 0.5K가 아님)입니다. 9:21은 Vertex/Cloud 전용이므로 여기서는 허용되지 않습니다. Google은 gemini-2.5-flash-image에 대해 image_size를 문서화하지 않았으므로 이 모델은 화면 비율만 받고 어댑터는 imageSize를 보내지 않습니다.

gemini-3.1-flash-lite-image 참고. 이 모델의 네 가지 극단 배너 비율(1:4, 4:1, 1:8, 8:1)은 부분적으로 추론한 값입니다. 다른 세 모델과 달리 Flash Lite에는 Google Gemini API 가이드의 모델별 비율 표가 없습니다. 14개 값은 Cloud 모델 페이지의 명시적 열거와 가이드의 "14개 화면 비율의 이산 집합"이라는 설명을 바탕으로 합니다. 이 모델에 대한 Gemini API의 유일한 열거는 "새 화면 비율"이라는 제목의 10개 항목 목록이며, 이를 전체 목록이 아닌 변경 사항 목록으로 해석했습니다. 실제로 API가 네 비율을 거부하면 이 모델에서는 표준 비율 10개를 우선 사용합니다.

Imagen 모델​

Imagen 모델은 내부적으로 화면 비율에 매핑되는 WIDTHxHEIGHT 형식을 사용합니다.

크기纵横비
1024x10241:1
1920x108016:9
1080x19209:16

또는 모델 옵션에서 화면 비율을 직접 지정할 수 있습니다.

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

const result = await generateImage({
  adapter: geminiImage("imagen-4.0-generate-001"),
  prompt: "A landscape photo",
  modelOptions: {
    aspectRatio: "16:9",
  },
});

이미지 모델 옵션​

두 모델군이 서로 다른 API를 사용하므로 modelOptions의 타입은 모델군별로 지정됩니다.

Imagen 모델 (generateImages) 은 GenerateImagesConfig 필드를 사용합니다:

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

const result = await generateImage({
  adapter: geminiImage("imagen-4.0-generate-001"),
  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
  },
});

Gemini 네이티브 모델 (generateContent) 은 seed, safetySettings, thinkingConfig, imageConfig, 및 systemInstruction를 사용합니다. imageConfig 은 Gemini Developer API 에서 aspectRatio 및 imageSize 만을 허용합니다.

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

const result = await generateImage({
  adapter: geminiImage("gemini-3.1-flash-image"),
  prompt: "...",
  size: "16:9_4K",
  modelOptions: {
    thinkingConfig: { thinkingBudget: 512 },
    // Merged over the imageConfig derived from `size`, per field.
    imageConfig: { imageSize: "2K" },
  },
});

전체 네이티브 옵션 목록은 이미지 생성을 참조합니다.

텍스트 음성 변환(실험적)​

참고: Gemini TTS는 실험적 기능이며 전체 기능을 사용하려면 Live API가 필요할 수 있습니다.

텍스트에서 음성 생성:

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

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

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

환경 변수​

환경 변수에 API 키를 설정합니다:

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

API 키 가져오기​

  1. Google AI Studio로 이동합니다.
  2. 새 API 키를 생성합니다.
  3. 환경 변수에 추가합니다.

Gemini 네이티브 이미지 모델 (NanoBanana)​

이 모델은 generateContent API를 사용하며 모델별 해상도 단계를 지원합니다.

모델설명
gemini-3.1-flash-imageNano Banana 2 — 최신이자 가장 빠른 Gemini 네이티브 이미지 생성(512/1K/2K/4K)
gemini-3.1-flash-lite-imageNano Banana 2 Lite — 초저지연 저비용 이미지 생성(1K만)
gemini-3-pro-imageNano Banana Pro — 고품질 Gemini 네이티브 이미지 생성(1K/2K/4K)
gemini-2.5-flash-imageNano Banana — 레거시이며 2026-10-02에 종료됩니다. 화면 비율만 받습니다

gemini-3.1-flash-image-preview 및 gemini-3-pro-image-preview ID는 2026-06-25에 종료되었습니다. 기존 코드가 컴파일되도록 타입 유니온에는 지원 중단 예정 별칭으로 남아 있지만 호출은 실패하므로 위의 GA ID를 사용합니다.

Imagen 모델​

이 모델들은 전용 generateImages API 를 사용합니다.

모델설명
imagen-4.0-ultra-generate-001최상의 품질의 Imagen 이미지 생성
imagen-4.0-generate-001고품질 Imagen 이미지 생성
imagen-4.0-fast-generate-001빠른 Imagen 이미지 생성

API 레퍼런스​

모든 팩토리 쌍은 동일한 형태를 따릅니다. 짧은 팩토리(geminiText, geminiImage, …)는 환경에서 GEMINI_API_KEY(또는 GOOGLE_API_KEY)를 읽고, create* 변형은 API 키를 명시적으로 받습니다. 두 함수 모두 첫 번째 인수로 model을 받습니다.

geminiText(model, config?) / createGeminiChat(model, apiKey, config?)​

Gemini 텍스트/채팅 어댑터를 생성합니다.

Parameters:

  • model - Gemini 채팅 모델 ID (예: "gemini-3.1-pro-preview")
  • config?.baseURL - 커스텀 기본 URL (선택 사항)

geminiTextInteractions(model, config?) / createGeminiTextInteractions(model, apiKey, config?) (실험적)​

Gemini Interactions API 텍스트 어댑터를 생성합니다. previous_interaction_id를 통해 상태 저장 대화 패턴을 지원합니다. @tanstack/ai-gemini/experimental에서 내보냅니다.

Parameters:

  • model - Gemini 채팅 모델 ID (예: "gemini-3.5-flash")
  • config?.baseURL - 커스텀 기본 URL (선택 사항)

geminiSummarize(model, config?) / createGeminiSummarize(model, apiKey, config?)​

Gemini 요약 어댑터를 생성합니다.

geminiImage(model, config?) / createGeminiImage(model, apiKey, config?)​

Gemini 이미지 어댑터를 생성합니다. GEMINI_NATIVE_IMAGE_MODELS의 모델은 generateContent를 사용합니다. Imagen 모델과 알 수 없는 모든 ID는 generateImages를 사용합니다.

geminiSpeech(model, config?) / createGeminiSpeech(model, apiKey, config?)​

Gemini 텍스트-음성 어댑터를 생성합니다. 실험적입니다.

geminiAudio(model, config?) / createGeminiAudio(model, apiKey, config?)​

Gemini Lyria 음악 생성 어댑터를 생성합니다. 실험적입니다.

다음 단계​

프로바이더 도구​

Google Gemini는 사용자가 정의한 함수 호출 외에도 여러 네이티브 도구를 제공합니다. @tanstack/ai-gemini/tools에서 가져와 chat({ tools: [...] })에 전달합니다.

전체 개념, 비교 행렬, 타입 제한 세부 정보는 프로바이더 도구를 참조합니다.

codeExecutionTool​

Gemini가 샌드박스 환경에서 Python 코드를 실행하고 결과를 인라인으로 반환하도록 합니다. 인수를 받지 않으며 코드 실행을 활성화하려면 tools 배열에 포함합니다.

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

const stream = chat({
  adapter: geminiText("gemini-3.1-pro-preview"),
  messages: [{ role: "user", content: "Calculate the first 10 Fibonacci numbers" }],
  tools: [codeExecutionTool()],
});

지원 모델: Gemini 1.5 Pro, Gemini 2.x, Gemini 2.5 이상입니다. 프로바이더 도구를 참조합니다.

fileSearchTool​

Gemini File API에 업로드된 파일을 검색합니다. 검색 범위를 지정하려면 코퍼스와 파일 ID가 포함된 FileSearch 구성 객체를 전달합니다.

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

const stream = chat({
  adapter: geminiText("gemini-3.1-pro-preview"),
  messages: [{ role: "user", content: "Find the quarterly revenue figures" }],
  tools: [
    fileSearchTool({
      fileSearchStoreNames: ["fileSearchStores/my-file-search-store-123"],
    }),
  ],
});

지원 모델: Gemini 2.x 이상입니다. 프로바이더 도구를 참조합니다.

googleSearchTool​

Gemini가 Google Search를 조회하고 근거가 있는 검색 결과를 응답에 포함하도록 합니다. 선택적 GoogleSearch 구성을 전달하거나 인수 없이 호출해 기본값을 사용합니다.

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

const stream = chat({
  adapter: geminiText("gemini-3.1-pro-preview"),
  messages: [{ role: "user", content: "What's the weather in Tokyo right now?" }],
  tools: [googleSearchTool()],
});

지원 모델: Gemini 1.5 Pro, Gemini 2.x, Gemini 2.5입니다. 프로바이더 도구를 참조합니다.

googleSearchRetrievalTool​

Google Search의 검색 증강 변형으로, 구성 가능한 동적 검색 모드를 사용해 웹에서 순위가 매겨진 문단을 반환합니다. 선택적 GoogleSearchRetrieval 구성을 전달합니다.

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

const stream = chat({
  adapter: geminiText("gemini-3.1-pro-preview"),
  messages: [{ role: "user", content: "Explain the latest JavaScript proposals" }],
  tools: [
    googleSearchRetrievalTool({
      dynamicRetrievalConfig: { mode: "MODE_DYNAMIC", dynamicThreshold: 0.7 },
    }),
  ],
});

지원 모델: Gemini 1.5 Pro 이상입니다. 프로바이더 도구를 참조합니다.

googleMapsTool​

Gemini를 Google Maps API에 연결해 길찾기, 장소 검색, 지오코딩과 같은 위치 기반 질의를 처리합니다. 선택적 GoogleMaps 구성을 전달하거나 인수 없이 호출합니다.

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

const stream = chat({
  adapter: geminiText("gemini-2.5-pro"),
  messages: [{ role: "user", content: "Find coffee shops near Union Square, SF" }],
  tools: [googleMapsTool()],
});

지원 모델: Gemini 2.5 이상입니다. 프로바이더 도구를 참조합니다.

urlContextTool​

대화에서 언급된 URL의 콘텐츠를 가져와 포함하므로 Gemini가 실시간 웹 페이지를 바탕으로 추론할 수 있습니다. 인수를 받지 않습니다.

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

const stream = chat({
  adapter: geminiText("gemini-3.1-pro-preview"),
  messages: [{ role: "user", content: "Summarise https://example.com/article" }],
  tools: [urlContextTool()],
});

지원 모델: Gemini 2.x 이상입니다. 프로바이더 도구를 참조합니다.

computerUseTool​

Gemini가 스크린샷으로 가상 데스크톱을 관찰하고 미리 정의된 컴퓨터 사용 함수로 상호작용하도록 합니다. environment를 제공하고, 필요하면 excludedPredefinedFunctions로 호출 가능한 함수를 제한합니다.

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

const stream = chat({
  adapter: geminiText("gemini-3.1-pro-preview"),
  messages: [{ role: "user", content: "Navigate to example.com in the browser" }],
  tools: [
    computerUseTool({
      environment: "browser",
    }),
  ],
});

지원 모델: Gemini 2.5 이상입니다. 프로바이더 도구를 참조합니다.