Die Gemini API: Ihre ersten echten Calls

Hier ist ein vollständiger, multimodaler Gemini-Call in Python: ein Bild, eine Frage, eine Antwort, und jedes Element erfüllt eine Gemini-spezifische Aufgabe.

from google import genai

client = genai.Client()  # liest GEMINI_API_KEY aus der Umgebung

with open("invoice.png", "rb") as f:
    image_bytes = f.read()

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        {"text": "Extract the total amount and due date. Reply as JSON."},
        {"inline_data": {"mime_type": "image/png", "data": image_bytes}},
    ],
)

print(response.text)

Das ist schon alles. Sie brauchen kein Base64-Gefrickel, keinen separaten Vision-Endpoint und keinen OCR-Präprozessor. Sie übergeben dem Modell Bytes und Text zusammen, und es liest beides. Der Rest dieser Lektion erklärt, was daran Gemini-spezifisch ist, denn genau dort liegt der Nutzen.

Das SDK und der Client

Das Paket heißt google-genai, das einheitliche Google GenAI SDK. Installieren Sie es mit pip install google-genai. Das ist das aktuelle SDK. Wenn Sie alte Tutorials finden, die google.generativeai importieren, handelt es sich um die Legacy-Bibliothek. Verwenden Sie die neue.

pip install google-genai
export GEMINI_API_KEY="your-key-from-aistudio"

Den Key holen Sie sich auf aistudio.google.com unter „Get APIAPIApplication Programming Interface: eine standardisierte Schnittstelle, über die Anwendungen kommunizieren und Daten austauschen, ohne die interne Funktionsweise der jeweils anderen zu kennen.Vollständige Definition ansehen → key“. Der Konstruktor `genai.Client()` liest `GEMINI_API_KEY` automatisch, Sie übergeben ihn also selten im Code. Die vollständige Referenz finden Sie auf ai.google.dev.

Ein SDK spricht mit zwei Backends. Derselbe Client funktioniert entweder mit der Gemini Developer API (der AI-Studio-Key, schneller Einstieg) oder mit Vertex AI (Google Cloud, mit IAM, VPC-Kontrollen und Enterprise-Abrechnung). Sie wechseln, indem Sie vertexai=True sowie ein Projekt und eine Location setzen. Ihren Code schreiben Sie nicht neu. Bauen Sie Prototypen auf der Developer API und wechseln Sie zu Vertex, wenn Sie Governance brauchen. Diesen Wechsel behandeln wir später in diesem Lernpfad.

Die Modellwahl: Flash vs. Pro

Der model-String ist eine echte Entscheidung. Die aktuelle Generation ist Gemini 3, und sie kommt in Stufen:

• Flash ist das Arbeitspferd. Es ist schnell und günstig und bewältigt Extraktion, Klassifikation, Chat und Jobs mit hohem Volumen gut. Die Rechnungsaufgabe oben ist ein Flash-Job.
• Pro ist das Reasoning-Modell, für schwierigere mehrstufige Probleme, dichten Code und lange analytische Ketten. Es ist langsamer und pro TokenTokenEin Token ist die grundlegende Texteinheit, die Sprachmodelle verarbeiten, oft ein Wortfragment, ein ganzes Wort oder ein Satzzeichen und nicht ein einzelnes Zeichen.Vollständige Definition ansehen → teurer.
• Flash-Lite-Varianten decken die Fälle mit dem höchsten Volumen und den niedrigsten Kosten ab.

Modell-IDs ändern sich häufig. Manche starten mit einem -preview-Suffix und werden später zu einer stabilen ID, und ältere Generationen (Gemini 2.5 und früher) bekommen Deprecation-Termine. Prüfen Sie vor dem Release die aktuelle Liste auf der Modellseite und pinnen Sie die exakte ID, die Sie getestet haben, statt eines variablen „latest“-Alias. Das Muster gilt weiter, auch wenn die Versionsnummern steigen: Greifen Sie zuerst zu Flash und wechseln Sie nur dann zu Pro, wenn Flash sichtbar an Grenzen stößt.

Warum das bei Gemini stärker ins Gewicht fällt

Gemini ist nativ multimodal. Text, Bilder, Audio, Video und PDFs laufen durch dasselbe Modell statt durch ein angeflanschtes Vision-Modul. Der Tradeoff bei Kosten und Latenz zwischen Flash und Pro gilt daher auch für die Arbeit mit Bildern und Dokumenten. Ein Flash-Modell, das ein 40-seitiges PDF liest, reicht oft völlig aus.

Die contents-Struktur

contents ist eine Liste von Parts. Jeder Part ist ein Stück Input: ein text-Part, ein inline_data-Part (rohe Bytes plus MIME-Typ) oder eine Referenz auf eine hochgeladene Datei. Das Modell sieht sie in dieser Reihenfolge, die Platzierung spielt also eine Rolle. Bei Aufgaben nach dem Muster „mach X mit diesem Ding“ funktioniert es meist gut, die Anweisung wie oben vor das Bild zu setzen.

