Die Gemini API: Ihre ersten echten Calls

# Die Gemini APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →: Ihre ersten echten Calls

Hier ist ein vollständiger, multimodaler Gemini-Call in Python: ein Bild, eine Frage, eine Antwort, wobei jedes Element etwas Gemini-spezifisches tut.

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-2.5-flash",
    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 alles. Kein Base64-Gefummel, kein separater Vision-Endpoint, kein OCR-Preprocessor. Sie übergeben dem Modell Bytes und Text gemeinsam, und es liest beides. Sehen wir uns an, was hier Gemini-spezifisch ist, denn dort liegt der Wert.

Das SDK und der Client

Das Package heißt google-genai, das einheitliche Google GenAI SDK. Installation mit pip install google-genai. Das ist das aktuelle SDK; wenn Sie alte Tutorials finden, die google.generativeai importieren, ist das die Legacy-Bibliothek. Nehmen 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: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.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, zwei Backends. Derselbe Client spricht entweder mit der Gemini Developer API (der AI-Studio-Key, schneller Start) oder mit Vertex AI (Google Cloud, mit IAM, VPC-Controls und Enterprise-Billing). Sie wechseln, indem Sie vertexai=True plus Projekt und Location setzen, nicht indem Sie Ihren Code umschreiben. Prototyping auf der Developer APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →, Umstieg auf Vertex, wenn Sie Governance brauchen. Diesen Schritt behandeln wir später in diesem Pfad.

Modellwahl: Flash vs. Pro

Der model-String ist eine echte Entscheidung, keine Formalität. Gemini kommt in Stufen:

• Flash ist das Arbeitstier: schnell, günstig, stark bei Extraktion, Klassifikation, Chat und Jobs mit hohem Volumen. Die Rechnungsaufgabe oben ist ein Flash-Job.
• Pro ist der Denker: schwierigere mehrstufige Probleme, dichter Code, lange analytische Ketten. Langsamer und pro TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → teurer.
• Flash-Lite-Varianten gibt es für die Fälle mit höchstem Volumen und niedrigsten Kosten.

Verwenden Sie einen gepinnten, datierten Alias wie gemini-2.5-flash, statt immer dem Neuesten nachzujagen. Modell-IDs entwickeln sich weiter, prüfen Sie also die aktuelle Liste in AI Studio oder auf der Models-Seite, bevor Sie ausliefern. Das Muster gilt auch, wenn die Versionsnummern hochzählen: zuerst Flash, Eskalation auf Pro nur, wenn Flash sichtbar Mühe hat.

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

Gemini ist nativ multimodal, das heißt Text, Bilder, Audio, Video und PDFs laufen durch dasselbe Modell statt durch ein angeflanschtes Vision-Modul. Der Tradeoff zwischen Kosten und Latenz bei Flash und Pro gilt damit auch für Bild- und Dokumentenarbeit, nicht nur für Text. Ein Flash-Modell, das ein 40-seitiges PDF liest, ist oft alles, was Sie brauchen.

Die contents-Struktur

contents ist eine Liste von Parts. Jeder Part ist ein Stück Input: ein text-Part, ein inline_data-Part (Rohbytes plus MIME-Type) oder eine Referenz auf eine hochgeladene Datei. Das Modell sieht sie in dieser Reihenfolge, die Platzierung des Prompts zählt also. Die Instruktion vor das Bild zu setzen, wie oben, funktioniert bei Aufgaben der Art „mach X mit diesem Ding“ meist gut.

Für kleine Bilder ist inline_data in Ordnung. Für alles Große (langes Video, große PDFs, 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-2.5-pro",
    contents=["Summarize the indemnification clauses.", uploaded],
)
print(response.text)

Beachten Sie: Sie kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen einfache Strings und Datei-Objekte direkt übergeben; das SDK verpackt sie für Sie in Parts. Die explizite Dict-Form aus dem ersten Beispiel ist genau dasselbe, nur ausgeschrieben.

Long Context, bewusst eingesetzt

Geminis langes Context WindowContext WindowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.Vollständige Definition ansehen → ist groß genug, dass Sie ganze Dokumente, Codebases oder Transkripte direkt in contents werfen und für viele Aufgaben auf Retrieval verzichten kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen. Das verändert das Design wirklich: manchmal ist das einfachste „RAG“ kein RAG, sondern einfach das ganze Korpus im Prompt.

Aber gratis ist das nicht. Mehr TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → bedeuten mehr Kosten und mehr Latenz, und sehr lange Kontexte kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen die Aufmerksamkeit auf das eine Detail verwässern, das Sie interessiert. Der Reflex, alles hineinzukopieren, ist eine Falle, wenn ein knapper, relevanter Ausschnitt genügen würde. Behandeln Sie Long Context als Werkzeug, für das Sie sich entscheiden, nicht als Default, auf den Sie sich stützen.

Konfiguration, die das Verhalten verändert

Übergeben Sie eine config, um die Generierung zu steuern. Zwei Einstellungen zahlen sich sofort aus.

Structured Output. Statt das Modell im Prompt um JSON zu bitten und zu hoffen, kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen Sie es auf ein SchemaSchemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.Vollständige Definition ansehen → festlegen. Gemini liefert dann passendes, valides JSON.

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-2.5-flash",
    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 gibt Ihnen ein echtes Python-Objekt, keinen String, den Sie mit json.loads durchdrücken und dabei beten müssen. So machen Sie Gemini-Calls sicher genug, um sie in nachgelagerten Code einzuhängen.

