What Is the OpenAI Decisions API?
Most AI APIs answer in words. You ask a question, the model writes a paragraph, and your code then has to extract the actual answer from that paragraph — usually with a regular expression, a JSON parser, and a quiet prayer that the model kept the same format.
The OpenAI Decisions API skips that step entirely. It does not generate text at all. Instead, it returns a typed verdict: a probability, a choice from a list you define, or a score against a rubric you define. Your application gets a number it can act on immediately — no parsing, no cleanup.
OpenAI opened the Decisions API in public beta on October 6, 2026, at a dedicated endpoint, POST /v1/decisions. During the beta it runs on a single model, gpt-6-luna, and OpenAI says it expects general availability "in the coming weeks." OpenAI claims answers arrive about 10 times faster than through its standard Responses API, and you pay only for input tokens. That speed figure is OpenAI's own claim — no benchmark has been published to verify it.
How It Works: Three Question Types
A request has three parts: the model, the input (the evidence — a text string, or messages mixing text and images), and an array of questions. Each question has a unique name the API echoes back. Independent questions can share one request; a decision that depends on an earlier answer needs a separate request.
1. Predicate: how likely is this true?
A predicate checks one condition and returns a probability from 0 to 1 that it holds. OpenAI's example inspects a product photo for visible damage — crack, tear, or dent — and returns a single number, 0.92 in the docs example, which your code compares against a threshold to flag the photo for review. Use predicates for yes-or-no checks: refund requests, policy violations, duplicate bug reports.
2. Choice: pick one from a fixed list
A choice question selects one value from options you supply, each with a description of when it applies. It returns the winning choice, a probability for every option, and a separate confidence figure. OpenAI's example routes the complaint "I was charged twice for my order" to billing, technical, shipping, or other — and returns billing, with a 0.95 probability and 0.93 confidence. Include a fallback such as "other" so uncovered cases land in a review queue instead of the wrong bucket.
3. Score: rate against ordered levels
A score question evaluates input against levels you define, lowest to highest, and returns a probability-weighted average of the level indices — a score that can fall between levels. OpenAI's example rates bug severity across Cosmetic (0), Workaround available (1), and Fully blocked (2). With level probabilities of 0.1, 0.7, and 0.2, the returned score is 1.1. Use score for ordered judgments (severity, quality, urgency) and choice for unordered categories (departments, topics).
A Real Example: Routing Support Tickets
Consider a support inbox receiving thousands of messages a day. The old approach asks a chat model to reply with a department name, then parses the reply and hopes the model did not add "I believe this belongs to..." in front of it. With the Decisions API, you send the message plus two questions in one request: a choice question routing it to billing, technical, shipping, or other, and a predicate estimating the probability it is urgent. Your code gets back structured numbers, routes the ticket, and sends anything below a confidence threshold to a human reviewer.
Pricing: What Does It Cost?
Pricing is refreshingly simple. With gpt-6-luna, input costs $0.10 per 1 million tokens, and there are no cache-read, cache-write, or output-token charges — because the API produces no output tokens at all. Regional premiums and long-context multipliers still apply.
To put that in context: classifying a typical 500-token support message costs about $0.00005. One million such classifications would cost roughly $50 in input tokens — and nothing for output. One independent test, on 450 texts with three or four questions each, reported a total cost of $0.041 — consistent with the published rate.
Decisions API vs Structured Outputs
If you already use OpenAI's Structured Outputs, you might wonder what changes. Structured Outputs forces a model's free-text answer into a JSON schema you define — it guarantees the shape of the answer, but says nothing about whether the judgment inside it is right. The Decisions API returns a probability distribution over your options, which tells you how sure the model is. A probability supports a policy (auto-approve above 0.9, escalate between 0.6 and 0.9, hand to a human below 0.6), while a bare label does not.
OpenAI's own guidance draws the line clearly: use Decisions when your application needs a probability, a choice, or a score. Use Structured Outputs with the Responses API when you need an object in your own JSON shape — extracted fields, a written explanation. Use function calling when you need the model to request a tool call with arguments. The Decisions API is a classifier, not a generator.
Pros and Cons
Pros
- No parsing: typed answers arrive ready to use — no regex, no JSON repair, no format drift.
- Confidence built in: probabilities and confidence values give you thresholds and human-review queues.
- Cheap at scale: $0.10 per 1M input tokens with zero output charges.
- Fast by design: OpenAI claims about 10x faster than the Responses API.
- Images included: text, images, or both can serve as evidence in one request.
- Compliance options: Zero Data Retention and HIPAA-eligible use, with US and EU data residency.
Cons
- Beta limits: one model (
gpt-6-luna), public beta, GA still "in the coming weeks." - Unverified speed claim: the 10x figure comes with no published benchmark.
- Calibration is your job: OpenAI calls the probabilities estimates and publishes no calibration results. One independent test found them leaning low on choice questions (95% correct while the top probability averaged 0.90).
- Images must be inline base64: hosted image URLs and uploaded file IDs are not supported.
- No chaining: decisions that depend on an earlier answer need separate requests.
- No custom output shapes: for extracted fields or explanations, you still need Structured Outputs.
Who Should Use the Decisions API?
Best for: developers running high-volume classification — support ticket routing, content moderation, quality gating, lead scoring, and agent pipelines where a fast verdict picks the next step.
Less suited for: anyone who needs explanations alongside decisions, custom JSON output, or multi-model choice — and anyone uncomfortable building on a public beta. If your workflow needs the model to show its reasoning, keep using the Responses API with Structured Outputs.
Limitations and Beta Caveats
Three caveats deserve emphasis. First, the probabilities are estimates, not calibrated guarantees: OpenAI explicitly advises setting thresholds from labeled examples in your own application, weighing the cost of false positives against false negatives. Second, images must arrive as inline base64 data URLs — if your pipeline stores images as hosted URLs or OpenAI file IDs, you will need to fetch and encode them first. Third, the beta is a moving target: only gpt-6-luna is supported, general availability has no firm date, and behavior could change before GA. Prototype before rebuilding a production pipeline around it.
Verdict
The OpenAI Decisions API is a small, sharp tool that fixes a real annoyance: paying for words you never wanted, then parsing them back into the verdict you actually needed. Typed answers with probabilities, near-zero marginal cost, and a design that fits routing, moderation, and gating workloads make it one of the most practical API releases of the year. The caveats — unverified speed claims, uncalibrated probabilities, beta-only status — are real, but manageable with testing.
If your application asks a language model yes-or-no questions today, the Decisions API is worth a prototype this week. If it needs explanations, custom shapes, or model choice, the Responses API remains the right home.
Related reading: the Decisions API runs on gpt-6-luna — see our guide to ChatGPT's GPT-6 intelligent UI for the model family's consumer side, and Claude Haiku 5.5 for Anthropic's competing cheap-and-fast option. For agent workflows that need verdicts at every step, read our guide to Gemini Agent, Google's universal AI agent for work.
Frequently Asked Questions
What is the OpenAI Decisions API?
It is a dedicated endpoint, POST /v1/decisions, that answers typed questions about text or images instead of generating prose. It returns a predicate probability, a choice from a fixed list, or a score against ordered levels, each with probabilities and a confidence value. It is in public beta and runs only on gpt-6-luna.
How much does the Decisions API cost?
$0.10 per 1 million input tokens, with no charges for output tokens, cache reads, or cache writes. Regional processing premiums and long-context input pricing multipliers still apply.
How is the Decisions API different from Structured Outputs?
Structured Outputs forces a model's answer into your JSON schema — it guarantees shape, not judgment. The Decisions API returns typed answers with a probability attached, so you can build threshold policies: auto-approve, escalate, or hand to a human based on confidence.
Is the Decisions API faster than the Responses API?
OpenAI claims it produces answers about 10 times faster than the Responses API, since it generates no output tokens. The company has published no benchmark to verify that figure.
Sources: OpenAI — Decisions API guide; AI Weekly — OpenAI launches Decisions API public beta; DEV — OpenAI Decisions API: A Practical Developer's Guide; Metir — Decisions API pricing and limits.
No comments:
Post a Comment