Gemini 3.8 Flash API-Tutorial: Denkstufen, PDF-Extraktion und Function Calling in Python

Was ist Gemini 3.8 Flash?

Gemini 3.8 Flash ist Googles Arbeitspferd unter den Modellen, allgemein verfügbar seit dem 2. September 2026 unter der Modell-ID gemini-3.8-flash. Es kam 3 Wochen nach 3.7 Flash, und Google positioniert es für langlaufende Coding-Aufgaben, agentische Workflows und mehrstufiges Reasoning in spezialisierten Domänen wie Finanzen und Rechtsarbeit.

Die für API-Calls relevanten Specs sind gegenüber 3.7 unverändert: 

• 1M Token Kontextfenster
• 64k maximale Output-Tokens
• Multimodaler Input (Text, Bilder, Video, Audio, PDFs) mit Textausgabe
• Gleiche Einführungspreise von $0.75 pro 1M Input-Tokens und $3.75 pro 1M Output-Tokens bis 31. Dezember 2026 (ab 1. Januar 2027 $1.50 bzw. $7.50)

Geändert hat sich das Verhalten, nicht die Oberfläche: Google sagt, 3.8 arbeitet bei komplexen Aufgaben gründlicher, macht zusätzliche Reasoning-Schritte und ruft Tools iterativ auf, was bei höheren Aufwandsstufen die Token-Nutzung steigern kann. 3.7 Flash bleibt voll unterstützt für Workloads, bei denen Effizienz wichtiger ist als Tiefe.

Für Benchmarks und detaillierte Preise lies unseren Gemini 3.8 Flash Guide oder hol dir im What is Google Gemini?-Guide einen Überblick über die Plattform.

Gemini 3.8 Flash vs. 3.8 Flash Cyber

Zum Launch gibt es 2 Varianten, und nur eine davon hat eine Modell-ID, die du eintippen kannst. 

• Gemini 3.8 Flash ist das General-Purpose-Modell, heute verfügbar in Google AI Studio und der Gemini API. 
• Gemini 3.8 Flash Cyber ist eine Cybersecurity-Variante, getunt für das Aufspüren von Schwachstellen und automatisierte Patches.

Die Cyber-Variante ist nicht über die öffentliche API verfügbar: Der Zugang läuft über Googles Fairwind Program, das auf genehmigte Behörden, Betreiber kritischer Infrastrukturen und Maintainer begrenzt ist.

Wenn du diesem Tutorial folgst, lautet deine Modell-ID gemini-3.8-flash. Nichts unten benötigt oder verwendet die Cyber-Variante.

Interactions API vs. generateContent

Um Gemini 3.8 Flash aufzurufen, nutze client.interactions.create() im google-genai-SDK. Google hat die Interactions API im Juni 2026 GA gemacht und empfiehlt sie für alle neuen Projekte. generateContent funktioniert noch, ist aber Legacy. Neue Features wie serverseitige Historie, Hintergrundausführung und beobachtbare Ausführungsschritte landen zuerst bei Interactions.

Die größte praktische Änderung ist das State-Management. Multi-Turn-Calls nutzen jetzt eine serverseitige previous_interaction_id: Du übergibst die letzte Interaktions-ID, und der Server stellt den Zustand wieder her. Du musst die Chat-Historie nicht mehr manuell anhängen oder komplett erneut senden. Vermeide auch das Vorabfüllen von Modell-Turns; das ist ein Legacy-Muster aus generateContent und bricht auf Gemini 3.x.

Eine Sache erwischt fast alle und kommt im PDF-Abschnitt zurück: previous_interaction_id stellt die Gesprächshistorie wieder her – und sonst nichts. tools, system_instruction, generation_config und response_format sind interaktionsbezogen. Jeder Turn, der sie braucht, muss sie erneut übergeben.

thinking_level ersetzt Sampling-Regler

