Gemini Decisions API Nasıl Kullanılır?

Gemini Decisions API'yi kullanmak için Google AI Studio'da bir anahtar alın, google-genai 3.2 veya daha yeni bir sürümü yükleyin ve gemini-decision-1 modeli, tek bir ortak input ve tiplenmiş questions haritası (noul, choice veya score) ile client.decisions.create() çağrısı yapın. Her soru için kalibre edilmiş bir olasılık ve bir confidence değeri alırsınız; çıktı tokeni sıfırdır.

Aşağıda: Python, JavaScript ve REST ile ilk evet/hayır sorunuzdan güven tabanlı yönlendirmeye ve bir CI test paketine kadar her adım.

Gemini Decisions API nedir?

Gemini Decisions API, metin üretmek yerine kapalı küme sorularını yanıtlayan Gemini Developer API'nin (v1beta) bir uç noktasıdır. Tek bir multimodal girdi ve 1.000'e kadar bağımsız soru gönderirsiniz. gemini-decision-1 modeli, tek bir ileri geçişte her seçeneği puanlar ve kodunuzun doğrudan dallanabileceği kalibre edilmiş olasılıklar döndürür.

Google, bu API'yi 11 Kasım 2026'da duyurdu. Resmi dokümantasyon üç soru tipi tanımlar:

Soru tipi	Ne için kullanın	Döndürür
`noul`	Bir ifadenin doğru olup olmadığını kontrol etmek (evet/hayır)	`noul` (0,01 ila 0,99), `confidence`
`choice`	2 ila 255 seçenek arasından birini seçmek	`choice`, `probabilities`, `confidence`
`score`	2 ila 255 sıralı düzeye göre derecelendirmek	`score`, `probabilities`, `legend`, `confidence`

Gemini API fiyatlandırma sayfasına göre fiyatlandırma: girdi tokeni başına 1M için 0,10 $ ve çıktı için 0 $. Paylaşılan girdi, kaç soru sorarsanız sorun istek başına yalnızca bir kez faturalandırılır. OpenAI Decisions API nasıl kullanılır rehberimizi okuduysanız yapı size tanıdık gelecektir, ancak aşağıdaki alanlar Gemini'ye özeldir.

Adım 1: API anahtarı alın ve SDK'yı yükleyin

Google AI Studio'yu açın ve bir API anahtarı oluşturun.
Dışa aktarın: export GEMINI_API_KEY="your-key".
SDK 3.2 veya sonrasını yükleyin: pip install -U google-genai veya npm install @google/genai@latest.

Soruları önce kod yazmadan denemek için çalıştırılabilir kod dışa aktaran Decisions Playground'u kullanabilirsiniz.

Ücretsiz katman, 12 Kasım 2026 itibarıyla kontrol edildi: hız limitleri sayfası, Ücretsiz katmanda dakikada 200 istek, dakikada 50.000 token ve günde 10.000 istek listeler. Girdi orada ücretsizdir, ancak fiyatlandırma sayfası Ücretsiz katman verilerini "Ürünlerimizi geliştirmek için kullanılır: Evet" olarak işaretler; bu yüzden gerçek müşteri verilerini ücretli bir katmanda tutun. Google'ın ücretsiz kotaları hakkında daha fazla bilgi için Gemini API ücretsiz katman rehberimize bakın.

Katman	RPM	TPM	RPD
Ücretsiz	200	50.000	10.000
Katman 1	1.500	1.000.000	50.000
Katman 2	5.000	4.000.000	Sınırsız
Katman 3	15.000	10.000.000	Sınırsız

Adım 2: İlk noul (evet/hayır) sorunuzu sorun

Bir noul sorusu, cevabın evet olma olasılığını döndürür. v1beta API sürümüne dikkat edin: uç nokta v1'de bulunmuyor.

Python:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
    questions={
        "is_damaged": {
            "type": "noul",
            "instructions": "Did the item arrive damaged?",
        },
    },
)

answer = result.answers["is_damaged"]
print(f"P(yes)={answer.noul:.2f} confidence={answer.confidence:.2f}")

JavaScript:

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

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: "The blue mug I ordered on Monday arrived cracked on Wednesday.",
  questions: {
    is_damaged: { type: "noul", instructions: "Did the item arrive damaged?" },
  },
});

const answer = result.answers?.is_damaged;
if (answer?.type === "noul") console.log(answer.noul, answer.confidence);

REST:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": "The blue mug I ordered on Monday arrived cracked on Wednesday.",
    "questions": {
      "is_damaged": { "type": "noul", "instructions": "Did the item arrive damaged?" }
    }
  }'

Google'ın dokümantasyonu bu yanıtı gösteriyor (dokümandan bir örnek, bizim bir çalıştırmamız değil):

{
  "answers": { "is_damaged": { "type": "noul", "noul": 0.99, "confidence": 0.99 } },
  "usage": { "total_input_tokens": 100, "total_output_tokens": 0, "total_tokens": 100 }
}

