AiHubMix Documentation Hub

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

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

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

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

const ai = new GoogleGenAI({
  apiKey: "sk-***", // Replace with your AIHubMix API Key
  httpOptions: {
    baseUrl: "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.

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, ... }

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"`

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"));
    }
  }
}

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

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

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.

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

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.

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);

Query and Delete

// 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 });

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

​Overview

​Quick Start

​Installation

​Initialize the Client

​Interactions API

​Text Generation

​Native Image Generation

​Streaming

​Embeddings

​embedContent

​Batch Embeddings

​Available Models and Parameters

​Context Caching (Explicit Caching)

​Create CachedContent

​Reference Cache in generateContent

​Query and Delete

​Supported Capabilities Matrix

​FAQ

Overview

Quick Start

Installation

Initialize the Client

Interactions API

Text Generation

Native Image Generation

Streaming

Embeddings

embedContent

Batch Embeddings

Available Models and Parameters

Context Caching (Explicit Caching)

Create CachedContent

Reference Cache in generateContent

Query and Delete

Supported Capabilities Matrix

FAQ