Bei älteren Gemini-Modellen steuerten Entwickler mit temperature, top_p und top_k die Ausgaberandomness. Gemini 3.x wirft diese Sampling-Regler raus und ersetzt sie durch thinking_level – das ist jetzt der einzige Drehknopf.

Es akzeptiert 3 Werte:

• low: am wenigsten Reasoning-Tokens, am schnellsten und günstigsten. Passt zu Extraktion, Klassifikation und allem, was du selbst prüfst.

• medium: Standardwert und Googles Empfehlung für Code und Agentenarbeit.

• high: größtes Reasoning-Budget für harte Mehrschrittlogik und toolintensive Aufgaben.

Sende kein minimal. Das ist seit Gemini Flash 3.7 ungültig und führt zu einem 400-Validierungsfehler. 

Eine weitere Regel aus 3.7: frequency_penalty, presence_penalty und candidate_count erzeugen jetzt aktive API-Fehler. Entferne sie ebenfalls aus Legacy-Konfigurationen.

Wie richtest du die Gemini 3.8 Flash API ein?

Das Setup deiner Umgebung dauert etwa 2 Minuten. Du brauchst einen API-Schlüssel aus Google AI Studio und die aktualisierte google-genai Python-Bibliothek.

API-Schlüssel aus Google AI Studio holen

Besuche Google AI Studio in deinem Browser und melde dich mit deinem Google-Konto an. Klicke auf Create API Key, wähle oder erstelle ein Google-Cloud-Projekt und kopiere deinen geheimen Schlüssel. 

Öffne dein Terminal und speichere den Schlüssel als Umgebungsvariable mit export GEMINI_API_KEY=<your-key>.

Übergib den Schlüssel niemals als ?key= Query-Parameter in einer URL; Query-Strings landen in Serverlogs, Browser-Historien und Proxy-Caches. Wenn du das Modell vor dem Coden im Playground ausprobieren willst, deckt das Google AI Studio Tutorial Chat-, Build- und Stream-Modi ab; dieser Artikel bleibt bei der API.

Für Produktionssysteme ändert sich die Auth-Story: Vertex AI (jetzt Teil der Gemini Enterprise Agent Platform) bietet OAuth, IAM-Rollen und regionale Endpunkte statt eines rohen API-Schlüssels. In diesem Tutorial nutzen wir AI-Studio-Schlüssel, weil das der schnellste Lernpfad ist. Plane die Vertex-Migration, bevor echte Nutzerdaten im Spiel sind.

google-genai installieren und Client erstellen

Viele Tutorials sagen noch, google-generativeai zu installieren. Das ist das alte SDK ohne Interactions API. Installiere google-genai (Version 2.3.0 oder neuer):

pip install -U google-genai

Nach der Installation prüfst du, ob Python die Bibliothek lädt und deinen Client fehlerfrei initialisiert:

from google import genai # reads GEMINI_API_KEY from the environment
client = genai.Client() 
print("Client initialized successfully.")

Deinen ersten Interactions-API-Call machen

Jeder Request an die Interactions API erzeugt eine Interaction-Ressource, die den kompletten Turn speichert: deinen Input, die Gedanken des Modells, Tool-Calls und den finalen Output. Das SDK stellt den finalen Text über die Convenience-Property output_text bereit, sodass du selten die Schritte manuell durchlaufen musst.

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        "Write a pandas one-liner that adds a 7-day rolling average "
        "revenue column per store_id to a DataFrame with columns "
        "date, store_id, revenue. Reply with only the code, no explanation."
    ),
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
    f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
    f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)

Bei mir antwortete das Modell mit einer verketteten pandas-One-Liner-Lösung und dieser Nutzungszeile:

Diese Zahlen verbergen den ersten echten Unterschied zu 3.7. Ich habe dieselbe Aufgabe noch einmal mit längerem Prompt und ohne Output-Beschränkung ausgeführt, und 3.8 verbrauchte 1.436 Thinking-Tokens gegenüber 870 Output-Tokens. Mit Beschränkung waren es 1.515 gegenüber 42. Das Reasoning-Budget bewegte sich kaum – anders als bei 3.7, wo dieselben 2 Prompts das Thinking von 838 auf 1.530 schwanken ließen.

