Skip to main content

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

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

Client initialisieren

Die baseUrl ist fest https://aihubmix.com/gemini — abweichend vom OpenAI-kompatiblen Endpunkt https://aihubmix.com/v1.

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.

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.
  • 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.
response_format-Parameter:

Streaming-Ausgabe

Uebergeben Sie stream: true, um Server-Sent Events (SSE) Streaming zu aktivieren. Die Ereignisse treffen in folgender Reihenfolge ein:
Inkrementeller Text wird ueber event.delta.text abgerufen; das Ereignistyp-Feld ist event_type.
JavaScript

Embeddings

Ueber den embedContent-Endpunkt erhalten Sie Vektordarstellungen (Embeddings) von Text- oder multimodalen Inhalten.
Fuer den OpenAI-kompatiblen /v1/embeddings-Endpunkt siehe Vektor-Embeddings.

embedContent

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:
JavaScript

Verfuegbare Modelle und Parameter

gemini-embedding-001 unterstuetzt die Angabe des Embedding-Verwendungszwecks ueber config.taskType, um die Vektorqualitaet fuer bestimmte nachgelagerte Aufgaben zu optimieren:
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: ...).

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 wird beim expliziten Caching der Lebenszyklus aktiv von der Anwendungsseite verwaltet.
Explizites Caching ist nur fuer die generateContent-API verfuegbar. Die Interactions API unterstuetzt nur implizites Caching.
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.

CachedContent erstellen

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

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.

Abfragen und Loeschen


Unterstuetzte Funktionen


Haeufige Fragen

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

Zuletzt aktualisiert: 2026-07-07