Gemini 3 Geliştirici Kılavuzu

Gemini 3, son teknoloji akıl yürütme temeli üzerine inşa edilmiş, bugüne kadarki en akıllı model ailemizdir. Temsilci tabanlı iş akışlarında, bağımsız kodlamada ve karmaşık çok formatlı görevlerde uzmanlaşarak her fikri hayata geçirmek için tasarlanmıştır. Bu kılavuzda, Gemini 3 model ailesinin temel özellikleri ve bu özelliklerden en iyi şekilde nasıl yararlanabileceğiniz açıklanmaktadır.

Yüksek/Dinamik Düşünme Düşük Düşünme

Gemini 3 Pro, istemleri değerlendirmek için varsayılan olarak dinamik düşünme özelliğini kullanır. Karmaşık akıl yürütme gerekmeyen durumlarda daha hızlı ve daha düşük gecikmeli yanıtlar için modelin düşünce düzeyini low ile sınırlayabilirsiniz.

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]"}]
    }]
  }'

Keşfet

Modelin gelişmiş akıl yürütme, bağımsız kodlama ve karmaşık çok formatlı görevleri nasıl ele aldığını görmek için Gemini 3 uygulamaları koleksiyonumuzu inceleyin.

Gemini 3 ile tanışın

Gemini 3 Pro, yeni serinin ilk modelidir. gemini-3-pro-preview, geniş dünya bilgisi ve farklı formatlarda gelişmiş akıl yürütme becerisi gerektiren karmaşık görevleriniz için en uygun modeldir.

* Fiyatlandırma, 1 milyon jeton başınadır. Listelenen fiyatlar standart metin içindir. Çok formatlı giriş ücretleri farklılık gösterebilir.

Ayrıntılı sıklık sınırları, toplu fiyatlandırma ve ek bilgiler için modeller sayfasına bakın.

Gemini 3'teki yeni API özellikleri

Gemini 3, geliştiricilerin gecikme, maliyet ve çok formatlı doğruluk üzerinde daha fazla kontrol sahibi olmasını sağlamak için tasarlanmış yeni parametreler sunar.

Düşünme düzeyi

thinking_level parametresi, modelin yanıt oluşturmadan önceki maksimum dahili muhakeme sürecinin derinliğini kontrol eder. Gemini 3, bu seviyeleri katı jeton garantileri yerine düşünme için göreceli izinler olarak değerlendirir. thinking_level belirtilmezse Gemini 3 Pro varsayılan olarak high değerini kullanır.

• low: Gecikmeyi ve maliyeti en aza indirir. Basit talimatları uygulamak, sohbet etmek veya yüksek işleme hızlı uygulamalar için en iyisidir.
• medium: (Çok yakında) Lansman sırasında desteklenmez.
• high (Varsayılan): Muhakeme derinliğini en üst düzeye çıkarır. Modelin ilk jetona ulaşması çok daha uzun sürebilir ancak çıkış daha dikkatli bir şekilde gerekçelendirilir.

Medya çözünürlüğü

Gemini 3, media_resolution parametresi aracılığıyla çok formatlı görüntü işleme üzerinde ayrıntılı kontrol sunar. Daha yüksek çözünürlükler, modelin ince metinleri okuma veya küçük ayrıntıları tanımlama becerisini artırır ancak jeton kullanımını ve gecikmeyi de artırır. media_resolution parametresi, giriş resmi veya video karesi başına ayrılan maksimum jeton sayısını belirler.

Artık çözünürlüğü her bir medya parçası için ayrı ayrı veya genel olarak (generation_config üzerinden) media_resolution_low, media_resolution_medium ya da media_resolution_high olarak ayarlayabilirsiniz. Belirtilmediği takdirde model, medya türüne göre optimum varsayılan değerleri kullanır.

Önerilen ayarlar

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"
          }
        }
      ]
    }]
  }'

Sıcaklık

Gemini 3 için sıcaklık parametresini varsayılan değeri olan 1.0'da tutmanızı önemle tavsiye ederiz.

Önceki modellerde yaratıcılık ile determinizm arasındaki dengeyi kontrol etmek için genellikle sıcaklık ayarından yararlanılırken Gemini 3'ün akıl yürütme özellikleri varsayılan ayar için optimize edilmiştir. Sıcaklığı değiştirmek (1, 0'ın altına ayarlamak), özellikle karmaşık matematiksel veya muhakeme görevlerinde döngüye girme ya da performansın düşmesi gibi beklenmedik davranışlara yol açabilir.

