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

> Anbindung an AIHubMix ueber das @google/genai SDK fuer Interactions, Embeddings, Context Caching und alle nativen Gemini-API-Funktionen

## Ueberblick

Google bietet zwei offizielle SDKs: `@google/genai` (JavaScript / TypeScript) und `google-genai` (Python), die alle Gemini-API-Endpunkte abdecken. Indem Sie die `baseUrl` auf das AIHubMix-Gateway richten und Ihren Plattform-API-Key verwenden, koennen Sie ueber das native SDK Interactions, Embeddings, Context Caching und weitere Funktionen aufrufen, die von der OpenAI-kompatiblen Schicht nicht abgedeckt werden -- ohne jegliche Aenderungen an Ihrem Geschaeftscode.

## Schnellstart

### Installation

<CodeGroup>
  ```bash JavaScript / TypeScript theme={null}
  npm install @google/genai
  # Erfordert >= 2.0.0; empfohlen: latest
  ```

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

<Warning>
  Die Interactions API erfordert `@google/genai` **>= 2.0.0** oder `google-genai` **>= 2.0.0**. Anfragen mit aelteren SDK-Versionen werden vom Google-Backend abgelehnt (`legacy Interactions schema no longer supported`).
</Warning>

### Client initialisieren

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

  const ai = new GoogleGenAI({
    apiKey: "sk-***", // Ersetzen Sie dies durch Ihren bei AIHubMix generierten API Key
    httpOptions: {
      baseUrl: "https://aihubmix.com/gemini",
    },
  });
  ```

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

  client = genai.Client(
      api_key="sk-***",  # Ersetzen Sie dies durch Ihren bei AIHubMix generierten API Key
      http_options={"base_url": "https://aihubmix.com/gemini"},
  )
  ```
</CodeGroup>

<Tip>
  Die `baseUrl` ist fest `https://aihubmix.com/gemini` -- abweichend vom OpenAI-kompatiblen Endpunkt `https://aihubmix.com/v1`.
</Tip>

***

## Interactions API

Interactions ist die Gemini-Inferenzschnittstelle der naechsten Generation. Sie gibt strukturierte `Interaction`-Objekte zurueck und unterstuetzt Textgenerierung, native Bilderzeugung (Nano Banana) sowie mehrstufiges Reasoning. Derzeit wird der **synchrone Modus** (`interactions.create()`) unterstuetzt; der asynchrone Modus (Background Interactions: `get` / `cancel` / `delete`) folgt in Kuerze.

### Textgenerierung

Rufen Sie `interactions.create()` auf, um eine Inferenz zu starten. Das zurueckgegebene `Interaction`-Objekt bietet die Komfort-Eigenschaft `output_text`, ueber die Sie direkt die letzte Textausgabe des Modells abrufen koennen.

<CodeGroup>
  ```js JavaScript theme={null}
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Erklaere Quantencomputing in einem Satz",
  });

  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="Erklaere Quantencomputing in einem Satz",
  )

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

### Native Bilderzeugung

Konfigurieren Sie die Ausgabemodalitaet ueber `response_format` auf Bild. Das zurueckgegebene `Interaction`-Objekt bietet die Komfort-Eigenschaft `output_image`, deren `data`-Feld die Base64-codierten Bilddaten enthaelt.

<Tip>
  * Empfohlenes Modell: `gemini-3.1-flash-image` (Nano Banana 2, universelles Bildgenerierungsmodell).
  * Die Werte von `response_modalities` muessen **kleingeschrieben** sein: `['text', 'image']`; Grossbuchstaben sind die Schreibweise der `generateContent`-API und fuehren bei der Interactions API zu einem `400`-Fehler.
  * Uebergeben Sie nicht `delivery: 'inline'` (`400 Image delivery mode is not supported`) -- die Interactions API gibt Bilddaten standardmaessig inline zurueck.
</Tip>

**`response_format`-Parameter:**

| Feld           | Beschreibung      | Moegliche Werte                           |
| -------------- | ----------------- | ----------------------------------------- |
| `type`         | Ausgabetyp        | `"image"`                                 |
| `aspect_ratio` | Seitenverhaeltnis | `"1:1"` `"3:4"` `"4:3"` `"9:16"` `"16:9"` |
| `image_size`   | Ausgabeaufloesung | `"1K"` `"2K"` `"4K"`                      |
| `mime_type`    | Bildformat        | `"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" },
  });

  // Methode 1: output_image-Komfort-Eigenschaft (letztes generiertes Bild)
  if (interaction.output_image?.data) {
    fs.writeFileSync("output.png", Buffer.from(interaction.output_image.data, "base64"));
  }

  // Methode 2: Steps durchlaufen, geeignet fuer mehrstufige gemischte Ausgaben
  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-Komfort-Eigenschaft
  if interaction.output_image:
      with open("output.png", "wb") as f:
          f.write(base64.b64decode(interaction.output_image.data))
  ```
</CodeGroup>

### Streaming-Ausgabe

Uebergeben Sie `stream: true`, um Server-Sent Events (SSE) Streaming zu aktivieren. Die Ereignisse treffen in folgender Reihenfolge ein:

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

Inkrementeller Text wird ueber `event.delta.text` abgerufen; das Ereignistyp-Feld ist `event_type`.

```js JavaScript theme={null}
const stream = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Schreibe ein Haiku ueber den Mond",
  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

Ueber den `embedContent`-Endpunkt erhalten Sie Vektordarstellungen (Embeddings) von Text- oder multimodalen Inhalten.

<Tip>
  Fuer den OpenAI-kompatiblen `/v1/embeddings`-Endpunkt siehe [Vektor-Embeddings](/de/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: Ausgabedimension angeben (128-3072), Standard 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: Ausgabedimension angeben (128-3072), Standard 3072
      ),
  )

  print(f"dimensions: {len(result.embeddings[0].values)}")  # 768
  ```
</CodeGroup>

### Batch-Embeddings abrufen

Uebergeben Sie ein `Content`-Array an den `contents`-Parameter von `embedContent`, um Embeddings fuer mehrere Texte in einem einzigen Aufruf zu erhalten:

```js JavaScript theme={null}
const response = await ai.models.embedContent({
  model: "gemini-embedding-2-preview",
  contents: [
    { parts: [{ text: "Erster Text" }] },
    { parts: [{ text: "Zweiter Text" }] },
  ],
});

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

### Verfuegbare Modelle und Parameter

| Modell                       | Max. Eingabe-Token | Standard-Ausgabedimension | Eingabemodalitaeten           | Beschreibung                                                                |
| ---------------------------- | ------------------ | ------------------------- | ----------------------------- | --------------------------------------------------------------------------- |
| `gemini-embedding-2-preview` | 8.192              | 3.072 (empfohlen: 768)    | Text, Bild, Video, Audio, PDF | Neuestes multimodales Embedding-Modell, unterstuetzt `outputDimensionality` |
| `gemini-embedding-001`       | 2.048              | 3.072                     | Nur Text                      | Vorheriges Text-Embedding-Modell, unterstuetzt `taskType`                   |

`gemini-embedding-001` unterstuetzt die Angabe des Embedding-Verwendungszwecks ueber `config.taskType`, um die Vektorqualitaet fuer bestimmte nachgelagerte Aufgaben zu optimieren:

| `taskType`            | Verwendungszweck                         |
| --------------------- | ---------------------------------------- |
| `SEMANTIC_SIMILARITY` | Semantische Aehnlichkeitsberechnung      |
| `RETRIEVAL_DOCUMENT`  | Dokumentenindexierung (abgerufene Seite) |
| `RETRIEVAL_QUERY`     | Suchanfrage (abrufende Seite)            |
| `CLASSIFICATION`      | Textklassifikation                       |
| `CLUSTERING`          | Text-Clustering                          |

<Note>
  `gemini-embedding-2-preview` unterstuetzt den `taskType`-Parameter nicht. Stattdessen wird der Aufgabentyp ueber ein Praefix im Prompt angegeben (z. B. `search_query: ...` oder `search_document: ...`).
</Note>

***

## Context Caching (Explizites Caching)

