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
Client initialisieren
Interactions API
Interactions ist die Gemini-Inferenzschnittstelle der naechsten Generation. Sie gibt strukturierteInteraction-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 Sieinteractions.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 ueberresponse_format auf Bild. Das zurueckgegebene Interaction-Objekt bietet die Komfort-Eigenschaft output_image, deren data-Feld die Base64-codierten Bilddaten enthaelt.
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" |
Streaming-Ausgabe
Uebergeben Siestream: true, um Server-Sent Events (SSE) Streaming zu aktivieren. Die Ereignisse treffen in folgender Reihenfolge ein:
event.delta.text abgerufen; das Ereignistyp-Feld ist event_type.
JavaScript
Embeddings
Ueber denembedContent-Endpunkt erhalten Sie Vektordarstellungen (Embeddings) von Text- oder multimodalen Inhalten.
embedContent
Batch-Embeddings abrufen
Uebergeben Sie einContent-Array an den contents-Parameter von embedContent, um Embeddings fuer mehrere Texte in einem einzigen Aufruf zu erhalten:
JavaScript
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 |
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.CachedContent erstellen
Erstellen Sie einen Cache uebercaches.create(). ttl (Time-To-Live) steuert die Gueltigkeitsdauer des Caches; nach Ablauf wird er automatisch geloescht.
Cache in generateContent referenzieren
Uebergeben Siecache.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
| 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
interactions.create() gibt einen Legacy-Schema-Fehler zurueck
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.Das Modell gibt 404 Not Found zurueck
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.response_modalities gibt 400 Bad Request zurueck
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.Kann vertexai: true verwendet werden?
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.Cache-Erstellung meldet: context caching is not available for model
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.Zuletzt aktualisiert: 2026-07-07