Kurz: 3.8 entscheidet anhand der Aufgabe, wie hart es nachdenkt – nicht anhand deiner Formulierung. Das passt zu Googles Aussage, dass das Modell gezielt mehr begründet und verifiziert. Thinking wird zum Output-Tarif abgerechnet, also waren beim eingeschränkten Call etwa 97% der abgerechneten Tokens Reasoning, das ich nie gesehen habe. Genau deshalb gibt es den nächsten Abschnitt. 

Die Antwort streamen

Für Chat-UIs oder alles, was jemand live liest, fühlt sich Warten auf die vollständige Antwort langsam an. Übergib stream=True an client.interactions.create() und gib Chunks beim Eintreffen aus:

	from google import genai

	client = genai.Client()

	stream = client.interactions.create(
	   model="gemini-3.8-flash",
	   input="Explain the difference between a JOIN and a correlated subquery in SQL.",
	   generation_config={"thinking_level": "low"},
	   stream=True,
	)

	for event in stream:
	   if event.event_type == "step.delta" and event.delta.type == "text":
	       print(event.delta.text, end="", flush=True)
	print() 

Bei mir kam eine lange, gut strukturierte Antwort bei thinking_level: "low": ein konzeptioneller Vergleich, eine Übersichtstabelle und 2 SQL-Beispiele, um die jeweils jüngste Bestellung pro Kunde zu finden – einmal mit Derived-Table-Join und einmal mit korrelierter Subquery in der SELECT-Liste. Die ersten Wörter erschienen nahezu sofort – genau darum geht es.

Das abschließende print() steht aus gutem Grund da. Ohne das endet der letzte Chunk mitten in der Zeile, und zsh zeigt ein verirrtes % vor deinem Prompt, weil der Stream exakt dort stoppt, wo der Modelltext stoppt. Außerdem tragen Deltas nur dann Text, und wenn du Token-Zahlen pro Request loggst, lies sie aus dem finalen Completion-Event statt Chunks zu summieren.

Wie beeinflusst thinking_level Kosten und Qualität?

thinking_level bestimmt, wie viel Reasoning Gemini 3.8 Flash vor der Antwort leistet. Reasoning-Tokens werden zum Output-Tarif von $3.75 pro 1M abgerechnet, also steuert dein Level direkt Kosten und Latenz. Google sagt, 3.8 nutzt das bewusst: Es macht bei komplexen Aufgaben zusätzliche Reasoning-Schritte und kann auf höheren Aufwandsstufen mehr Tokens verbrauchen als 3.7.

Einen Prompt auf low, medium und high laufen lassen

Der Test ist eine Race-Condition in einer Payment-Retry-Funktion, gesendet mit demselben Prompt auf allen 3 Stufen. Concurrency-Bugs bestrafen Querlesen – wenn es Unterschiede gibt, sieht man sie hier. Wenn du nur 1 Codeblock aus diesem Artikel ausführst, dann diesen; die Zahlen argumentieren besser als jede Prosa.

import time

from google import genai

client = genai.Client()

BUGGY_CODE = '''
import threading

payment_attempts = {}

def retry_payment(order_id, charge_fn, max_retries=3):
    """Retry a failed payment up to max_retries times."""
    if order_id not in payment_attempts:
        payment_attempts[order_id] = 0

    while payment_attempts[order_id] < max_retries:
        success = charge_fn(order_id)
        if success:
            del payment_attempts[order_id]
            return True
        payment_attempts[order_id] += 1
    return False
'''

