Entwicklerleitfaden für Gemini 3

Gemini 3 ist unsere bisher intelligenteste Modellfamilie, die auf modernster Logik basiert. Sie wurde entwickelt, um jede Idee zum Leben zu erwecken, indem sie agentische Workflows, autonomes Programmieren und komplexe multimodale Aufgaben beherrscht. In diesem Leitfaden werden die wichtigsten Funktionen der Gemini 3-Modellfamilie und die optimale Nutzung beschrieben.

High/Dynamic Thinking Low Thinking

Gemini 3 Pro verwendet standardmäßig dynamisches Denken, um Prompts zu analysieren. Wenn Sie schnellere Antworten mit geringerer Latenz benötigen und keine komplexen Schlussfolgerungen erforderlich sind, können Sie die Denkebene des Modells auf low beschränken.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

Entdecken

In unserer Sammlung von Gemini 3-Apps können Sie sehen, wie das Modell mit komplexen Reasoning-Aufgaben, autonomem Programmieren und komplexen multimodalen Aufgaben umgeht.

Das ist Gemini 3

Gemini 3 Pro ist das erste Modell der neuen Reihe. gemini-3-pro-preview ist die beste Wahl für komplexe Aufgaben, die ein breites Weltwissen und fortschrittliche multimodale Schlussfolgerungen erfordern.

* Die Preise gelten pro 1 Million Tokens. Die angegebenen Preise gelten für Standardtext. Die Preise für multimodale Eingaben können variieren.

Detaillierte Ratenlimits, Batchpreise und zusätzliche Informationen finden Sie auf der Seite zu Modellen.

Neue API-Funktionen in Gemini 3

Mit Gemini 3 werden neue Parameter eingeführt, mit denen Entwickler mehr Kontrolle über Latenz, Kosten und multimodale Genauigkeit erhalten.

Denkaufwand

Der Parameter thinking_level steuert die maximale Tiefe des internen Denkprozesses des Modells, bevor es eine Antwort generiert. Bei Gemini 3 werden diese Stufen als relative Kontingente für das Denken und nicht als strikte Token-Garantien behandelt. Wenn thinking_level nicht angegeben ist, wird standardmäßig Gemini 3 Pro mit high verwendet.

• low: Minimiert Latenz und Kosten. Am besten geeignet für einfache Anweisungen, Chat oder Anwendungen mit hohem Durchsatz
• medium: (Bald verfügbar), bei der Einführung nicht unterstützt
• high (Standard): Maximiert die Tiefe der Argumentation. Es kann deutlich länger dauern, bis das Modell das erste Token ausgibt, aber die Ausgabe ist sorgfältiger begründet.

Auflösung von Medien

Mit Gemini 3 wird über den Parameter media_resolution eine detaillierte Steuerung der multimodalen Bildverarbeitung eingeführt. Höhere Auflösungen verbessern die Fähigkeit des Modells, kleinen Text zu lesen oder kleine Details zu erkennen, erhöhen aber die Tokennutzung und die Latenz. Der Parameter media_resolution bestimmt die maximale Anzahl von Tokens, die pro Eingabebild oder Videoframes zugewiesen werden.

Sie können die Auflösung jetzt für jeden einzelnen Media-Teil oder global (über generation_config) auf media_resolution_low, media_resolution_medium oder media_resolution_high festlegen. Wenn nichts angegeben ist, verwendet das Modell optimale Standardwerte basierend auf dem Medientyp.

Empfohlene Einstellungen

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

Temperatur

Für Gemini 3 empfehlen wir dringend, den Temperaturparameter auf dem Standardwert 1.0 zu belassen.

Bei früheren Modellen war es oft sinnvoll, die Temperatur anzupassen, um die Kreativität im Vergleich zum Determinismus zu steuern. Die Reasoning-Funktionen von Gemini 3 sind jedoch für die Standardeinstellung optimiert. Wenn Sie die Temperatur ändern (auf unter 1,0 setzen), kann dies zu unerwartetem Verhalten führen, z. B. zu Schleifen oder einer schlechteren Leistung, insbesondere bei komplexen mathematischen oder logischen Aufgaben.

Gedankensignaturen

Gemini 3 verwendet Thought-Signaturen, um den Kontext der Argumentation über API-Aufrufe hinweg beizubehalten. Diese Signaturen sind verschlüsselte Darstellungen des internen Denkprozesses des Modells. Damit das Modell seine Fähigkeit zur logischen Schlussfolgerung beibehält, müssen Sie diese Signaturen in Ihrer Anfrage genau so an das Modell zurückgeben, wie sie empfangen wurden:

• Function Calling (Strict): Die API erzwingt eine strenge Validierung des aktuellen Zuges. Fehlende Signaturen führen zu einem 400-Fehler.
• Text/Chat:Die Validierung wird nicht streng erzwungen, aber das Weglassen von Signaturen beeinträchtigt die Argumentation und Antwortqualität des Modells.

Funktionsaufrufe (strenge Validierung)

Wenn Gemini ein functionCall generiert, wird das thoughtSignature verwendet, um die Ausgabe des Tools im nächsten Zug richtig zu verarbeiten. Der „aktuelle Zug“ umfasst alle Modell- (functionCall) und Nutzerschritte (functionResponse), die seit der letzten Standardnachricht User text erfolgt sind.

• Einzelner Funktionsaufruf:Der functionCall-Teil enthält eine Signatur. Sie müssen es zurückgeben.
• Parallele Funktionsaufrufe:Nur der erste functionCall-Teil in der Liste enthält die Signatur. Sie müssen die Teile in der genauen Reihenfolge zurücksenden, in der Sie sie erhalten haben.
• Mehrstufig (sequenziell): Wenn das Modell ein Tool aufruft, ein Ergebnis empfängt und ein anderes Tool aufruft (im selben Zug), haben beide Funktionsaufrufe Signaturen. Sie müssen alle im Verlauf gesammelten Signaturen zurückgeben.

Text und Streaming

Bei Standard-Chat oder Textgenerierung ist das Vorhandensein einer Signatur nicht garantiert.

• Nicht-Streaming: Der letzte Inhaltsteil der Antwort kann ein thoughtSignature enthalten, ist aber nicht immer vorhanden. Wenn ein Gerät zurückgegeben wird, sollten Sie es zurücksenden, um die bestmögliche Leistung zu erzielen.
• Streaming: Wenn eine Signatur generiert wird, kann sie in einem letzten Chunk mit einem leeren Textteil ankommen. Achten Sie darauf, dass Ihr Stream-Parser auch dann nach Signaturen sucht, wenn das Textfeld leer ist.

Codebeispiele

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

Migration von anderen Modellen

Wenn Sie einen Unterhaltungsverlauf von einem anderen Modell übertragen, z.B. Gemini 2.5) oder einen benutzerdefinierten Funktionsaufruf einfügen, der nicht von Gemini 3 generiert wurde, haben Sie keine gültige Signatur.

Wenn Sie die strenge Validierung in diesen spezifischen Szenarien umgehen möchten, füllen Sie das Feld mit diesem spezifischen Dummy-String aus: "thoughtSignature": "context_engineering_is_the_way_to_go"

Strukturierte Ausgaben mit Tools

Mit Gemini 3 können Sie strukturierte Ausgaben mit integrierten Tools wie Grounding mit der Google Suche, URL-Kontext und Codeausführung kombinieren.

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

Von Gemini 2.5 migrieren

Gemini 3 ist unsere bisher leistungsstärkste Modellfamilie und bietet eine schrittweise Verbesserung gegenüber Gemini 2.5 Pro. Beachten Sie bei der Migration Folgendes:

• Überlegung:Wenn Sie bisher komplexes Prompt-Engineering (z. B. Chain-of-Thought) verwendet haben, um Gemini 2.5 zum Schlussfolgern zu zwingen, probieren Sie Gemini 3 mit thinking_level: "high" und vereinfachten Prompts aus.
• Temperatureinstellungen:Wenn in Ihrem vorhandenen Code die Temperatur explizit festgelegt wird (insbesondere auf niedrige Werte für deterministische Ausgaben), empfehlen wir, diesen Parameter zu entfernen und den Gemini 3-Standardwert von 1,0 zu verwenden, um potenzielle Probleme mit Schleifen oder Leistungseinbußen bei komplexen Aufgaben zu vermeiden.
• PDF- und Dokumentanalyse:Die standardmäßige OCR-Auflösung für PDFs wurde geändert. Wenn Sie sich auf ein bestimmtes Verhalten beim Parsen von dichten Dokumenten verlassen haben, sollten Sie die neue Einstellung media_resolution_high testen, um die Genauigkeit zu gewährleisten.
• Tokenverbrauch:Durch die Migration zu Gemini 3 Pro-Standardeinstellungen kann der Tokenverbrauch für PDFs steigen, für Videos jedoch sinken. Wenn Anfragen aufgrund höherer Standardauflösungen das Kontextfenster überschreiten, empfehlen wir, die Media-Auflösung explizit zu verringern.
• Bildsegmentierung:Funktionen zur Bildsegmentierung (Rückgabe von Masken auf Pixelebene für Objekte) werden in Gemini 3 Pro nicht unterstützt. Für Arbeitslasten, die eine native Bildsegmentierung erfordern, empfehlen wir weiterhin die Verwendung von Gemini 2.5 Flash mit deaktiviertem Thinking-Modus oder Gemini Robotics-ER 1.5.

