Cara Menggunakan Gemini Decisions API

Untuk menggunakan Gemini Decisions API, dapatkan API key di Google AI Studio, instal google-genai versi 3.2 atau lebih baru, lalu panggil client.decisions.create() dengan model gemini-decision-1, satu input bersama, dan sebuah map berisi questions bertipe (noul, choice, atau score). Anda akan mendapatkan probabilitas terkalibrasi beserta confidence untuk setiap pertanyaan, tanpa output token sama sekali.

Di bawah ini: setiap langkah dalam Python, JavaScript, dan REST, mulai dari pertanyaan ya/tidak pertama Anda hingga confidence routing dan test suite CI.

Apa itu Gemini Decisions API?

Gemini Decisions API adalah endpoint di Gemini Developer API (v1beta) yang menjawab pertanyaan dengan pilihan tertutup alih-alih menghasilkan teks. Anda mengirim satu input multimodal dan hingga 1.000 pertanyaan independen. Model gemini-decision-1 menilai setiap opsi dalam satu forward pass dan mengembalikan probabilitas terkalibrasi yang bisa langsung dipakai kode Anda untuk percabangan.

Google mengumumkannya pada 11 November 2026. Dokumentasi resminya mendefinisikan tiga tipe pertanyaan:

Harganya $0,10 per 1M input token dan $0 untuk output, sesuai halaman harga Gemini API. Input bersama ditagih sekali per request, berapa pun jumlah pertanyaan Anda. Jika Anda sudah membaca panduan kami tentang cara menggunakan OpenAI Decisions API, bentuknya akan terasa familier, tapi field di bawah ini adalah milik Gemini sendiri.

Langkah 1: Dapatkan API key dan instal SDK

1. Buka Google AI Studio dan buat API key.
2. Ekspor: export GEMINI_API_KEY="your-key".
3. Instal SDK versi 3.2 atau lebih baru: pip install -U google-genai atau npm install @google/genai@latest.

Anda bisa mencoba pertanyaan tanpa kode terlebih dahulu di Decisions Playground, yang bisa mengekspor kode yang langsung bisa dijalankan.

Free tier, dicek pada 12 November 2026: halaman rate limits mencantumkan 200 request per menit, 50.000 token per menit, dan 10.000 request per hari pada Free tier. Input di sana gratis, tapi halaman harga menandai data Free tier sebagai “Used to improve our products: Yes”, jadi simpan data pelanggan sungguhan di tier berbayar. Untuk info lebih lanjut tentang kuota gratis Google, lihat panduan Gemini API free tier kami.

Langkah 2: Ajukan pertanyaan noul (ya/tidak) pertama Anda

Pertanyaan noul mengembalikan probabilitas bahwa jawabannya adalah ya. Perhatikan versi API v1beta: endpoint ini tidak ada di v1.

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

Dokumentasi Google menampilkan respons ini (contoh dari dokumen, bukan hasil uji kami):

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

Ketika “ya” bersifat ambigu, tambahkan criteria dengan true_description dan false_description. Satu aturan yang perlu diingat: nilai noul selalu berada di antara 0,01 dan 0,99, jadi ambang batas di atas 0,99 tidak akan pernah terpenuhi.

Langkah 3: Tambahkan pertanyaan choice dan score

Letakkan pertanyaan-pertanyaan independen tentang input yang sama dalam satu request. Input ditagih sekali; setiap pertanyaan hanya menambah token miliknya sendiri.

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

Tiga detail dari dokumentasi yang sering membuat orang keliru:

• Key pilihan diurutkan secara alfabetis sebelum dinilai. Gunakan other sebagai catch-all, bukan none_of_the_above, yang urutannya berada di depan opsi sungguhan.
• Criteria untuk score berupa list, diurutkan dari terendah ke tertinggi dan diindeks mulai dari 0. score yang dikembalikan adalah rata-rata tertimbang probabilitas, jadi bisa jatuh di antara dua tingkat (dokumentasi menunjukkan 1.12).
• Model tidak pernah melihat key pertanyaan Anda. Tulis pertanyaan lengkap di instructions.

Untuk mendapatkan tingkat diskrit dari sebuah score, ambil entri dengan probabilitas tertinggi:

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

Langkah 4: Kirim gambar, PDF, dan audio

input menerima string, satu content block, atau list berisi beberapa block, dengan format block yang sama seperti Interactions API. Block yang didukung adalah text, image, audio, video, dan document (hanya 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?",
        },
    },
)

Untuk audio, kirimkan block seperti {"type": "audio", "uri": "<https-url>", "mime_type": "audio/mp3"}. Batasan yang perlu diketahui:

• Data base64 inline dibatasi 100 MB per request (50 MB untuk PDF); URL eksternal 15 MB masing-masing.
• Gunakan MIME type yang sebenarnya. API menolak application/octet-stream.
• URL YouTube dan URI gs:// tidak didukung. Gunakan Files API, URL HTTPS publik atau bertanda tangan, atau byte inline.
• resolution (low, medium, high, ultra_high) menukar detail visual dengan token. ultra_high hanya untuk gambar.