Düşünce imzaları

Gemini 3, API çağrıları arasında akıl yürütme bağlamını korumak için düşünce imzalarını kullanır. Bu imzalar, modelin dahili düşünce sürecinin şifrelenmiş gösterimleridir. Modelin muhakeme yeteneklerini korumasını sağlamak için bu imzaları isteğinizde modele alındıkları şekilde geri göndermeniz gerekir:

• İşlev Çağrısı (Katı): API, "Mevcut Sıra" üzerinde katı doğrulama uygular. Eksik imzalar 400 hatasına neden olur.
• Metin/Sohbet: Doğrulama katı bir şekilde uygulanmaz ancak imzaların atlanması modelin akıl yürütme ve yanıt kalitesini düşürür.

İşlev çağırma (katı doğrulama)

Gemini, functionCall oluşturduğunda aracın çıkışını bir sonraki dönüşte doğru şekilde işlemek için thoughtSignature kullanır. "Mevcut Tur", son standart Kullanıcı text mesajından bu yana gerçekleşen tüm Model (functionCall) ve Kullanıcı (functionResponse) adımlarını içerir.

• Tek İşlev Çağrısı: functionCall bölümü bir imza içerir. Ürünü iade etmeniz gerekir.
• Paralel İşlev Çağrıları: Listedeki yalnızca ilk functionCall bölümü imzayı içerir. Parçaları, alındıkları sırayla iade etmeniz gerekir.
• Çok adımlı (sıralı): Model bir aracı çağırır, sonuç alır ve başka bir aracı çağırırsa (aynı dönüş içinde) her iki işlev çağrısının da imzası olur. Geçmişte biriken tüm imzaları döndürmeniz gerekir.

Metin ve canlı yayın

Standart sohbet veya metin oluşturma işlemlerinde imza bulunması garanti edilmez.

• Akış Olmayan: Yanıtın son içerik bölümünde thoughtSignature bulunabilir ancak bu her zaman geçerli değildir. Bir cihaz iade edilirse en iyi performansı korumak için cihazı geri göndermeniz gerekir.
• Yayın: İmza oluşturulursa boş metin bölümü içeren son bir parça olarak gelebilir. Akış ayrıştırıcınızın, metin alanı boş olsa bile imzaları kontrol ettiğinden emin olun.

Kod örnekleri

// 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." }] 
  }
]

Diğer modellerden taşıma

Başka bir modelden (ör. Gemini 3 tarafından oluşturulmamış özel bir işlev çağrısı ekliyorsanız geçerli bir imzanız olmaz.

Bu belirli senaryolarda katı doğrulamayı atlamak için alanı şu belirli sahte dizeyle doldurun: "thoughtSignature": "context_engineering_is_the_way_to_go"

Araçlarla yapılandırılmış çıkışlar

Gemini 3, Yapılandırılmış Çıkışlar'ı Google Arama ile Temellendirme, URL Bağlamı ve Kod Yürütme gibi yerleşik araçlarla birleştirmenize olanak tanır.

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"]
        }
    }
  }'

Gemini 2.5'ten taşıma

Gemini 3, bugüne kadarki en yetenekli model ailemizdir ve Gemini 2.5 Pro'ya kıyasla kademeli bir iyileşme sunar. Taşıma işlemi yaparken aşağıdakileri göz önünde bulundurun:

• Düşünme: Gemini 2.5'i mantık yürütmeye zorlamak için daha önce karmaşık istem mühendisliği (ör. düşünce zinciri) kullanıyorsanız thinking_level: "high" ve basitleştirilmiş istemlerle Gemini 3'ü deneyin.
• Sıcaklık ayarları: Mevcut kodunuz sıcaklığı açıkça ayarlıyorsa (özellikle deterministik çıkışlar için düşük değerlere ayarlıyorsa) olası döngü sorunlarını veya karmaşık görevlerde performans düşüşünü önlemek için bu parametreyi kaldırmanızı ve Gemini 3'ün varsayılan değeri olan 1.0'ı kullanmanızı öneririz.
• PDF ve belge anlama: PDF'ler için varsayılan OCR çözünürlüğü değiştirildi. Yoğun doküman ayrıştırma için belirli bir davranışa güveniyorsanız doğruluğun devamlılığını sağlamak amacıyla yeni media_resolution_high ayarını test edin.
• Jeton tüketimi: Gemini 3 Pro varsayılanlarına geçiş, PDF'ler için jeton kullanımını artırabilir ancak videolar için jeton kullanımını azaltabilir. Varsayılan çözünürlüklerin yükselmesi nedeniyle istekler artık bağlam penceresini aşıyorsa medya çözünürlüğünü açıkça düşürmenizi öneririz.
• Görüntü segmentasyonu: Görüntü segmentasyonu özellikleri (nesneler için piksel düzeyinde maskeler döndürme) Gemini 3 Pro'da desteklenmez. Yerel görüntü segmentasyonu gerektiren iş yükleri için düşünme özelliği devre dışı bırakılmış Gemini 2.5 Flash veya Gemini Robotics-ER 1.5'i kullanmaya devam etmenizi öneririz.