"Evet"in belirsiz olduğu durumlarda, bir true_description ve bir false_description ile birlikte criteria ekleyin. Akılda tutulması gereken bir kural: noul değerleri her zaman 0,01 ile 0,99 arasındadır, bu yüzden 0,99'un üzerinde bir eşik asla eşleşmez.

Adım 3: choice ve score soruları ekleyin

Aynı girdi hakkındaki bağımsız soruları tek bir isteğe koyun. Girdi bir kez faturalandırılır; her soru yalnızca kendi tokenlerini ekler.

result = client.decisions.create(
    model="gemini-decision-1",
    input="I was charged twice for my order and the export page crashes in Safari.",
    questions={
        "department": {
            "type": "choice",
            "instructions": "Which department should handle this request?",
            "criteria": {
                "billing": "Payments, invoices, and refunds.",
                "technical": "Problems using the product.",
                "shipping": "Delivery and tracking.",
                "other": "Anything outside these categories.",
            },
        },
        "severity": {
            "type": "score",
            "instructions": "How severe is this issue for the user?",
            "criteria": [
                "Cosmetic: appearance only, no lost functionality.",
                "Workaround available: a task fails, but another way works.",
                "Fully blocked: a task fails with no workaround.",
            ],
        },
    },
)

Dokümandaki üç detay insanları zorluyor:

Choice anahtarları puanlamadan önce alfabetik olarak sıralanır. Her şeye yakalayan bir seçenek için none_of_the_above değil other kullanın; none_of_the_above, gerçek seçeneklerin önüne sıralanır.
Score kriterleri bir listedir, en düşükten en yükseğe sıralı ve 0'dan indekslenir. Döndürülen score, olasılıkla ağırlıklandırılmış bir ortalamadır, bu yüzden düzeyler arasında bir değer alabilir (doküman 1.12 gösteriyor).
Model, soru anahtarlarınızı asla görmez. Sorunun tamamını instructions içinde yazın.

Bir score'dan kesirli bir düzey elde etmek için en yüksek olasılıklı girişi alın:

sev = result.answers["severity"]
level = max(sev.probabilities, key=sev.probabilities.get)
print(sev.legend[level])

Adım 4: Görsel, PDF ve ses gönderin

input, bir dize, tek bir içerik bloğu veya bir blok listesi alır; Interactions API ile aynı blok biçiminde. Desteklenen bloklar: text, image, audio, video ve document (yalnızca PDF).

import base64

with open("earcup.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")
with open("return-form.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode("utf-8")

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {"type": "text", "text": "Customer photo and form for return #8821.\n"},
        {"type": "image", "data": image_b64, "mime_type": "image/jpeg", "resolution": "low"},
        {"type": "document", "data": pdf_b64, "mime_type": "application/pdf"},
    ],
    questions={
        "visible_damage": {
            "type": "noul",
            "instructions": "Does the photo show physical damage to the device? Ignore the packaging.",
        },
        "form_signed": {
            "type": "noul",
            "instructions": "Is the return form in the PDF signed by the customer?",
        },
    },
)

Ses için, {"type": "audio", "uri": "<https-url>", "mime_type": "audio/mp3"} gibi bir blok gönderin. Bilinmesi gereken sınırlar:

Satır içi base64 verisi istek başına 100 MB ile sınırlıdır (PDF'ler için 50 MB); harici URL'ler her biri 15 MB'dir.
Gerçek MIME tipini ayarlayın. API, application/octet-stream'i reddeder.
YouTube URL'leri ve gs:// URI'leri desteklenmez. Files API'yi, herkese açık veya imzalı bir HTTPS URL'sini ya da satır içi baytları kullanın.
resolution (low, medium, high, ultra_high), görsel detayı tokenlerle takas eder. ultra_high yalnızca görseller içindir.

Adım 5: Olasılıkları ve güveni okuyun

Her cevap, 0'dan 1'e kadar bir confidence yani en üst cevabın doğru olma tahmini olasılığını taşır. choice ve score için, bu en üst sonucun olasılığına eşittir. noul için, max(noul, 1 - noul)'dur.

Böylece 0,03'lük bir noul, 0,97 güvene sahiptir: model, cevabın hayır olduğundan emindir.

Adım 6: Düşük güvenli cevapları bir yedek mekanizmaya yönlendirin

Bir eylem seçmek için değeri, eylemi otomatik yapılıp yapılmayacağına karar vermek için güveni kullanın:

a = result.answers
dept = a["department"]

if dept.confidence >= 0.7 and dept.choice != "other":
    route_to(dept.choice)
elif dept.confidence >= 0.4:
    route_to_fallback_model(ticket)   # a bigger model reasons it out
else:
    route_to("human_review")

0,7 ve 0,4 eşikleri yer tutucudur: Google, eşikleri kendi trafiğinizden etiketlenmiş örneklerden belirlemenizi önerir. Dokümandan iki kural daha:

Choice soruları, hiçbiri uymasa bile olasılığı seçenekleriniz arasında böler. Bunları "Bu mesaj bir sipariş hakkında mı?" gibi bir kapsam kontrolüyle eşleştirin.
Girdiyi güvenilmez kabul edin. Bir kullanıcının mesajı, kendi sınıflandırması için argüman ileri sürebilir. Ödemeler ve diğer yüksek riskli eylemler için bir insanı veya ikinci bir kontrolü devrede tutun.

Flowchart of confidence-based routing: a Decisions API answer with confidence of 0.7 or higher runs automatically, 0.4 to 0.7 goes to a fallback model, and below 0.4 goes to human review

Adım 7: Kodlama ajanınızın Apidog CLI ile test etmesine izin verin

Bir yönlendirme katmanı sessizce başarısız olur. Biri bir kriteri yeniden ifade eder, billing, taleplerinizin yarısı için technical olur ve hiçbir şey hata vermez. Çözüm, beklenen kararları sabitleyen bir regresyon paketidir; kodlama ajanınız bunu siz incelerken Apidog CLI ile oluşturabilir.

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Ardından ajanınıza tek bir istem verin:

In Apidog project <id>, build a test suite for POST
https://generativelanguage.googleapis.com/v1beta/decisions (header x-goog-api-key
from env var GEMINI_API_KEY). Add one request per question type (noul, choice,
score) asserting status 200, confidence between 0 and 1 and zero output tokens.
Add a test data set of 20 tickets with expected departments and assert each
choice matches with confidence >= 0.7. Run it and summarize failures.