Langkah 5: Membaca probabilitas dan confidence

Setiap jawaban membawa confidence dari 0 hingga 1, yaitu perkiraan peluang bahwa jawaban teratas benar. Untuk choice dan score, nilainya sama dengan probabilitas hasil teratas. Untuk noul, nilainya adalah max(noul, 1 - noul).

Jadi, noul sebesar 0,03 memiliki confidence 0,97: model yakin jawabannya adalah tidak.

Langkah 6: Alihkan jawaban ber-confidence rendah ke fallback

Gunakan nilainya untuk memilih tindakan dan confidence-nya untuk memutuskan apakah tindakan dijalankan otomatis:

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")

Ambang 0,7 dan 0,4 hanyalah placeholder: Google menyarankan menetapkan ambang batas dari contoh berlabel traffic Anda sendiri. Dua aturan lagi dari dokumentasi:

• Pertanyaan choice selalu membagi probabilitas ke seluruh opsi Anda, bahkan ketika tidak ada yang cocok. Padukan dengan pemeriksaan cakupan seperti “Apakah pesan ini berkaitan dengan pesanan?”
• Perlakukan input sebagai sesuatu yang tidak terpercaya. Pesan pengguna bisa berargumen untuk klasifikasinya sendiri. Pertahankan manusia atau pemeriksaan kedua untuk pembayaran dan tindakan berisiko tinggi lainnya.

Langkah 7: Biarkan coding agent Anda mengujinya dengan Apidog CLI

Layer routing bisa gagal secara senyap. Seseorang mengubah kata-kata satu kriteria, billing berubah menjadi technical untuk separuh tiket Anda, dan tidak ada error yang muncul. Solusinya adalah regression suite yang mengunci keputusan yang diharapkan, dan coding agent Anda bisa membangunnya dengan Apidog CLI sementara Anda melakukan review.

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

Lalu berikan satu prompt ke agent Anda:

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.

Agent membaca skema setiap payload, memvalidasinya, menulis resource-nya, dan menjalankan suite:

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

Setiap flag di atas berasal dari apidog run --help pada CLI 2.2.12. Sekarang perubahan prompt atau criteria yang membalik keputusan sebuah fixture akan membuat run gagal. Masukkan apidog run ... -r cli,junit yang sama ke GitHub Actions dan file JUnit akan menunjukkan tiket mana yang berubah; panduan CI/CD Apidog CLI kami memuat file workflow-nya, dan Apidog CLI in Claude Code membahas setup agent-nya. Paket Free Apidog mencakup hingga 4 pengguna.

Batasan dan fitur yang belum didukung

Dari batasan Decisions API, dicek pada 12 November 2026:

• 1 hingga 1.000 pertanyaan per request, dalam context window 262.144 token.
• Tidak ada context caching, tidak ada Batch API, tidak ada inferensi Flex atau Priority. Input yang berulang antar request ditagih penuh.
• Blokiran safety mengembalikan HTTP 400 dengan error.code seperti safety atau prohibited_content, bukan sebuah jawaban.
• Hanya di Gemini Developer API (v1beta). Google menyatakan dukungan Vertex AI “segera hadir”, tanpa tanggal.

Google melaporkan latensi end-to-end 150 hingga 250 ms, hampir datar dari 1 hingga 100 pertanyaan untuk input hingga 16K token, dan mengatakan Gemini Decision 1 memimpin rangkaian benchmark mereka sendiri dengan error kalibrasi terendah. Itu angka-angka Google; ukur latensi pada input Anda sendiri sebelum merancang sistem berdasarkan angka tersebut.

FAQ

Apakah Gemini Decisions API gratis? Ada Free tier dengan input gratis, dibatasi 200 RPM, 50.000 TPM, dan 10.000 request per hari (dicek pada 12 November 2026). Data Free tier bisa digunakan untuk meningkatkan produk Google. Tier berbayar seharga $0,10 per 1M input token.

Apa arti noul? Itu adalah tipe pertanyaan ya/tidak. Field noul adalah probabilitas bahwa jawabannya ya, di antara 0,01 dan 0,99.

Versi API apa yang saya butuhkan? v1beta. Set http_options={"api_version": "v1beta"} di Python, apiVersion: "v1beta" di JavaScript, atau panggil /v1beta/decisions lewat REST.

Apakah bisa dipakai di Vertex AI? Belum. Ini hanya tersedia di Gemini Developer API; Google mencantumkan Gemini di Google Cloud sebagai segera hadir.

Bagaimana cara memilih ambang confidence? Beri label pada beberapa ratus input sungguhan, jalankan lewat API, lalu pilih ambang batas di mana biaya tindakan otomatis yang salah sebanding dengan biaya review manusia.