googleapis/js-genai

Google Gen AI SDK for TypeScript & JavaScript

简介 – 由 Google 官方维护的 npm 包 (@google/genai)，封装了 Gemini 2.0+ API（包含公共的 Gemini Developer API 和 Gemini Enterprise Agent Platform）。它为 JavaScript/TypeScript 代码提供了一层轻量且符合惯用的接口，用于：

文本、图像、音频、视频生成
流式响应
函数 (工具) 调用 / 自动函数调用
有状态聊天会话
文件上传、实时会话处理，以及较新的 Interactions 统一 API

适用对象 – 希望在 Node.js 或浏览器中调用 Gemini 模型，且不想编写原始 HTTP 请求的前端或后端开发者。

核心概念

概念	功能
`GoogleGenAI` 类	入口点；持有验证配置（API 密钥或企业凭据）并创建子模块 (`models`, `chats`, `caches`, `files`, `live`, `interactions`)。
`ai.models.generateContent`	文本（或多模态）生成的单次请求。
`generateContentStream`	当模型流式输出时，产生部分块的异步迭代器。
`ai.chats`	创建一个本地 `Chat` 对象，保存对话历史并简化多轮交互。
`ai.caches`	管理服务器端提示词缓存，以降低重复长前缀的 Token 成本。
`ai.files`	上传大型文件（图像、音频、PDF 等）并在提示词中引用它们。
`ai.live`	启动实时会话，可接收实时音频/视频并返回实时输出。
`ai.interactions`	一个更高阶的 API，统一了模型调用、聊天状态、工具编排与长时间运行的任务（例如深度研究 Agent）。
函数调用 / 工具	声明 JSON-schema 函数，让 Gemini 调用它们，然后将结果回传。
自动续写	SDK 会自动跟随续写 Token，除非您将其禁用。

安装

npm install @google/genai

快速开始 (API-key)

import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const resp = await ai.models.generateContent({
  model: 'gemini-flash-latest',
  contents: 'Why is the sky blue?'
});
console.log(resp.text);

相同的构造函数可在浏览器中使用，但 README 警告您应将密钥保留在服务器端。

企业级 Agent 初始化

const ai = new GoogleGenAI({
  enterprise: true,
  project: 'my-project',
  location: 'us-central1'
});

也可以使用环境变量 (GOOGLE_GENAI_USE_ENTERPRISE, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION)。

流式示例

for await (const chunk of ai.models.generateContentStream({
  model: 'gemini-flash-latest',
  contents: 'Write a 100-word poem.'
})) {
  console.log(chunk.text);
}

函数调用 (工具) 示例

const controlLight: FunctionDeclaration = {
  name: 'controlLight',
  parametersJsonSchema: {
    type: 'object',
    properties: {
      brightness: {type: 'number'},
      colorTemperature: {type: 'string'}
    },
    required: ['brightness', 'colorTemperature']
  }
};

const resp = await ai.models.generateContent({
  model: 'gemini-flash-latest',
  contents: 'Dim the lights so the room feels cozy.',
  config: {
    toolConfig: {functionCallingConfig: {mode: FunctionCallingConfigMode.ANY, allowedFunctionNames: ['controlLight']}},
    tools: [{functionDeclarations: [controlLight]}]
  }
});
console.log(resp.functionCalls);

SDK 会返回一个 functionCalls 数组，您可以执行它并通过后续请求（或通过 ai.chats）将结果回传。

Interactions API (有状态，Agent 风格)

// 第一轮
const i1 = await ai.interactions.create({model: 'gemini-flash-latest', input: 'Hi, I am Amir.'});
// 第二轮 – 保留对话上下文
const i2 = await ai.interactions.create({
  model: 'gemini-flash-latest',
  input: 'What is my name?',
  previous_interaction_id: i1.id
});

支持深度研究 Agent、多模态输入、内置工具（Google 搜索、代码执行）以及自定义函数工具。

错误处理 – 所有 API 错误都会以 ApiError 形式呈现，包含 name、message 与 HTTP status 字段。

版本与兼容性说明

目前的 SDK 适用于 Node 20+。从 3.0.0 版本开始将需要 Node 22+。如果您需要旧版运行环境，请锁定在 <3.0.0。
即将到来的主要版本更新将会把自动函数调用从 Models.generateContent 移至 Chats 模块。
部分字段即将被弃用 (LiveConnectConfig.generation_config, prompt/text/image 在 generate_videos 中等)。

深入了解

完整文档: https://googleapis.github.io/js-genai/
示例项目: https://github.com/googleapis/js-genai/tree/main/sdk-samples
代码生成指南: 仓库中的 codegen_instructions.md。

总结 – 此仓库是一个真正的生产级 SDK，让 JavaScript/TypeScript 开发者能将 Google 的 Gemini 模型（包含企业级 Agent）集成到应用中，并支持流式传输、聊天状态、工具调用与多模态数据。

googleapis/js-genai

Google Gen AI SDK for TypeScript & JavaScript

相关