Für kleine Bilder ist inline_data in Ordnung. Für alles Große, etwa lange Videos, umfangreiche PDFs oder Dateien, die Sie über mehrere Calls hinweg wiederverwenden, laden Sie einmal über die Files API hoch und übergeben stattdessen ein Handle:

uploaded = client.files.upload(file="contract.pdf")
response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=["Summarize the indemnification clauses.", uploaded],
)
print(response.text)

Sie kkDie durchschnittliche Zahl neuer Nutzer, die jeder bestehende Nutzer über Empfehlungen generiert. Über 1,0 verstärkt sich das Wachstum selbst und wird exponentiell.Vollständige Definition ansehen →önnen einfache Strings und Dateiobjekte direkt übergeben, und das SDK verpackt sie für Sie in Parts. Die explizite Dict-Form im ersten Beispiel ist dasselbe, nur ausgeschrieben.

Long Context, bewusst eingesetzt

Das Kontextfenster von Gemini ist groß genug für ganze Dokumente, Codebases oder Transkripte. Bei vielen Aufgaben können Sie das Material also direkt in contents packen und auf Retrieval verzichten. Manchmal ist das einfachste „RAGRAGVerfahren, mit dem ein KI-Modell aus Ihren eigenen Dokumenten antwortet, indem es relevante Passagen abruft, bevor es eine Antwort erzeugt.Vollständige Definition ansehen →“ gar kein RAG, sondern einfach der gesamte Korpus im Prompt.

Das hat allerdings seinen Preis. Mehr Tokens bedeuten mehr Kosten und mehr Latenz, und sehr lange Kontexte können die Aufmerksamkeit für das eine Detail verwässern, auf das es Ihnen ankommt. Alles hineinzukopieren ist eine Falle, wenn ein knapper, relevanter Ausschnitt genügen würde. Nutzen Sie Long Context, wenn die Aufgabe es verlangt, und machen Sie es nicht zum Standard.

Konfiguration, die das Verhalten ändert

Übergeben Sie eine config, um die Generierung zu steuern. Zwei Einstellungen sind sofort nützlich.

Structured Output. Sie müssen JSON nicht im Prompt anfordern und dann hoffen. Sie können das Modell auf ein SchemaSchemaEin Schema ist der formale Bauplan, der festlegt, wie Daten in einer Datenbank, einer Datei oder einer Nachricht strukturiert, benannt, typisiert und miteinander verknüpft sind.Vollständige Definition ansehen → festlegen, und Gemini liefert valides JSON, das diesem Schema entspricht.

from google import genai
from pydantic import BaseModel

class Invoice(BaseModel):
    total: float
    due_date: str

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=["Extract total and due date.", uploaded],
    config={
        "response_mime_type": "application/json",
        "response_schema": Invoice,
    },
)

invoice = response.parsed  # ein typisiertes Invoice-Objekt
print(invoice.total, invoice.due_date)

response.parsed liefert Ihnen ein echtes Python-Objekt statt eines Strings, den Sie mit json.loads parsen und dabei auf das Beste hoffen müssen. So machen Sie Gemini-Calls sicher genug, um sie in nachgelagerten Code einzubinden.

System Instructions. Legen Sie dauerhaftes Verhalten mit system_instruction in der config fest, statt es in jedem Prompt zu wiederholen:

config={"system_instruction": "You are a terse financial analyst. Cite figures exactly as written."}

Auch die Einstellungen temperature, max_output_tokens und thinking_config gehören hierher. Gemini-3-Modelle denken nach, bevor sie antworten, und wie viel, steuern Sie mit thinking_level innerhalb von thinking_config (zum Beispiel {"thinking_config": {"thinking_level": "low"}}). Verwenden Sie low für Geschwindigkeit bei einfacher Extraktion und high für schwierige Probleme. Ältere 2.5-Modelle nutzten stattdessen ein numerisches thinking_budget, Sie werden in Tutorials also beides sehen. Für Gemini 3 empfiehlt Google, temperature auf dem Standardwert 1.0 zu belassen.

Grounding mit Google Search

Das bieten nur wenige andere APIs: Sie können Gemini seine Antworten auf Live-Ergebnisse der Google-Suche stützen lassen, mit Quellenangaben, über einen einzigen Tool-Eintrag in der config.

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="What changed in the latest Gemini API pricing?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())]
    ),
)

print(response.text)

Das Modell entscheidet, wann es sucht, führt die Suchanfragen aus und schreibt eine Antwort, die Quellen hängen in den Metadaten der Response. Bei faktischen, zeitkritischen Fragen ist das die sauberste Lösung gegen veraltetes Wissen, und sie ist eingebaut. Details finden Sie in der Grounding-Dokumentation.

Streaming, Chat und Fehler

