Gemini Native SDK Integration

Integrate with AIHubMix via the @google/genai SDK to access all native Gemini API capabilities including Interactions, Embeddings, and Context Caching

Overview

Google provides two official SDKs — @google/genai (JavaScript / TypeScript) and google-genai (Python) — covering all Gemini API endpoints. By pointing the baseUrl to the AIHubMix gateway and replacing the API Key with your platform key, you can call native capabilities such as Interactions, Embeddings, and Context Caching that are not covered by the OpenAI-compatible layer, without modifying any business code.

Quick Start

Installation

JavaScript / TypeScript

npm install @google/genai
# Requires >= 2.0.0; installing latest is recommended

pip install -U google-genai
# Requires >= 2.0.0

The Interactions API requires @google/genai >= 2.0.0 or google-genai >= 2.0.0. Requests from older SDK versions will be rejected by Google’s backend (legacy Interactions schema no longer supported).

Initialize the Client

JavaScript

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

const ai = new GoogleGenAI({
  apiKey: "sk-***", // Replace with your AIHubMix API Key
  httpOptions: {
    baseUrl: "https://aihubmix.com/gemini",
  },
});

from google import genai

client = genai.Client(
    api_key="sk-***",  # Replace with your AIHubMix API Key
    http_options={"base_url": "https://aihubmix.com/gemini"},
)

The baseUrl is always https://aihubmix.com/gemini, which differs from the OpenAI-compatible endpoint https://aihubmix.com/v1.

---

Interactions API

Interactions is Gemini’s next-generation inference interface that returns structured Interaction objects, supporting text generation, native image generation (Nano Banana), and multi-step reasoning. Synchronous mode (interactions.create()) is currently supported; asynchronous mode (Background Interactions: get / cancel / delete) is coming soon.

Text Generation

Call interactions.create() to initiate inference. The returned Interaction object provides an output_text convenience property for directly accessing the model’s last text output.

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)

Native Image Generation

Configure the output modality to image via response_format. The returned Interaction object provides an output_image convenience property whose data field contains Base64-encoded image data.

• Recommended model: gemini-3.1-flash-image (Nano Banana 2, general-purpose image generation model).
• response_modalities values must be lowercase ['text', 'image']; uppercase is the generateContent API convention and will return 400 in the Interactions API.
• Do not pass delivery: 'inline' (400 Image delivery mode is not supported) — the Interactions API returns image data inline by default.

response_format parameters:

Field	Description	Possible values
type	Output type	"image"
aspect_ratio	Aspect ratio	"1:1" "3:4" "4:3" "9:16" "16:9"
image_size	Output resolution	"1K" "2K" "4K"
mime_type	Image format	"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" },
});

// Method 1: output_image convenience property (gets the last generated image)
if (interaction.output_image?.data) {
  fs.writeFileSync("output.png", Buffer.from(interaction.output_image.data, "base64"));
}

// Method 2: iterate over steps, suitable for multi-step mixed output
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 convenience property
if interaction.output_image:
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(interaction.output_image.data))

Streaming

Pass stream: true to enable Server-Sent Events (SSE) streaming. Events arrive in the following order:

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

Incremental text is obtained via event.delta.text, and the event type field is 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

Obtain vector representations (embeddings) of text or multimodal content via the embedContent endpoint.

For the OpenAI-compatible /v1/embeddings endpoint, see Embeddings.

embedContent

JavaScript

