Zum Hauptinhalt springen

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

npm install @google/genai
# Erfordert >= 2.0.0; empfohlen: latest
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

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

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:
FeldBeschreibungMoegliche Werte
typeAusgabetyp"image"
aspect_ratioSeitenverhaeltnis"1:1" "3:4" "4:3" "9:16" "16:9"
image_sizeAusgabeaufloesung"1K" "2K" "4K"
mime_typeBildformat"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" },
});

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

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.
JavaScript
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.
Fuer den OpenAI-kompatiblen /v1/embeddings-Endpunkt siehe Vektor-Embeddings.

embedContent

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

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

ModellMax. Eingabe-TokenStandard-AusgabedimensionEingabemodalitaetenBeschreibung
gemini-embedding-2-preview8.1923.072 (empfohlen: 768)Text, Bild, Video, Audio, PDFNeuestes multimodales Embedding-Modell, unterstuetzt outputDimensionality
gemini-embedding-0012.0483.072Nur TextVorheriges 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:
taskTypeVerwendungszweck
SEMANTIC_SIMILARITYSemantische Aehnlichkeitsberechnung
RETRIEVAL_DOCUMENTDokumentenindexierung (abgerufene Seite)
RETRIEVAL_QUERYSuchanfrage (abrufende Seite)
CLASSIFICATIONTextklassifikation
CLUSTERINGText-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.
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.
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

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

Abfragen und Loeschen

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

Unterstuetzte Funktionen

FunktionStatusBeschreibung
generateContentNicht-Streaming + Streaming
systemInstruction / generationConfigtemperature, maxOutputTokens usw.
Structured Output (responseSchema)JSON-Modus
Function CallingfunctionDeclarations Tool-Deklaration
thinkingConfigChain-of-Thought-Ausgabe
Multimodale EingabeBild / Audio / Video / PDF via inlineData + Files API
Google Search GroundingSuchverstaerkung
countTokensToken-Zaehlung
Imagen (generateImages)Imagen 3 Bilderzeugung
Veo (generateVideos)Videogenerierung
TTSSprachsynthese-Ausgabe
Files APIGrosse Dateien hochladen und referenzieren
Interactions APIInferenzschnittstelle der naechsten Generation (Text + Nano Banana Bilderzeugung)
Embeddings (embedContent)Native Vektor-Embeddings
Context Caching CRUDExplizite Cache-Verwaltung
Live API (WebSocket)Noch nicht unterstuetzt

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