PROMPT = (
    "Two worker threads can call retry_payment() with the same order_id "
    "at the same time. Identify the concurrency bug that can double-charge "
    "a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)

for level in ["low", "medium", "high"]:
    start = time.perf_counter()
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=PROMPT,
        generation_config={"thinking_level": level},
    )
    elapsed = time.perf_counter() - start
    usage = interaction.usage
    print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
    print(interaction.output_text)
    print(
        f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
        f"thinking={usage.total_thought_tokens}"
    )

Zur Einordnung: Die Schwachstelle ist ein nicht-atomarer Check-then-Act auf payment_attempts[order_id]. Unter Concurrency können 2 Threads beide die while-Bedingung passieren und beide charge_fn() aufrufen, bevor einer den Zähler inkrementiert. Die Lösung ist, den Read-Check-Charge-Increment-Flow in einen per-Order-Lock zu packen oder am Gateway einen Idempotency-Key zu nutzen.

Die Ergebnisse im Vergleich

Ergebnisse meiner Läufe:

Alle 3 Stufen fanden die Double-Charge, und alle 3 lieferten Per-Order-Locking, sodass unabhängige Bestellungen parallel laufen. Das ist der Knackpunkt im Vergleich zu 3.7: Dort packte low alles in einen globalen Lock, der während des Netzwerkanrufs gehalten wird; Per-Order-Locks tauchten erst bei medium auf. In 3.8 schreibt low dieses bessere Design bei 0 Thinking-Tokens, in 7,8 Sekunden, für weniger als ein Drittel Cent.

Was kaufen die Stufen also? Prüftiefe. Dieser Code hat 4 unterschiedliche Fehlermodi (Double-Charge, ein KeyError bei konkurrierendem Delete, ein erneutes Laden nach dem Success-Pfad mit State-Delete und nicht-atomare Zählerinkremente), und high war die einzige Stufe, die alle 4 nannte; low verpasste den Re-Charge-Fall, und medium den Zähler. 

high war auch die einzige Stufe, die die Failure-Path-Semantik des Fixes explizit beschrieb: Sind die Retries aufgebraucht, erhalten spätere Aufrufer False zurück, statt erneut zu belasten.

Die Thinking-Spalte zeigt Googles „3.8 arbeitet härter“-These direkt im Terminal. Gegen denselben Prompt auf 3.7 stieg medium von 2.343 auf 3.158 Thinking-Tokens, und high von 2.217 auf 4.512 – grob verdoppelt – und die zusätzlichen Tokens kauften eine vollständigere Analyse statt eines anderen Urteils. Die Latenz kletterte in diesem Lauf mit (7,8 s, 16,6 s, 25,5 s), aber Einzelmessungen schwanken; vergleiche also Token-Zahlen, nicht Sekunden.

Standard wählen und gezielt eskalieren

Meine Faustregel für Reasoning-Level:

• Unter 3.8 hat low eine größere Rolle verdient, als Googles Standard medium vermuten lässt: Es lieferte einen korrekten, gut designten Fix bei 0 Thinking-Tokens. Starte damit für alles, was ein Mensch liest, bevor es zählt (Triage, Entwürfe, Zusammenfassungen, Code, den du reviewst). 

• Nutze medium wo der Output ungelesen verschickt wird, denn das zusätzliche Thinking brachte eine vollständigere Analyse der Fehlermodi – und in ungelesenen Pipelines ist genau der nicht benannte Fehlmodus der, der feuert.

• Reserviere high für Outputs, bei denen der Failure-Pfad selbst das Produkt ist – etwa Zahlungsflüsse, Migrationen oder alles, was ein Reviewer Zeile für Zeile auditieren würde. In meinem Lauf war es die einzige Stufe, die alle 4 Bugs fand und beschrieb, was nach erschöpften Retries passiert.

Bei 6,6-fachen Kosten von low zu high liest sich dieser Trade-off heute bei $3.75 pro 1M Output-Tokens anders als nach dem 31. Dezember 2026 bei $7.50. Eskaliere daher pro Request statt global.

