Gemini API reference

Bu API referansında, Gemini modelleriyle etkileşim kurmak için kullanabileceğiniz standart, akış ve anlık API'ler açıklanmaktadır. REST API'leri, HTTP isteklerini destekleyen herhangi bir ortamda kullanabilirsiniz. İlk API çağrınızla nasıl başlayacağınız hakkında bilgi edinmek için Hızlı Başlangıç Kılavuzu'na bakın. Dile özgü kitaplıklarımız ve SDK'larımızla ilgili referansları arıyorsanız sol gezinme bölümündeki SDK referansları altında ilgili dilin bağlantısına gidin.

Birincil uç noktalar

Gemini API, aşağıdaki ana uç noktalar etrafında düzenlenmiştir:

  • Standart içerik oluşturma (generateContent): İsteğinizi işleyen ve modelin tam yanıtını tek bir pakette döndüren standart bir REST uç noktası. Bu seçenek, sonucun tamamını bekleyebileceğiniz etkileşimsiz görevler için en iyisidir.
  • Akış halinde içerik oluşturma (streamGenerateContent): Yanıt parçalarını oluşturuldukça size göndermek için sunucu tarafından gönderilen etkinlikleri (SSE) kullanır. Bu sayede, chatbot'lar gibi uygulamalarda daha hızlı ve etkileşimli bir deneyim sunulur.
  • Live API (BidiGenerateContent): Çift yönlü akış için durum bilgisi içeren WebSocket tabanlı bir API'dir. Gerçek zamanlı sohbet kullanım alanları için tasarlanmıştır.
  • Toplu mod (batchGenerateContent): generateContent istek gruplarını göndermek için kullanılan standart bir REST uç noktasıdır.
  • Yerleştirmeler (embedContent): Girişten Content metin yerleştirme vektörü oluşturan standart bir REST uç noktasıdır.
  • Gen Media API'leri: Görsel üretimi için Imagen ve video üretimi için Veo gibi özel modellerimizle medya oluşturmaya yönelik uç noktalar. Gemini'da bu özellikler yerleşik olarak bulunur ve generateContent API'si kullanılarak erişilebilir.
  • Platform API'leri: Dosya yükleme ve jeton sayma gibi temel özellikleri destekleyen yardımcı program uç noktaları.

Kimlik doğrulama

Gemini API'ye yapılan tüm istekler, API anahtarınızla birlikte bir x-goog-api-key üstbilgisi içermelidir. Google Yapay Zeka Studio'da birkaç tıklamayla oluşturabilirsiniz.

Aşağıda, üst bilgiye API anahtarının dahil edildiği bir örnek istek verilmiştir:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Gemini SDK'larını kullanarak anahtarınızı API'ye iletme talimatları için Gemini API anahtarlarını kullanma kılavuzuna bakın.

İçerik oluşturma

Bu, modele istem göndermek için kullanılan merkezi uç noktadır. İçerik oluşturmak için iki uç nokta vardır. Temel fark, yanıtı nasıl aldığınızdır:

  • generateContent (REST): İsteği alır ve model tüm oluşturma işlemini tamamladıktan sonra tek bir yanıt verir.
  • streamGenerateContent (SSE): Tamamen aynı isteği alır ancak model, yanıtın parçalarını oluşturuldukça geri aktarır. Bu, kısmi sonuçları hemen görüntülemenize olanak tanıdığı için etkileşimli uygulamalarda daha iyi bir kullanıcı deneyimi sağlar.

İstek metni yapısı

İstek gövdesi, hem standart hem de akış modları için aynı olan ve birkaç temel nesneden oluşturulan bir JSON nesnesidir:

  • Content object: Bir görüşmedeki tek bir dönüşü temsil eder.
  • Part nesne: Content dönüşündeki bir veri parçası (ör. metin veya resim).
  • inline_data (Blob): İşlenmemiş medya baytları ve bunların MIME türü için bir kapsayıcı.

En üst düzeyde, istek gövdesinde bir contents nesnesi bulunur. Bu nesne, her biri sohbetteki dönüşleri temsil eden Content nesnelerinin listesidir. Çoğu durumda, temel metin oluşturma için tek bir Content nesneniz olur. Ancak görüşme geçmişini korumak istiyorsanız birden fazla Content nesne kullanabilirsiniz.