OpenAI uyumluluğu

OpenAI uyumluluk katmanını kullanan kullanıcılar için standart parametreler otomatik olarak Gemini eşdeğerleriyle eşlenir:

• reasoning_effort (OAI) thinking_level (Gemini) ile eşlenir. reasoning_effort orta seviyesinin thinking_level yüksek seviyesine karşılık geldiğini unutmayın.

İstem yazmayla ilgili en iyi uygulamalar

Gemini 3, istemlerinizi nasıl yazmanız gerektiğini değiştiren bir akıl yürütme modelidir.

• Net talimatlar: Giriş istemlerinizde kısa ve öz olun. Gemini 3, doğrudan ve net talimatlara en iyi şekilde yanıt verir. Eski modeller için kullanılan ayrıntılı veya aşırı karmaşık istem mühendisliği tekniklerini aşırı analiz edebilir.
• Çıkış ayrıntı düzeyi: Gemini 3, varsayılan olarak daha az ayrıntılıdır ve doğrudan, etkili yanıtlar vermeyi tercih eder. Kullanım alanınız daha sohbet tarzı veya "konuşkan" bir karakter gerektiriyorsa istemde modeli açıkça yönlendirmeniz gerekir (ör. "Bunu arkadaş canlısı ve konuşkan bir asistan gibi açıkla").
• Bağlam yönetimi: Büyük veri kümeleriyle (ör. kitapların tamamı, kod tabanları veya uzun videolar) çalışırken özel talimatlarınızı ya da sorularınızı istemin sonuna, veri bağlamından sonra ekleyin. Sorunuza "Yukarıdaki bilgilere göre..." gibi bir ifadeyle başlayarak modelin muhakemesini sağlanan verilere dayandırın.

İstem tasarımı stratejileri hakkında daha fazla bilgiyi istem mühendisliği kılavuzunda bulabilirsiniz.

SSS

1. Gemini 3 Pro'nun bilgi kesme tarihi nedir? Gemini 3'ün bilgi kesme tarihi Ocak 2025'tir. Daha güncel bilgiler için Search Grounding aracını kullanın.

2. Bağlam penceresi sınırları nelerdir? Gemini 3 Pro, 1 milyon parçalık giriş bağlam penceresini ve 64 bin parçaya kadar çıkışını destekler.

3. Gemini 3 Pro'nun ücretsiz katmanı var mı? Modeli Google AI Studio'da ücretsiz olarak deneyebilirsiniz ancak şu anda Gemini API'de gemini-3-pro-preview için ücretsiz katman bulunmamaktadır.

4. Eski thinking_budget kodum çalışmaya devam eder mi? Evet, thinking_budget geriye dönük uyumluluk için hâlâ desteklenmektedir ancak daha öngörülebilir performans için thinking_level'ye geçmenizi öneririz. Aynı istekte ikisini birden kullanmayın.

5. Gemini 3, Batch API'yi destekliyor mu? Evet, Gemini 3, Batch API'yi destekler.

6. Bağlamı önbelleğe alma özelliği destekleniyor mu? Evet, Gemini 3'te Bağlam Önbelleğe Alma desteklenir. Önbelleğe almayı başlatmak için gereken minimum jeton sayısı 2.048'dir.

7. Gemini 3'te hangi araçlar desteklenir? Gemini 3; Google Arama, Dosya Arama, Kod Yürütme ve URL Bağlamı'nı destekler. Ayrıca, kendi özel araçlarınız için standart işlev çağrısını da destekler. Google Haritalar ve Bilgisayar Kullanımı'nın şu anda desteklenmediğini lütfen unutmayın.

Sonraki adımlar

• Gemini 3 Cookbook'u kullanmaya başlama
• Düşünme düzeyleri ve düşünme bütçesinden düşünme düzeylerine nasıl geçileceği hakkında özel Cookbook kılavuzunu inceleyin.