Ein Ausweg, den man kennen sollte: Google sagt, 3.7 Flash bleibt voll unterstützt für Effizienz-first-Workloads. Wenn 3.8s Zusatzsorgfalt mehr kostet, als deine Aufgabe braucht, ist das Bleiben auf gemini-3.7-flash eine unterstützte Wahl, kein Hack.

Wie extrahierst du strukturierte Daten aus einer PDF?

Gemini 3.8 Flash liest PDFs direkt als Input. Du kannst also eine Rechnung oder einen Bericht senden und Fragen dazu stellen. Ich nutzte eine einseitige Lieferantenrechnung mit Rechnungsnummer, Daten, 4 Positionen und einer Summe.

Eine PDF an den Prompt anhängen

Lass uns eine lokale Rechnungs-PDF über die Files API hochladen. Die Files API übernimmt Dateispeicherung und Caching auf Googles Infrastruktur:

	from google import genai
	client = genai.Client()
	print("Uploading invoice...")
	doc = client.files.upload(file="invoice_aug_2026.pdf")
	print(f"File uploaded: {doc.uri}\n")

	interaction = client.interactions.create(
	   model="gemini-3.8-flash",
	   input=[
	       {
	           "type": "text",
	           "text": "Extract the invoice number, total amount due, and due date.",
	       },
	       {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
	   ],
	)
	print(interaction.output_text)

Die Ausgabe aus meiner Rechnung:

Alle 3 Werte stimmen. Der Upload passiert einmal, und die Datei bleibt für spätere Requests verfügbar – wichtig, sobald du mehr als 1 Frage zum selben Dokument stellst. Die Antwort kommt als Markdown-Aufzählung zurück – gut lesbar, aber ungeeignet für eine Pipeline.

JSON per Response-Schema erzwingen

Um JSON statt Prosa zu erhalten, übergib ein Schema in response_format. In der Interactions API ist das ein Top-Level-Parameter; die responseMimeType-Einstellung innerhalb von generationConfig, die du in älteren Tutorials siehst, gehört zum Legacy-Endpunkt generateContent.

import json

from google import genai
from pydantic import BaseModel

client = genai.Client()


class Invoice(BaseModel):
    invoice_number: str
    total_due_usd: float
    due_date: str  # ISO 8601


doc = client.files.upload(file="invoice_aug_2026.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "text",
            "text": "Extract the invoice number, total amount due in USD, and due date.",
        },
        {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Invoice.model_json_schema(),
    },
)

invoice = json.loads(interaction.output_text)
print(invoice)

Das war meine Ausgabe: 

Deine Pydantic-Klasse definiert Pflichtfelder und Datentypen, während model_json_schema() das von der Gemini API benötigte JSON-Schema erzeugt. Mit json.loads() wandelst du die Modellausgabe in ein Standard-Python-Dict um. Ab hier kannst du die strukturierten Daten in eine DataFrame-Zeile umwandeln, in eine Datenbank schreiben oder in ein Google Sheet übernehmen.

Eine Rückfrage mit previous_interaction_id stellen

Für eine zweite Frage zum selben Dokument übergibst du die id der ersten Interaktion als previous_interaction_id. Der Server hat PDF und ersten Austausch bereits – du sendest beides nicht erneut:

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input="List each line item on the invoice with its amount.",
)

print(follow_up.output_text)

Es kamen alle 4 Positionen in Reihenfolge zurück, inklusive der wiederholten Compute-Zeile – ohne Kommentar zur Wiederholung. Das ist korrekt für die gestellte Frage; wenn du Anomalien markiert haben willst, fordere das explizit an. 

Zur Einordnung: 3.7 verhielt sich hier identisch, also bezieht sich 3.8s zusätzliche Gründlichkeit auf sein eigenes Reasoning, nicht darauf, ungefragt Audits zu liefern.

2 Dinge zu diesem Call: 

• response_format wurde nicht übernommen, weil es interaktionsbezogen ist – dieser Turn kam also als Prosa zurück. 

