> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```bash JavaScript / TypeScript theme={null}
  npm install @google/genai
  # Requires >= 2.0.0; installing latest is recommended
  ```

  ```bash Python theme={null}
  pip install -U google-genai
  # Requires >= 2.0.0
  ```
</CodeGroup>

<Warning>
  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`).
</Warning>

### Initialize the Client

<CodeGroup>
  ```js JavaScript theme={null}
  import { GoogleGenAI } from "@google/genai";

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

  ```python Python theme={null}
  from google import genai

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

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

***

## 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.

<CodeGroup>
  ```js JavaScript theme={null}
  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, ... }
  ```

  ```python Python theme={null}
  interaction = client.interactions.create(
      model="gemini-3.5-flash",
      input="Explain quantum computing in one sentence",
  )

  print(interaction.output_text)
  ```
</CodeGroup>

### 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.

<Tip>
  * 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.
</Tip>

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

<CodeGroup>
  ```js JavaScript theme={null}
  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"));
      }
    }
  }
  ```

  ```python Python theme={null}
  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))
  ```
</CodeGroup>

### 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`.

```js JavaScript theme={null}
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.

<Tip>
  For the OpenAI-compatible `/v1/embeddings` endpoint, see [Embeddings](/en/api/EBD).
</Tip>

### embedContent

<CodeGroup>
  ```js JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

### Batch Embeddings

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

```js JavaScript theme={null}
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                      |

<Note>
  `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: ...`).
</Note>

***

## 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](/en/api/Gemini-Guides#context-caching), explicit caching lets the application manage the lifecycle.

<Note>
  Explicit caching is only available for the `generateContent` API. The Interactions API only supports implicit caching.
</Note>

<Tip>
  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.
</Tip>

### 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.

<CodeGroup>
  ```js JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

### 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`.

<CodeGroup>
  ```js JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

### Query and Delete

<CodeGroup>
  ```js JavaScript theme={null}
  // 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 });
  ```

  ```python Python theme={null}
  # 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)
  ```
</CodeGroup>

***

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

Last updated: 2026-07-07