Gemini 原生 SDK 接入

通过 @google/genai SDK 接入 AIHubMix，调用 Interactions、Embeddings、Context Caching 等 Gemini API 全部原生能力

​

概述

Google 提供 @google/genai（JavaScript / TypeScript）和 google-genai（Python）两套官方 SDK，覆盖 Gemini API 的全部端点。将 baseUrl 指向 AIHubMix 网关并替换为平台 API Key，即可通过原生 SDK 调用 Interactions、Embeddings、Context Caching 等 OpenAI 兼容层未覆盖的能力，无需改动任何业务代码。

​

快速开始

​

安装

JavaScript / TypeScript

npm install @google/genai
# 要求 >= 2.0.0；推荐安装 latest

pip install -U google-genai
# 要求 >= 2.0.0

Interactions API 要求 @google/genai >= 2.0.0 或 google-genai >= 2.0.0。低版本 SDK 的请求会被 Google 后端拒绝（legacy Interactions schema no longer supported）。

​

初始化客户端

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: "sk-***", // 替换为你在 AIHubMix 生成的 API Key
  httpOptions: {
    baseUrl: "https://aihubmix.com/gemini",
  },
});

from google import genai

client = genai.Client(
    api_key="sk-***",  # 替换为你在 AIHubMix 生成的 API Key
    http_options={"base_url": "https://aihubmix.com/gemini"},
)

baseUrl 固定为 https://aihubmix.com/gemini，与 OpenAI 兼容端点 https://aihubmix.com/v1 不同。

---

​

Interactions API

Interactions 是 Gemini 新一代推理接口，返回结构化的 Interaction 对象，支持文本生成、原生图像生成（Nano Banana）及多步推理。目前已支持同步模式（interactions.create()）；异步模式（Background Interactions：get / cancel / delete）敬请期待。

​

文本生成

调用 interactions.create() 发起推理，返回的 Interaction 对象提供 output_text 便捷属性，直接获取模型最后一段文本输出。

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Explain quantum computing in one sentence",
});

console.log(interaction.output_text);
console.log(interaction.usage);
// { total_tokens, total_input_tokens, total_output_tokens, ... }

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Explain quantum computing in one sentence",
)

print(interaction.output_text)

​

原生图像生成

通过 response_format 配置输出模态为图像。返回的 Interaction 对象提供 output_image 便捷属性，其 data 字段为 Base64 编码的图像数据。

• 推荐模型 gemini-3.1-flash-image（Nano Banana 2，通用生图模型）。
• response_modalities 值必须为小写 ['text', 'image']；大写为 generateContent API 的写法，在 Interactions API 中会返回 400。
• 勿传 delivery: 'inline'（400 Image delivery mode is not supported），Interactions API 默认即以 inline 方式返回图像数据。

response_format 参数：

字段	说明	可选值
type	输出类型	"image"
aspect_ratio	宽高比	"1:1" "3:4" "4:3" "9:16" "16:9"
image_size	输出分辨率	"1K" "2K" "4K"
mime_type	图像格式	"image/png" "image/jpeg"

JavaScript

import fs from "node:fs";

const interaction = await ai.interactions.create({
  model: "gemini-3.1-flash-image",
  input: "A translucent banana-shaped glass lamp on a white desk, soft studio lighting.",
  response_modalities: ["text", "image"],
  response_format: { type: "image", aspect_ratio: "1:1", image_size: "1K" },
});

// 方式 1：output_image 便捷属性（取最后一张生成图像）
if (interaction.output_image?.data) {
  fs.writeFileSync("output.png", Buffer.from(interaction.output_image.data, "base64"));
}

// 方式 2：遍历 steps，适用于多步骤混合输出
for (const step of interaction.steps ?? []) {
  for (const block of step.content ?? []) {
    if (block.type === "image" && block.data) {
      fs.writeFileSync("output.png", Buffer.from(block.data, "base64"));
    }
  }
}