• Interaktionen werden standardmäßig (store=True) gespeichert: 55 Tage im Bezahl-Tier und 1 Tag im Free-Tier; store=False macht den Call zustandslos, verhindert aber, dass du eine previous_interaction_id anhängst.

Wie fügst du Function Calling in Gemini 3.8 Flash hinzu?

Function Calling auf Gemini 3.8 Flash ist eine Schleife: Das Modell fordert ein Tool an, dein Code führt es aus, du sendest das Ergebnis zurück, und das Modell schreibt die finale Antwort. In diesem Abschnitt bauen wir die Schleife manuell.

Wenn Google die Schleife für dich mit gehosteten Multi-Tool-Agenten ausführen soll, lies als Nächstes unser Tutorial zu „Managed Agents“ in der Gemini API. Und wenn du langfristig auf Agenten hinauswillst, baut der Building AI Agents with Google ADK-Kurs einen vollständigen Customer-Support-Assistenten auf denselben Primitiven.

Ein Tool definieren und die Interaktionsschleife ausführen

Unser Tool ist lookup_exchange_rate(currency, date), hinterlegt mit einem kleinen In-Memory-Dict, damit das Beispiel ohne externe API läuft. Die Deklaration ist ein JSON-Schema. Das Modell führt die Funktion nie aus; es liefert einen function_call-Schritt und bittet deinen Code darum:

import json

from google import genai

client = genai.Client()

# Local "data source" standing in for a real FX API
RATES = {
    ("USD", "2026-08-03"): 87.42,
    ("USD", "2026-08-10"): 87.15,
    ("EUR", "2026-08-03"): 95.08,
}


def lookup_exchange_rate(currency: str, date: str) -> dict:
    rate = RATES.get((currency.upper(), date))
    if rate is None:
        return {"error": f"No rate for {currency} on {date}"}
    return {"currency": currency.upper(), "date": date, "inr_rate": rate}