System Instructions. Setzen Sie dauerhaftes Verhalten über system_instruction in der Config, statt es in jedem Prompt zu vergraben:

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

Auch temperature, max_output_tokens und thinking_config wohnen hier. Letzteres ist Gemini-spezifisch: Bei reasoning-fähigen Modellen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen Sie das Thinking Budget anpassen, also den Umfang des internen Reasonings, das das Modell vor der Antwort aufwendet. Bei leichten Aufgaben senken Sie es für Geschwindigkeit, bei schweren erhöhen Sie es.

Grounding mit Google Search

Hier ist eine Fähigkeit, die Sie bei den meisten APIs nicht finden: Sie kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen Gemini seine Antworten in live Google-Search-Ergebnissen grounden lassen, mit Quellenangaben, über ein einziges Config-Flag.

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-2.5-flash",
    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 Queries aus und synthetisiert eine Antwort, deren Quellen in den Response-Metadaten hängen. Das ist der saubersten Weg gegen veraltetes Wissen bei faktischen, zeitkritischen Fragen, und es ist eingebaut statt etwas, das Sie selbst zusammenbauen. Details in den Grounding-Docs.

Streaming, Chat und Fehler

Drei praktische Dinge, bevor Sie ausliefern.

Streaming. Bei allem, worauf ein Mensch wartet, streamen Sie TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →, sobald sie eintreffen, statt auf die vollständige Antwort zu blocken:

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

Chat-Sessions. Für mehrstufige Konversationen hält client.chats.create(model=...) die History für Sie, Sie rufen chat.send_message(...) und es erinnert sich an die vorherigen Turns. Sie bauen nicht jedes Mal von Hand das ganze Transkript neu auf.

Fehler und Limits. Keys im Free Tier haben Rate Limits, und unter Last werden Sie 429-Responses sehen. Bauen Sie Retry mit Backoff ein. Achten Sie auf RESOURCE_EXHAUSTED (Quota) gegenüber INVALID_ARGUMENT (Ihr Request ist fehlerhaft, oft ein falscher MIME-Type oder ein zu großes Inline-Payload). Wenn Inline-Daten groß werden, wechseln Sie zur Files APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →; das behebt einen überraschend großen Teil der frühen Fehlschläge.

AI Studio: prototypen, dann exportieren

Schreiben Sie kein Python zum Erkunden. Öffnen Sie AI Studio, fügen Sie Ihren Prompt ein, legen Sie ein Bild dazu, schalten Sie Structured Output und Grounding um, justieren Sie die Temperature und sehen Sie zu, wie es arbeitet. Wenn der Prompt sich so verhält, wie ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → soll, klicken Sie auf „Get code“, und AI Studio generiert den exakten google-genai-Call, samt Modell-ID und Config. Ihr Loop lautet dann: in AI Studio experimentieren, exportieren, im Editor verfeinern.

Hier prüfen Sie auch den Tokenverbrauch und testen Modelle nebeneinander, bevor Sie sich für eins in Produktion entscheiden.

Wann Sie stattdessen zu Vertex AI greifen

Der Developer-APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Key ist perfekt für Prototypen und kleine Apps. Wechseln Sie zu Vertex AI, wenn Sie eines davon brauchen: IAM und Zugriffskontrolle auf Organisationsebene, garantierte Data Residency, VPC Service Controls, kundenverwaltete Verschlüsselung oder konsolidiertes Google-Cloud-Billing. Derselbe google-genai-Code trägt sich mit; Sie stellen den Client auf Vertex-Modus um und authentifizieren über Google Cloud statt über einen APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Key. Siehe cloud.google.com/vertex-ai. Die Entscheidung dreht sich um Governance und Scale, nicht um Fähigkeiten, denn die zugrunde liegenden Modelle sind dieselbe Familie.

Eine Anmerkung dazu, wo die APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → sitzt

Die APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → ist einer von mehreren Wegen zu Gemini, und sie zielen auf unterschiedliche Aufgaben. Die Gemini App und Gems sind Endnutzer-Oberflächen. Gemini in Workspace lebt in Docs und Gmail. Gemini CLI und Code Assist bedienen Entwickler im Terminal und in der IDE. Die APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → ist die Schicht unter Ihren eigenen Produkten: Sie rufen sie, wenn *Sie* derjenige sind, der das Ding baut, das andere benutzen. Alles in dieser Lektion ist diese Builder-Schicht.

Key Takeaways

• Installieren Sie `google-genai`, nicht das Legacy-`google.generativeai`. Ein SDK, ein genai.Client(), und derselbe Code läuft gegen die AI-Studio-Developer-APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → und gegen Vertex AI.
• Default ist Flash, Eskalation auf Pro. Flash erledigt Extraktion, Chat und Arbeit mit hohem Volumen günstig; reservieren Sie Pro für wirklich schweres Reasoning, und pinnen Sie eine datierte Modell-ID, statt dem Neuesten nachzujagen.
• Übergeben Sie multimodalen Input als Parts. Nutzen Sie inline_data für kleine Bilder und die Files APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → für große PDFs, Video oder alles, was Sie wiederverwenden, und denken Sie daran: Gemini liest beides nativ in einem Call.
• Begrenzen Sie den Output mit `response_schema` und lesen Sie `response.parsed`. Damit wird aus Modell-Output ein typisiertes Objekt, das Sie sicher in nachgelagerten Code einhängen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen.
• Prototypen in AI Studio, dann „Get code“. Justieren Sie Prompts, Grounding und Config visuell auf aistudio.google.com, exportieren Sie den exakten Call, und wechseln Sie erst dann in den Editor.