Ajan her payload şemasını okur, doğrular, kaynakları yazar ve paketi çalıştırır:

apidog cli-schema get test-scenario-create
apidog cli-schema validate test-scenario-create --file scenario.json
apidog test-scenario create --project <id> --file scenario.json
apidog test-data create --project <id> --file tickets.json
apidog test-suite create --project <id> --file suite.json
apidog run --test-suite <suiteId> --project <id> -e <envId> -d <testDataId> -r cli,junit --out-dir reports

Yukarıdaki her bayrak, CLI 2.2.12 üzerindeki apidog run --help çıktısından gelir. Artık bir fixture'ın kararını değiştiren bir istem veya kriter değişikliği çalıştırmayı başarısız kılar. Aynı apidog run ... -r cli,junit komutunu GitHub Actions'a ekleyin; JUnit dosyası hangi talebin değiştiğini gösterir. Apidog CLI CI/CD rehberimizde workflow dosyası var; Claude Code'da Apidog CLI ise ajan kurulumunu ele alıyor. Apidog'un Ücretsiz planı 4 kullanıcıya kadar kapsar.

Sınırlar ve henüz desteklenmeyenler

Decisions API sınırlarından, 12 Kasım 2026 itibarıyla kontrol edildi:

İstek başına 1 ila 1.000 soru, 262.144 tokenlik bir bağlam penceresi içinde.
Bağlam önbelleğe alma yok, Batch API yok, Flex veya Priority çıkarımı yok. İstekler arasında tekrarlanan girdi tam olarak faturalandırılır.
Güvenlik engellemeleri, bir cevap yerine safety veya prohibited_content gibi bir error.code ile HTTP 400 döndürür.
Yalnızca Gemini Developer API (v1beta). Google, Vertex AI desteğinin "yakında" geleceğini, ancak bir tarih vermeden söylüyor.

Google, uçtan uca 150 ila 250 ms gecikme bildirir; 16K token'e kadar girdilerde 1'den 100 soruya kadar neredeyse sabittir ve Gemini Decision 1'in kendi benchmark setinde en düşük kalibrasyon hatasıyla önde olduğunu söylüyor. Bunlar Google'ın rakamlarıdır; bunlara dayanarak tasarım yapmadan önce kendi girdilerinizle gecikmeyi ölçün.

SSS

Gemini Decisions API ücretsiz mi? Girdinin ücretsiz olduğu, dakikada 200 istek, dakikada 50.000 token ve günde 10.000 istekle sınırlı bir Ücretsiz katman var (12 Kasım 2026 itibarıyla kontrol edildi). Ücretsiz katman verileri, Google'ın ürünlerini geliştirmek için kullanılabilir. Ücretli katman, 1M girdi tokeni başına 0,10 $'dır.

noul ne anlama geliyor? Evet/hayır soru tipidir. noul alanı, cevabın evet olma olasılığıdır; 0,01 ile 0,99 arasındadır.

Hangi API sürümüne ihtiyacım var? v1beta. Python'da http_options={"api_version": "v1beta"}, JavaScript'te apiVersion: "v1beta" ayarlayın veya REST üzerinden /v1beta/decisions çağrısı yapın.

Vertex AI'da çalışıyor mu? Henüz hayır. Yalnızca Gemini Developer API'de bulunuyor; Google, Google Cloud'da Gemini'yi "yakında" olarak listeliyor.

Bir güven eşiğini nasıl seçerim? Birkaç yüz gerçek girdiyi etiketleyin, API'den geçirin ve yanlış otomatik eylemlerin maliyeti, insan incelemesinin maliyetine eşit olduğu kesme noktasını seçin.