OpenAI-Kompatibilität

Für Nutzer, die die OpenAI-Kompatibilitätsebene verwenden, werden Standardparameter automatisch den entsprechenden Gemini-Parametern zugeordnet:

• reasoning_effort (OAI) entspricht thinking_level (Gemini). Hinweis: reasoning_effort entspricht thinking_level.

Best Practices für die Prompt-Erstellung

Gemini 3 ist ein Modell für logisches Denken, was sich auf die Art und Weise auswirkt, wie Sie Prompts formulieren sollten.

• Genaue Anweisungen:Fassen Sie sich in Ihren Eingabeaufforderungen kurz. Gemini 3 reagiert am besten auf direkte, klare Anweisungen. Es kann sein, dass sie ausführliche oder übermäßig komplexe Prompt-Engineering-Techniken, die für ältere Modelle verwendet wurden, überanalysiert.
• Ausführlichkeit der Ausgabe:Standardmäßig ist Gemini 3 weniger ausführlich und liefert lieber direkte, effiziente Antworten. Wenn für Ihren Anwendungsfall eine eher konversationelle oder „geschwätzige“ Persona erforderlich ist, müssen Sie das Modell in der Eingabeaufforderung explizit darauf hinweisen (z.B. „Erkläre das als freundlicher, gesprächiger Assistent.“
• Kontextverwaltung:Wenn Sie mit großen Datasets arbeiten (z.B. ganze Bücher, Codebasen oder lange Videos), platzieren Sie Ihre spezifischen Anweisungen oder Fragen am Ende des Prompts, nach dem Datenkontext. Verankern Sie die Argumentation des Modells in den bereitgestellten Daten, indem Sie Ihre Frage mit einer Formulierung wie „Basierend auf den oben genannten Informationen…“ beginnen.

Weitere Informationen zu Strategien für das Design von Prompts finden Sie im Leitfaden zum Prompt Engineering.

FAQ

1. Was ist der Wissensstand von Gemini 3 Pro? Gemini 3 hat einen Wissensstand von Januar 2025. Aktuellere Informationen finden Sie im Tool Search Grounding.

2. Welche Einschränkungen gelten für das Kontextfenster? Gemini 3 Pro unterstützt ein Kontextfenster für die Eingabe von 1 Million Tokens und bis zu 64.000 Tokens für die Ausgabe.

3. Gibt es eine kostenlose Stufe für Gemini 3 Pro? Sie können das Modell kostenlos in Google AI Studio ausprobieren. Derzeit ist jedoch keine kostenlose Stufe für gemini-3-pro-preview in der Gemini API verfügbar.

4. Funktioniert mein alter thinking_budget-Code weiterhin? Ja, thinking_budget wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt. Wir empfehlen jedoch, zu thinking_level zu migrieren, um eine besser vorhersagbare Leistung zu erzielen. Verwenden Sie nicht beide in derselben Anfrage.

5. Unterstützt Gemini 3 die Batch API? Ja, Gemini 3 unterstützt die Batch API.

6. Wird Kontext-Caching unterstützt? Ja, Kontext-Caching wird für Gemini 3 unterstützt. Die Mindestanzahl an Tokens, die zum Starten des Caching erforderlich ist, beträgt 2.048 Tokens.

7. Welche Tools werden in Gemini 3 unterstützt? Gemini 3 unterstützt Google Suche, Dateisuche, Codeausführung und URL-Kontext. Außerdem wird Function Calling für Ihre eigenen benutzerdefinierten Tools unterstützt. Google Maps und Computer Use werden derzeit nicht unterstützt.

Nächste Schritte

• Gemini 3 Cookbook
• Weitere Informationen finden Sie im Cookbook-Leitfaden zu Denkprozessebenen und zur Migration vom Budget für Denkprozesse zu Denkprozessebenen.