import base64

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="A translucent banana-shaped glass lamp on a white desk, soft studio lighting.",
    response_format={
        "type": "image",
        "aspect_ratio": "1:1",
        "image_size": "1K",
    },
)

# output_image 便捷属性
if interaction.output_image:
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(interaction.output_image.data))

​

流式输出

传入 stream: true 启用 Server-Sent Events（SSE）流式传输。事件按以下顺序到达：

interaction.created → status_update → step.start → step.delta → step.stop → interaction.completed

增量文本通过 event.delta.text 获取，事件类型字段为 event_type。

JavaScript

const stream = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Write a haiku about the moon",
  stream: true,
});

for await (const event of stream) {
  if (event.event_type === "step.delta" && event.delta?.type === "text") {
    process.stdout.write(event.delta.text);
  }
  if (event.event_type === "interaction.completed") {
    console.log("\nUsage:", JSON.stringify(event.interaction?.usage));
  }
}

---

​

Embeddings

通过 embedContent 端点获取文本或多模态内容的向量表示（embedding）。

如需 OpenAI 兼容的 /v1/embeddings 端点，请参阅 向量嵌入。

​

embedContent

JavaScript

const response = await ai.models.embedContent({
  model: "gemini-embedding-2-preview",
  contents: "What is the meaning of life?",
  config: {
    outputDimensionality: 768, // 可选：指定输出维度（128–3072），默认 3072
  },
});

console.log("dimensions:", response.embeddings[0].values.length); // 768

from google.genai import types

result = client.models.embed_content(
    model="gemini-embedding-2-preview",
    contents="What is the meaning of life?",
    config=types.EmbedContentConfig(
        output_dimensionality=768,  # 可选：指定输出维度（128–3072），默认 3072
    ),
)

print(f"dimensions: {len(result.embeddings[0].values)}")  # 768

​

批量获取 Embeddings

向 embedContent 的 contents 参数传入 Content 数组，即可一次调用获取多条文本的 embedding：

JavaScript

const response = await ai.models.embedContent({
  model: "gemini-embedding-2-preview",
  contents: [
    { parts: [{ text: "First paragraph of text" }] },
    { parts: [{ text: "Second paragraph of text" }] },
  ],
});

console.log("count:", response.embeddings.length); // 2
for (const emb of response.embeddings) {
  console.log("dimensions:", emb.values.length);
}

​

可用模型与参数

模型	输入 Token 上限	默认输出维度	输入模态	说明
gemini-embedding-2-preview	8,192	3,072（推荐 768）	文本、图像、视频、音频、PDF	最新多模态嵌入模型，支持 outputDimensionality
gemini-embedding-001	2,048	3,072	仅文本	上一代文本嵌入模型，支持 taskType

gemini-embedding-001 支持通过 config.taskType 指定嵌入用途，优化特定下游任务的向量质量：

taskType	用途
SEMANTIC_SIMILARITY	语义相似度计算
RETRIEVAL_DOCUMENT	文档索引（被检索侧）
RETRIEVAL_QUERY	搜索查询（检索侧）
CLASSIFICATION	文本分类
CLUSTERING	文本聚类

gemini-embedding-2-preview 不支持 taskType 参数，改为在 prompt 中通过前缀指定任务类型（如 search_query: ... 或 search_document: ...）。

---

​

Context Caching（显式缓存）

显式缓存（Explicit Caching）允许开发者手动创建、查询、引用和删除 CachedContent 对象，适用于需要在多次请求间复用同一段长上下文的场景。与隐式缓存不同，显式缓存由应用侧主动管理生命周期。

显式缓存仅适用于 generateContent API。Interactions API 仅支持隐式缓存。

未配置存储定价的模型会被网关拦截缓存创建请求（context caching is not available for model），以防止存储费用漏收。主流模型（gemini-2.5-flash、gemini-2.5-pro 等）均已配置。

​

创建 CachedContent

通过 caches.create() 创建缓存。ttl（Time-To-Live）控制缓存有效期，到期后自动清除。