Aşağıda tipik bir generateContent istek gövdesi gösterilmektedir:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Yanıt gövdesi yapısı

Yanıt metni, aşağıdakiler hariç hem akış hem de standart modda benzerdir:

Genel olarak, yanıt gövdesinde bir candidates nesnesi bulunur. Bu nesne, Candidate nesnelerinin listesidir. Candidate nesnesi, modelden döndürülen oluşturulmuş yanıtı içeren bir Content nesnesi içerir.

İstek örnekleri

Aşağıdaki örneklerde, bu bileşenlerin farklı istek türleri için nasıl bir araya geldiği gösterilmektedir.

Yalnızca metin içeren istem

Basit bir metin istemi, tek bir Content nesnesi içeren bir contents dizisinden oluşur. Bu nesnenin parts dizisi ise text alanı olan tek bir Part nesnesi içerir.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

Çok formatlı istem (metin ve resim)

İstemde hem metin hem de resim sağlamak için parts dizisi iki Part nesne içermelidir: biri metin, diğeri ise resim inline_data için.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Çok adımlı görüşmeler (sohbet)

Birden fazla dönüş içeren bir görüşme oluşturmak için contents dizisini birden fazla Content nesnesiyle tanımlarsınız. API, sonraki yanıt için bağlam olarak bu geçmişin tamamını kullanır. Her Content nesnesinin role değeri user ve model arasında değişmelidir.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Temel çıkarımlar

  • Content zarfı temsil eder: Kullanıcıdan veya modelden gelen mesaj dönüşü için üst düzey kapsayıcıdır.
  • Part çok formatlılığı etkinleştirir: Farklı veri türlerini (metin, resim, video URI'si vb.) birleştirmek için tek bir Content nesnesinde birden fazla Part nesnesi kullanın.
  • Veri yönteminizi seçin:
    • Doğrudan yerleştirilmiş küçük medya öğeleri (ör. çoğu resim) için Part ile inline_data kullanın.
    • Daha büyük dosyalar veya istekler arasında yeniden kullanmak istediğiniz dosyalar için dosyayı yüklemek üzere File API'yi kullanın ve file_data bölümüyle referans verin.
  • Konuşma geçmişini yönetme: REST API'yi kullanan sohbet uygulamaları için her dönüşte contents nesnelerini ekleyerek Content dizisini oluşturun. "user" ve "model" rolleri arasında geçiş yapın. SDK kullanıyorsanız konuşma geçmişini yönetmenin önerilen yolu için SDK belgelerine bakın.

Yanıt örnekleri

Aşağıdaki örneklerde, bu bileşenlerin farklı istek türleri için nasıl bir araya geldiği gösterilmektedir.

Yalnızca metin içeren yanıt

Basit bir metin yanıtı, modelin yanıtını içeren bir veya daha fazla content nesnesi içeren bir candidates dizisinden oluşur.

Aşağıda, standart bir yanıt örneği verilmiştir:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Aşağıda bir dizi aktarım yanıtı verilmiştir. Her yanıtta, yanıtın tamamını bir araya getiren bir responseId bulunur:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

Live API, gerçek zamanlı akış kullanım alanlarını etkinleştirmek için çift yönlü akışa yönelik durum bilgisi içeren bir WebSocket tabanlı API sunar. Daha fazla bilgi için Live API kılavuzunu ve Live API referansını inceleyebilirsiniz.

Uzmanlaşmış modeller

Gemini API, Gemini model ailesine ek olarak Imagen, Lyria ve gömme modelleri gibi özel modeller için uç noktalar sunar. Modeller bölümündeki bu kılavuzlara göz atabilirsiniz.

Platform API'leri

Diğer uç noktalar, şu ana kadar açıklanan ana uç noktalarla birlikte kullanılabilecek ek özellikler sunar. Daha fazla bilgi edinmek için Kılavuzlar bölümündeki Toplu iş modu ve File API konularına göz atın.

Sırada ne var?

Yeni başlıyorsanız Gemini API programlama modelini anlamanıza yardımcı olacak aşağıdaki kılavuzlara göz atın:

Ayrıca, farklı Gemini API özelliklerini tanıtan ve kod örnekleri sunan yetenek kılavuzlarına da göz atabilirsiniz: