Most of the time you ask an AI model a question, you do not want an essay back. You want “yes”, “billing” or “7 out of 10”, so your code can pick a branch and move on. Google’s new Gemini Decisions API is built for exactly that, and it charges nothing for output.
This guide shows you how to make your first call in Python and curl, read the three kinds of answer, and avoid the traps Google documents. It reflects Google’s docs as of 15 November 2026. We syntax-checked the Python and curl samples (the code compiles and the JSON body parses). Live calls need your own API key, so the sample outputs below are the ones shown in the docs.
What the Decisions API actually is
Google launched it on 11 November 2026 with a model called Gemini Decision 1 (gemini-decision-1). Instead of writing text, the model scores the options you give it and returns probabilities. Google says one request can carry up to 1,000 questions about a shared input, and puts median end-to-end latency at 150 to 250 milliseconds for inputs up to 16K tokens.
Pricing is $0.10 per million input tokens, and output is always zero tokens. Shared input is billed once per request, however many questions you ask. There is a free tier in Google AI Studio, where Google’s pricing page says your data may be used to improve its products. The paid tier says it is not.
Simon Willison noted that Google’s model sits in a small category with two rivals. By his account, Gemini Decision 1 costs the same as OpenAI’s GPT-6 Luna decision model, while a model called Jev is cheaper at 4.2 cents per million. He also found a quirk: Jev and OpenAI return a flat 1.0 or 0.0 for yes/no questions, while Gemini returned softer numbers such as 0.92 and 0.05.
What you need
- A Gemini API key from Google AI Studio.
- Python with the Google GenAI SDK, version 3.2 or later. JavaScript users need
@google/genai. - Any HTTP client, if you would rather skip the SDK.
Step 1: Install the SDK and set your key
pip install -U google-genai
export GEMINI_API_KEY=your-key-here
The curl example in Google’s docs reads the key from GEMINI_API_KEY. For a wider look at calling Gemini from Python, JavaScript and curl, see our Gemini 4 Hydrogen API guide.
Step 2: Ask your first yes/no question
This is the quickstart from Google’s docs. Save it as decisions.py:
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}")
Run python decisions.py. The docs show a response of 0.99 for both the probability of yes and the confidence, with total_output_tokens at 0. The key you choose (is_damaged) is only a label. The model never sees it, so put the whole question in instructions.
Step 3: Try it with curl
The API is one POST request, so no SDK is required:
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?"
}
}
}'
Step 4: Learn the three question types
| Type | Use it to | Needs criteria? | You get back |
|---|---|---|---|
noul | Check a yes/no statement | No | noul (0.01 to 0.99), confidence |
choice | Pick one option from 2 to 255 | Yes, a map of option to description | choice, probabilities, confidence |
score | Rate against ordered levels, from 0 | Yes, a list of levels | score, probabilities, legend, confidence |
A choice question looks like this (the docs’ example input is “I was charged twice for my order.”):
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.",
},
},
}
The score value is the probability-weighted average of the level numbers, so it can land between levels. Flavio Copes’s write-up shows 1.12 on a three-level scale.
Step 5: Let confidence decide who acts
Every answer carries a confidence from 0 to 1, the estimated probability that the top answer is right. Google suggests using the answer to pick an action and confidence to decide whether code runs it:
answer = result.answers["department"]
if answer.confidence >= 0.7:
route_to(answer.choice)
else:
route_to("human_review")
Here route_to is your own function. Google says to set thresholds from labeled examples of your own traffic, not to copy 0.7.
Step 6: Batch your questions
Put independent questions about the same input in one request. The shared input is counted once, and the types can be mixed. Google’s example routes a support ticket with a yes/no defect check, a four-way action choice and a four-level churn score in a single call. The questions cannot see each other.
Limits worth knowing
| Limit | Value |
|---|---|
| Questions per request | 1 to 1,000 |
| Context window | 262,144 tokens, input plus questions |
| Free tier | 200 requests per minute, 10,000 per day |
| Tier 1 | 1,500 requests per minute, 50,000 per day |
Common errors and fixes
- Nothing happens when you check for certainty. Yes/no probabilities always fall between 0.01 and 0.99, so a test for
noul > 0.99never matches. Set thresholds inside that range. - Junk input still gets a label. Choice questions spread probability across your options even if none fits. Add an
otheroption with a description and check confidence. - Your catch-all is not last. The API sorts option keys alphabetically, so
none_of_the_abovelands beforeshipping, not last. Use a described catch-all such asother. - A 400 error. It comes back when you break a limit, fail key validation, or trip the safety filters. The error body names a
codesuch assafety. - Media will not load. YouTube URLs and
gs://addresses are not supported. Use a Files API URI, a public or signed HTTPS link, or inline base64 data. - Your bill creeps up on a long document. There is no context caching or Batch API, so repeated input counts in full. Ask every question in one request instead.
- Odd results from user text. Google warns that input can argue for its own classification. Keep a person or a second check in front of anything that moves money.
- Setup trouble. Check you have SDK 3.2 or later and the
v1betaAPI version before debugging anything else. The docs say the API is available on v1beta only.
When to use something else
Use the Decisions API for routing, filtering and rule checks with a fixed set of answers. When you need generated text, summaries, or values that follow your own JSON schema, Google points you to the Interactions API instead. If you prefer to keep models on your own hardware, our Ollama guide shows that route.
Sources
Links last checked on 15 November 2026.





Write a response