const response = await ai.models.embedContent({
  model: "gemini-embedding-2-preview",
  contents: "What is the meaning of life?",
  config: {
    outputDimensionality: 768, // Optional: specify output dimensions (128–3072), default 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,  # Optional: specify output dimensions (128–3072), default 3072
    ),
)

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

Batch Embeddings

Pass a Content array to the contents parameter of embedContent to obtain embeddings for multiple texts in a single call:

JavaScript

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

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

Available Models and Parameters

Model	Max Input Tokens	Default Output Dimensions	Input Modality	Notes
gemini-embedding-2-preview	8,192	3,072 (768 recommended)	Text, image, video, audio, PDF	Latest multimodal embedding model, supports outputDimensionality
gemini-embedding-001	2,048	3,072	Text only	Previous-generation text embedding model, supports taskType

gemini-embedding-001 supports specifying the embedding purpose via config.taskType to optimize vector quality for specific downstream tasks:

taskType	Purpose
SEMANTIC_SIMILARITY	Semantic similarity computation
RETRIEVAL_DOCUMENT	Document indexing (retrieval target)
RETRIEVAL_QUERY	Search query (retrieval source)
CLASSIFICATION	Text classification
CLUSTERING	Text clustering

gemini-embedding-2-preview does not support the taskType parameter. Instead, specify the task type via a prefix in the prompt (e.g., search_query: ... or search_document: ...).

---

Context Caching (Explicit Caching)

Explicit Caching allows developers to manually create, query, reference, and delete CachedContent objects, suitable for scenarios that require reusing the same long context across multiple requests. Unlike implicit caching, explicit caching lets the application manage the lifecycle.

Explicit caching is only available for the generateContent API. The Interactions API only supports implicit caching.

Models without configured storage pricing will have cache creation requests blocked by the gateway (context caching is not available for model) to prevent storage cost leakage. Mainstream models (gemini-2.5-flash, gemini-2.5-pro, etc.) are already configured.

Create CachedContent

Create a cache via caches.create(). The ttl (Time-To-Live) controls the cache validity period; the cache is automatically cleared when it expires.

JavaScript

const longDocument = "Long text content to be referenced repeatedly...".repeat(500);

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

console.log("CachedContent name:", cache.name);
// Format: cachedContents/xxx

long_document = "Long text content to be referenced repeatedly..." * 500

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

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

Reference Cache in generateContent

Pass cache.name to the cachedContent (JS) or cached_content (Python) parameter to use the cache during inference. The number of cached tokens is reflected in 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}")

Query and Delete

JavaScript

// Query CachedContent metadata
const info = await ai.caches.get({ name: cache.name });
console.log("model:", info.model, "expireTime:", info.expireTime);

// Delete cache
await ai.caches.delete({ name: cache.name });

# Query CachedContent metadata
info = client.caches.get(name=cache.name)
print(f"model: {info.model}  expire_time: {info.expire_time}")

# Delete cache
client.caches.delete(name=cache.name)

---

Supported Capabilities Matrix

Capability	Status	Notes
generateContent	✅	Non-streaming + streaming
systemInstruction / generationConfig	✅	temperature, maxOutputTokens, etc.
Structured Output (responseSchema)	✅	JSON mode
Function Calling	✅	functionDeclarations tool declarations
thinkingConfig	✅	Chain-of-thought output
Multimodal input	✅	Image / audio / video / PDF via inlineData + Files API
Google Search Grounding	✅	Search-augmented generation
countTokens	✅	Token counting
Imagen (generateImages)	✅	Imagen 3 image generation
Veo (generateVideos)	✅	Video generation
TTS	✅	Text-to-speech output
Files API	✅	Large file upload and reference
Interactions API	✅	Next-gen inference interface (text + Nano Banana image generation)
Embeddings (embedContent)	✅	Native vector embeddings
Context Caching CRUD	✅	Explicit cache management
Live API (WebSocket)	❌	Not yet supported

---

FAQ

interactions.create() returns a legacy schema error

The SDK version is too old. @google/genai must be >= 2.0.0, and google-genai must be >= 2.0.0. Run npm install @google/genai@latest or pip install -U google-genai to upgrade to the latest version.

Model returns 404 Not Found

Some early model names (e.g., gemini-2.5-flash-image-preview) have been retired from the Interactions API. Use currently available model identifiers such as gemini-3.1-flash-image (Nano Banana 2). The generateContent API is not affected.

response_modalities returns 400 Bad Request

The Interactions API requires response_modalities values to be lowercase ("text", "image"). Uppercase "TEXT" / "IMAGE" is the generateContent API convention and is not accepted in the Interactions API.

Can I use vertexai: true?

No. The SDK’s vertexai: true mode requires GCP OAuth + project / location parameters, which are mutually exclusive with apiKey (the SDK throws Project/location and API key are mutually exclusive). When accessing through AIHubMix, use the Gemini Developer API form — the backend routes automatically.

Cache creation returns 'context caching is not available for model'

The gateway blocks caches.create() requests for models without configured storage pricing to prevent storage cost leakage. Mainstream models (gemini-2.5-flash, gemini-2.5-pro, etc.) are already configured; if you encounter this error, verify that the model supports explicit caching.

---

Last updated: 2026-07-07