Ein paar praktische Punkte, bevor Sie live gehen.

Streaming. Bei allem, worauf ein Mensch wartet, streamen Sie die Tokens, sobald sie eintreffen, statt bis zur vollständigen Antwort zu blockieren:

for chunk in client.models.generate_content_stream(
    model="gemini-3-flash-preview",
    contents="Explain native multimodality in two sentences.",
):
    print(chunk.text, end="", flush=True)

Chat-Sessions. Bei Unterhaltungen über mehrere Turns führt client.chats.create(model=...) den Verlauf für Sie. Sie rufen chat.send_message(...) auf, und frühere Turns bleiben erhalten, sodass Sie das Transkript nicht von Hand neu aufbauen müssen.

Fehler und Limits. Free-Tier-Keys haben Rate Limits, und unter Last bekommen Sie 429-Responses. Bauen Sie also Retries mit Backoff ein. RESOURCE_EXHAUSTED bedeutet, dass das Kontingent erschöpft ist. INVALID_ARGUMENT bedeutet, dass Ihr Request fehlerhaft ist, oft wegen eines falschen MIME-Typs oder eines zu großen Inline-Payloads. Wenn die Inline-Daten groß werden, wechseln Sie zur Files API. Das behebt einen überraschend großen Teil der frühen Fehler. Achten Sie außerdem auf Fehler durch ausgemusterte Modell-IDs, wenn Google eine ältere Generation abkündigt.

AI Studio: erst Prototyp, dann Export

Schreiben Sie kein Python, um auszuprobieren. Öffnen Sie AI Studio, fügen Sie Ihren Prompt ein, ziehen Sie ein Bild hinein, schalten Sie Structured Output und Grounding ein, justieren Sie die Einstellungen und sehen Sie zu, wie es funktioniert. Wenn der Prompt sich wie gewünscht verhält, klicken Sie auf „Get code“, und AI Studio generiert den exakten google-genai-Call inklusive Modell-ID und config. Ihr Ablauf sieht dann so aus: in AI Studio experimentieren, exportieren, im Editor verfeinern.

In AI Studio prüfen Sie außerdem den Token-Verbrauch und testen Modelle nebeneinander, bevor Sie eines für die Produktion festlegen.

Wann Sie stattdessen zu Vertex AI greifen

Der Developer-API-Key eignet sich gut für Prototypen und kleine Apps. Wechseln Sie zu Vertex AI, wenn Sie IAM auf Organisationsebene, Garantien zur DatenresidenzDatenresidenzDie Anforderung, Daten physisch in einem bestimmten Land oder einer Region zu speichern und zu verarbeiten, oft aus rechtlichen oder vertraglichen Gründen.Vollständige Definition ansehen →, VPC Service Controls, kundenverwaltete Verschlüsselung oder eine konsolidierte Google-Cloud-Abrechnung brauchen. Derselbe google-genai-Code lässt sich übernehmen: Sie schalten den Client in den Vertex-Modus und authentifizieren sich über Google Cloud statt über einen API-Key. Siehe cloud.google.com/vertex-ai. Die Entscheidung betrifft Governance und Skalierung. Die zugrunde liegenden Modelle gehören zur selben Familie, durch den Wechsel gewinnen Sie also keine zusätzlichen Fähigkeiten.

Wo die API einzuordnen ist

Die API ist einer von mehreren Zugängen zu Gemini, und jeder zielt auf eine andere Aufgabe. Die Gemini-App und Gems sind Oberflächen für Endnutzer. Gemini in Workspace steckt in Docs und Gmail. Gemini CLI und Code Assist bedienen Entwickler im Terminal und in der IDE. Die API ist die Schicht unter Ihren eigenen Produkten. Sie rufen sie auf, wenn Sie selbst das bauen, was andere nutzen, und alles in dieser Lektion dreht sich um diese Schicht.

Das Wichtigste in Kürze

• Installieren Sie google-genai, nicht das Legacy-Paket google.generativeai. Ein einziger genai.Client() läuft sowohl gegen die Developer API von AI Studio als auch gegen Vertex AI.
• Nehmen Sie standardmäßig Gemini 3 Flash und wechseln Sie für schwieriges Reasoning zu Pro. Pinnen Sie die exakte Modell-ID, die Sie getestet haben, und prüfen Sie die Modellseite auf Deprecations.
• Übergeben Sie multimodalen Input als Parts: inline_data für kleine Bilder, die Files API für große PDFs, Videos oder alles, was Sie wiederverwenden.
• Legen Sie den Output mit `response_schema` fest und lesen Sie `response.parsed`, um typisierte Objekte zu erhalten, die Sie nachgelagert sicher verwenden können.
• Bei Gemini 3 steuern Sie das Reasoning mit thinking_level. Bauen Sie Prototypen in AI Studio und exportieren Sie den exakten Call anschließend mit „Get code“.