Explizites Caching ermoeglicht es Entwicklern, `CachedContent`-Objekte manuell zu erstellen, abzufragen, zu referenzieren und zu loeschen. Es eignet sich fuer Szenarien, in denen derselbe lange Kontext ueber mehrere Anfragen hinweg wiederverwendet werden soll. Im Gegensatz zum [impliziten Caching](/de/api/Gemini-Guides#kontext-caching) wird beim expliziten Caching der Lebenszyklus aktiv von der Anwendungsseite verwaltet.

<Note>
  Explizites Caching ist nur fuer die `generateContent`-API verfuegbar. Die Interactions API unterstuetzt nur implizites Caching.
</Note>

<Tip>
  Modelle ohne konfigurierte Speicherpreise werden vom Gateway bei Cache-Erstellungsanfragen blockiert (`context caching is not available for model`), um unkontrollierte Speicherkosten zu vermeiden. Gaengige Modelle (gemini-2.5-flash, gemini-2.5-pro usw.) sind bereits konfiguriert.
</Tip>

### CachedContent erstellen

Erstellen Sie einen Cache ueber `caches.create()`. `ttl` (Time-To-Live) steuert die Gueltigkeitsdauer des Caches; nach Ablauf wird er automatisch geloescht.

<CodeGroup>
  ```js JavaScript theme={null}
  const longDocument = "Langer Text, der wiederholt referenziert wird...".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 = "Langer Text, der wiederholt referenziert wird..." * 500

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

  print(f"CachedContent name: {cache.name}")
  ```
</CodeGroup>

### Cache in generateContent referenzieren

Uebergeben Sie `cache.name` an den Parameter `cachedContent` (JS) bzw. `cached_content` (Python), um den Cache bei der Inferenz zu nutzen. Die Anzahl der getroffenen Token wird in `usageMetadata.cachedContentTokenCount` ausgewiesen.

<CodeGroup>
  ```js JavaScript theme={null}
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Fassen Sie die Kernaussagen des obigen Dokuments zusammen",
    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="Fassen Sie die Kernaussagen des obigen Dokuments zusammen",
      config={"cached_content": cache.name},
  )

  print(response.text)
  print(f"cached tokens: {response.usage_metadata.cached_content_token_count}")
  ```
</CodeGroup>

### Abfragen und Loeschen

<CodeGroup>
  ```js JavaScript theme={null}
  // CachedContent-Metadaten abfragen
  const info = await ai.caches.get({ name: cache.name });
  console.log("model:", info.model, "expireTime:", info.expireTime);

  // Cache loeschen
  await ai.caches.delete({ name: cache.name });
  ```

  ```python Python theme={null}
  # CachedContent-Metadaten abfragen
  info = client.caches.get(name=cache.name)
  print(f"model: {info.model}  expire_time: {info.expire_time}")

  # Cache loeschen
  client.caches.delete(name=cache.name)
  ```
</CodeGroup>

***

## Unterstuetzte Funktionen

| Funktion                                 | Status | Beschreibung                                                                      |
| ---------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| `generateContent`                        | ✅      | Nicht-Streaming + Streaming                                                       |
| `systemInstruction` / `generationConfig` | ✅      | temperature, maxOutputTokens usw.                                                 |
| Structured Output (`responseSchema`)     | ✅      | JSON-Modus                                                                        |
| Function Calling                         | ✅      | `functionDeclarations` Tool-Deklaration                                           |
| `thinkingConfig`                         | ✅      | Chain-of-Thought-Ausgabe                                                          |
| Multimodale Eingabe                      | ✅      | Bild / Audio / Video / PDF via `inlineData` + Files API                           |
| Google Search Grounding                  | ✅      | Suchverstaerkung                                                                  |
| `countTokens`                            | ✅      | Token-Zaehlung                                                                    |
| Imagen (`generateImages`)                | ✅      | Imagen 3 Bilderzeugung                                                            |
| Veo (`generateVideos`)                   | ✅      | Videogenerierung                                                                  |
| TTS                                      | ✅      | Sprachsynthese-Ausgabe                                                            |
| Files API                                | ✅      | Grosse Dateien hochladen und referenzieren                                        |
| Interactions API                         | ✅      | Inferenzschnittstelle der naechsten Generation (Text + Nano Banana Bilderzeugung) |
| Embeddings (`embedContent`)              | ✅      | Native Vektor-Embeddings                                                          |
| Context Caching CRUD                     | ✅      | Explizite Cache-Verwaltung                                                        |
| Live API (WebSocket)                     | ❌      | Noch nicht unterstuetzt                                                           |

***

## Haeufige Fragen

<AccordionGroup>
  <Accordion title="interactions.create() gibt einen Legacy-Schema-Fehler zurueck">
    Die SDK-Version ist zu alt. `@google/genai` muss >= 2.0.0 sein, `google-genai` muss >= 2.0.0 sein. Fuehren Sie `npm install @google/genai@latest` oder `pip install -U google-genai` aus, um auf die neueste Version zu aktualisieren.
  </Accordion>

  <Accordion title="Das Modell gibt 404 Not Found zurueck">
    Einige fruehe Modellnamen (z. B. `gemini-2.5-flash-image-preview`) wurden in der Interactions API eingestellt. Verwenden Sie aktuelle Modellbezeichner wie `gemini-3.1-flash-image` (Nano Banana 2). Die `generateContent`-API ist davon nicht betroffen.
  </Accordion>

  <Accordion title="response_modalities gibt 400 Bad Request zurueck">
    Die Werte von `response_modalities` in der Interactions API muessen kleingeschrieben sein (`"text"`, `"image"`). Grossbuchstaben `"TEXT"` / `"IMAGE"` sind die Schreibweise der `generateContent`-API und werden in der Interactions API nicht akzeptiert.
  </Accordion>

  <Accordion title="Kann vertexai: true verwendet werden?">
    Nein. Der `vertexai: true`-Modus des SDKs erfordert GCP OAuth + project-/location-Parameter und ist mit `apiKey` inkompatibel (das SDK wirft `Project/location and API key are mutually exclusive`). Bei der Anbindung ueber AIHubMix verwenden Sie einfach die Gemini Developer API -- das Backend routet automatisch.
  </Accordion>

  <Accordion title="Cache-Erstellung meldet: context caching is not available for model">
    Das Gateway blockiert `caches.create()`-Anfragen fuer Modelle ohne konfigurierte Speicherpreise, um unkontrollierte Speicherkosten zu vermeiden. Gaengige Modelle (gemini-2.5-flash, gemini-2.5-pro usw.) sind bereits konfiguriert. Pruefen Sie bei diesem Fehler, ob das Modell explizites Caching unterstuetzt.
  </Accordion>
</AccordionGroup>

***

Zuletzt aktualisiert: 2026-07-07