JavaScript

const longDocument = "需要反复引用的长文本内容...".repeat(500);

const cache = await ai.caches.create({
  model: "gemini-3.5-flash",
  config: {
    contents: longDocument,
    ttl: "300s",
  },
});

console.log("CachedContent name:", cache.name);
// 格式：cachedContents/xxx

long_document = "需要反复引用的长文本内容..." * 500

cache = client.caches.create(
    model="gemini-3.5-flash",
    config={
        "contents": long_document,
        "ttl": "300s",
    },
)

print(f"CachedContent name: {cache.name}")

​

在 generateContent 中引用缓存

将 cache.name 传入 cachedContent（JS）或 cached_content（Python）参数，即可在推理时命中缓存。命中的 token 数会体现在 usageMetadata.cachedContentTokenCount 中。

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Please summarize the core points of the above document",
  config: { cachedContent: cache.name },
});

console.log(response.text);
console.log("cached tokens:", response.usageMetadata?.cachedContentTokenCount);

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Please summarize the core points of the above document",
    config={"cached_content": cache.name},
)

print(response.text)
print(f"cached tokens: {response.usage_metadata.cached_content_token_count}")

​

查询与删除

JavaScript

// 查询 CachedContent 元数据
const info = await ai.caches.get({ name: cache.name });
console.log("model:", info.model, "expireTime:", info.expireTime);

// 删除缓存
await ai.caches.delete({ name: cache.name });

# 查询 CachedContent 元数据
info = client.caches.get(name=cache.name)
print(f"model: {info.model}  expire_time: {info.expire_time}")

# 删除缓存
client.caches.delete(name=cache.name)

---

​

已支持能力矩阵

能力	状态	说明
generateContent	✅	非流式 + 流式
systemInstruction / generationConfig	✅	temperature、maxOutputTokens 等
Structured Output（responseSchema）	✅	JSON mode
Function Calling	✅	functionDeclarations 工具声明
thinkingConfig	✅	思维链输出
多模态输入	✅	图像 / 音频 / 视频 / PDF via inlineData + Files API
Google Search Grounding	✅	搜索增强
countTokens	✅	Token 计数
Imagen（generateImages）	✅	Imagen 3 图像生成
Veo（generateVideos）	✅	视频生成
TTS	✅	语音合成输出
Files API	✅	大文件上传与引用
Interactions API	✅	新一代推理接口（文本 + Nano Banana 生图）
Embeddings（embedContent）	✅	原生向量嵌入
Context Caching CRUD	✅	显式缓存管理
Live API（WebSocket）	❌	暂未支持

---

​

常见问题

调用 interactions.create() 报 legacy schema 错误

SDK 版本过低。@google/genai 须 >= 2.0.0，google-genai 须 >= 2.0.0。执行 npm install @google/genai@latest 或 pip install -U google-genai 升级至最新版本。

模型返回 404 Not Found

部分早期模型名称（如 gemini-2.5-flash-image-preview）在 Interactions API 上已下线。请使用当前可用的模型标识符，如 gemini-3.1-flash-image（Nano Banana 2）。generateContent API 不受影响。

response_modalities 报 400 Bad Request

Interactions API 的 response_modalities 值必须为小写（"text"、"image"）。大写 "TEXT" / "IMAGE" 是 generateContent API 的写法，在 Interactions API 中不被接受。

vertexai: true 是否可用？

不可用。SDK 的 vertexai: true 模式要求 GCP OAuth + project / location 参数，与 apiKey 互斥（SDK 抛出 Project/location and API key are mutually exclusive）。通过 AIHubMix 接入时使用 Gemini Developer API 形态即可，后端自动路由。

创建缓存报 context caching is not available for model

网关对未配置存储定价的模型会拦截 caches.create() 请求，以防止存储费用漏收。主流模型（gemini-2.5-flash、gemini-2.5-pro 等）均已配置；如遇此错误，请确认该模型是否支持显式缓存。

---

更新时间：2026-07-07