rate_tool = {
    "type": "function",
    "name": "lookup_exchange_rate",
    "description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
    "parameters": {
        "type": "object",
        "properties": {
            "currency": {"type": "string", "description": "ISO code, e.g. USD"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["currency", "date"],
    },
}

# Turn 1: the model decides to call the tool
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What was the USD to INR exchange rate on 2026-08-03?",
    tools=[rate_tool],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")

# Your code executes the function locally
result = lookup_exchange_rate(**fc_step.arguments)

# Turn 2: send the result back; tools must be re-specified (interaction-scoped)
final = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[rate_tool],
)

print(final.output_text)

Die Ausgabe: 

3 Dinge sind hier passiert:  

1. Turn 1 lieferte einen function_call-Schritt mit Name, strukturierten Argumenten und einer id.

2. Dein Python führte das Lookup lokal aus.

3. Turn 2 sendete einen function_result-Block mit Verweis auf diesen Call. 

Der Parameter tools wird in Turn 2 aus demselben Grund erneut übergeben wie response_format im PDF-Abschnitt: previous_interaction_id trägt Historie, nicht Konfiguration.

Fehler beim Function Calling auf Gemini 3.x

Wenn eine Tool-Schleife bricht, sind es fast immer 1 von 2 Ursachen. 

Erstens: Jedes Ergebnis muss auf seinen Call abbilden. In der Interactions API sind das call_id und name im function_result-Block; in der Legacy-generateContent-API müssen FunctionResponse und FunctionCall bei id und name übereinstimmen. Beides ist auf Gemini 3.x nicht optional.

Zweitens: Ein Malformed_Function_Call-Fehler tritt meist auf, wenn das Modell vor dem Tool-Call Kommentarteile ausgibt. Googles 3.8 Developer Guide rät, führenden Pre-Tool-Text zu bereinigen, Inline-Instruktionen mit \n\n zu formatieren und Arbeitsnotizen in einen dedizierten Function-Call statt als Rohtext zu packen. Schärfe die Systeminstruktion, statt blind zu retrien.

Was bricht beim Umstieg auf Gemini 3.8 Flash?

Das hängt davon ab, wo du startest. 

• Von Gemini 3.7 Flash: nichts. Ändere den Modellstring auf gemini-3.8-flash, und jeder Snippet in diesem Artikel läuft unverändert, da die API-Oberfläche identisch ist. 

• Von Gemini 3.6 Flash oder älter braucht die Modellkonfiguration dieselbe 15-Minuten-Prüfung wie zuvor.

Migrations-Checkliste (von 3.6 Flash oder älter)

Arbeite diese Punkte der Reihe nach ab. Punkte 1 bis 3 führen zu unmittelbaren 400ern; 4 und 5 verursachen stille Qualitätsprobleme.

1. Ändere die Modell-ID auf gemini-3.8-flash.

2. Entferne tote Sampling-Parameter: temperature, top_p und top_k werden auf Gemini 3.x ignoriert oder abgelehnt, und frequency_penalty, presence_penalty sowie candidate_count werfen aktive API-Fehler. Streiche alle 6 aus Legacy-Configs.

3. Ersetze thinking_budget durch thinking_level: Verwende nur low, medium oder high. Der alte Wert minimal liefert einen Validierungsfehler. Das gleichzeitige Senden von thinking_budget und thinking_level führt zu einem 400.

4. Entferne vorabgefüllte Modell-Turns: Streiche sie aus jeder konstruierten Konversation und stelle sicher, dass der letzte User-Turn nicht leer ist. History-Payloads dürfen nicht mit einem Modell-Turn enden.

5. Standardisiere Multi-Turn-Flows: Nutze previous_interaction_id statt clientseitigem History-Replay. Du musst tools, system_instruction und generation_config in jedem relevanten Turn erneut angeben.

Die maßgebliche Version veröffentlicht Google in den Gemini API Model Docs, inklusive eines automatisierten Pfads, falls dein Coding-Agent Skills unterstützt. Lies es selbst einmal – eine automatisierte Migration erklärt dir nicht, warum dein temperature=0.2 überhaupt gesetzt war.

Fehler, die du in Produktion sehen wirst

Hier sind die 4 Statuscodes, für die sich dedizierte Handler lohnen – und was sie in dieser API tatsächlich bedeuten:

2 weitere Hinweise:

• Setze explizite Client-Timeouts, wenn du thinking_level: "high" mit langen Tool-Schleifen kombinierst – ein hängender Request ist schlimmer als ein fehlgeschlagener, und 3.8s zusätzliche Gründlichkeit macht lange Reasoning-Läufe eher wahrscheinlicher als unwahrscheinlicher. 

• Logge interaction.id bei jedem Request – das ist dein Handle, um gespeicherte Interaktionen später abzurufen, zu debuggen oder zu löschen.

Abschließende Gedanken

Alles in diesem Artikel hängt an 3 Verschiebungen: Die Interactions API hat das Aufrufmuster geändert, thinking_level hat alle Sampling-Regler ersetzt, und der serverseitige Zustand via previous_interaction_id hat sowohl das PDF-Follow-up als auch die Tool-Schleife zu Einzeilern gemacht statt zu History-Replay-Übungen. Gemini 3.8 Flash hat daran nichts an der Oberfläche geändert; geändert hat sich, wie hart das Modell darin arbeitet – deshalb wurden alle Messungen frisch auf 3.8 statt aus 3.7 übernommen.

Bevor du meine Level-Empfehlungen übernimmst, lass das Vergleichsskript auf eine Aufgabe aus deinem eigenen Backlog laufen; das Level, das beim Payment-Retry-Race gewinnt, kann bei deiner SQL-Generierung verlieren. 

Wenn einzelne API-Calls nicht mehr reichen und du produktionsreife KI-Systeme willst, deckt unser Associate AI Engineer for Developers-Lernpfad den kompletten Weg ab, und der Associate AI Engineer for Data Scientists-Lernpfad tut dasselbe aus Datensicht.