2 2
3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4 4
5The Decisions API evaluates text, images, or both and returns typed answers about 10x faster than the Responses API. Get the probability that a condition is true, a choice from a fixed set, or a score against a rubric. Use those answers to classify content, route requests, and prioritize work in your application.5The Decisions API is now generally available. Review [what's new](#whats-new)
6 since the public beta.
7
8The Decisions API evaluates text, images, and JSON and returns typed answers about 10x faster than the Responses API. Get the probability that a condition is true, a choice from a fixed set, or a score against a rubric. Use those answers to classify content, route requests, and prioritize work in your application.
6 9
7Try the Decisions API in the [Playground](https://platform.openai.com/decisions) to experiment with questions and inputs before writing code.10Try the Decisions API in the [Playground](https://platform.openai.com/decisions) to experiment with questions and inputs before writing code.
8 11
9The Decisions API is in public beta, and we expect to GA in the coming weeks.12Send requests to `POST /v1/decisions` using `gpt-6-luna`, the only currently
10 `gpt-6-luna` is the only model currently available. Use the dedicated `POST13 supported model.
11 /v1/decisions` endpoint.14
15## What's new
16
17Since the public beta launched, the Decisions API has added these capabilities:
12 18
13To run the SDK examples below, use these OpenAI SDK versions or later: Python 3.26.0, JavaScript 7.30.0, Go 3.73.0, Ruby 0.101.0, and Java 4.78.0. See [OpenAI SDK](https://developers.openai.com/api/docs/libraries) for installation instructions.19- [**Prompt caching.**](#reuse-shared-input-with-prompt-caching) Reuse shared input across requests and receive cache discounts.
20- [**Images in question instructions.**](#include-images-in-question-instructions) Give each question its own images to compare against shared evidence.
21- [**JSON input.**](#evaluate-json-data) Pass structured data directly with an `input_json` content part.
22- [**More questions per request.**](#ask-multiple-questions) Ask up to 400 questions per request, up from 200 during the public beta.
23- [**Hosted image inputs.**](#check-an-image-for-visible-damage) Pass publicly accessible HTTP or HTTPS image URLs as well as inline base64 data URLs.
24- [**Conversation history.**](#evaluate-a-conversation) Evaluate messages alongside function calls, custom tool calls, and their outputs.
25- [**Organization usage reporting.**](#monitor-usage) Track token usage and request counts.
26- [**Native GPT-Live integration.**](https://developers.openai.com/api/docs/guides/decisions-voice) Let Live call Decisions directly, or trigger decisions as input or output transcripts arrive.
27- [**Private Link.**](https://developers.openai.com/api/docs/guides/private-link) Send Decisions requests over a private connection.
14 28
15## How decisions work29## How decisions work
16 30
17A request has three parts:31A request has three parts:
18 32
19| Field | Purpose |33| Field | Purpose |
20| ----------- | -------------------------------------------------------------------------------------------------------- |34| ----------- | --------------------------------------------------------------------------------------------------------------- |
21| `model` | The model that evaluates the request. Currently, only `gpt-6-luna` is supported. |35| `model` | The model that evaluates the request. Currently, only `gpt-6-luna` is supported. |
22| `input` | Shared evidence for the questions: a text string or user messages containing text and images. |36| `input` | Shared evidence for the questions: a text string or an ordered array of messages, tool calls, and tool outputs. |
23| `questions` | What to evaluate, including each question's type, instructions, and any allowed choices or score levels. |37| `questions` | What to evaluate, including each question's type, instructions, and any allowed choices or score levels. |
24 38
25The response contains an `answers` array. Give each question a unique `name` to identify its answer; the API echoes that name in the response.39The response contains an `answers` array. Give each question a unique `name` to identify its answer; the API echoes that name in the response.
36 50
37Use Decisions when your application needs one of these answer types. Use [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) with the Responses API when you need to generate an object that follows your own JSON schema, such as extracted fields or a written explanation, or [function calling](https://developers.openai.com/api/docs/guides/function-calling) when you need a model to request a tool call with arguments.51Use Decisions when your application needs one of these answer types. Use [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) with the Responses API when you need to generate an object that follows your own JSON schema, such as extracted fields or a written explanation, or [function calling](https://developers.openai.com/api/docs/guides/function-calling) when you need a model to request a tool call with arguments.
38 52
53### Evaluate a conversation
54
55Pass conversation history in `input` to evaluate a request in context. Include messages and any function or custom tool calls and outputs in order. Match each tool output to its call with `call_id`.
56
57The supported content depends on the message role or item type:
58
59| Input item | Supported content |
60| ------------------------------ | ------------------------------------------------------------------ |
61| User message | Text, images, and JSON |
62| Developer or system message | Input text only; system messages are treated as developer messages |
63| Assistant message | Output text or refusals |
64| Function or custom tool output | Text and images, associated with a matching tool call |
65
66Tool calls and outputs provide evidence for your questions. Decisions returns typed answers; your application runs any actions those answers select. Files, audio, and item references aren't supported. See the [create decision reference](https://developers.openai.com/api/reference/resources/decisions/methods/create) for accepted input fields.
67
68## Evaluate JSON data
69
70Use an `input_json` content part to pass structured evidence without first converting it to a string. Put the JSON object or array in `data`, alongside any text or image parts in a user message. Within message content, `input_json` is supported only for the `user` role.
71
72For example, send this JSON request body to `POST /v1/decisions` to evaluate a support ticket against an order record:
73
74```json
75{
76 "model": "gpt-6-luna",
77 "input": [
78 {
79 "role": "user",
80 "content": [
81 {
82 "type": "input_text",
83 "text": "Evaluate the ticket using the order evidence."
84 },
85 {
86 "type": "input_json",
87 "data": {
88 "ticket": { "body": "Please refund the duplicate charge." },
89 "order": { "charges": [49, 49] }
90 }
91 }
92 ]
93 }
94 ],
95 "questions": [
96 {
97 "type": "predicate",
98 "name": "duplicate_charge",
99 "instructions": "Does the ticket describe a duplicate charge supported by the order?"
100 }
101 ]
102}
103```
104
105JSON keys such as `role` or `image_url` inside `data` are ordinary data: they don't create messages or fetch images. The answer still uses the selected question type; JSON input doesn't change the response format.
106
39## Check an image for visible damage107## Check an image for visible damage
40 108
41Use a `predicate` question to check a product photo for visible damage. This request combines the image with instructions to look for a crack, tear, or dent.109Use a `predicate` question to check a product photo for visible damage. This request combines the image with instructions to look for a crack, tear, or dent.
315 383
316Provide images as inline base64 data URLs or publicly accessible HTTP or HTTPS URLs. This endpoint doesn't support `file_id` inputs. Combine `input_text` and `input_image` parts in a user message to evaluate images together with instructions or other context.384Provide images as inline base64 data URLs or publicly accessible HTTP or HTTPS URLs. This endpoint doesn't support `file_id` inputs. Combine `input_text` and `input_image` parts in a user message to evaluate images together with instructions or other context.
317 385
386## Include images in question instructions
387
388Put evidence that all questions share in `input`. To give each question a different image, set its `instructions` to a nonempty array of `input_text` and `input_image` parts. This works for predicate, choice, and score questions. Text-only instructions can remain a string.
389
390For example, send this JSON request body to `POST /v1/decisions` to compare a candidate against a shared reference. Replace the two example image URLs with publicly accessible images, or use base64 image data URLs:
391
392```json
393{
394 "model": "gpt-6-luna",
395 "input": [
396 {
397 "role": "user",
398 "content": [
399 {
400 "type": "input_text",
401 "text": "The shared image is reference image A."
402 },
403 {
404 "type": "input_image",
405 "image_url": "https://example.com/reference.jpg"
406 }
407 ]
408 }
409 ],
410 "questions": [
411 {
412 "type": "predicate",
413 "name": "candidate_matches_reference",
414 "instructions": [
415 {
416 "type": "input_text",
417 "text": "Is candidate image B a derivative or variant of reference image A, including recompression or resizing?"
418 },
419 {
420 "type": "input_image",
421 "image_url": "https://example.com/candidate.jpg"
422 }
423 ]
424 }
425 ]
426}
427```
428
429When adding images to question instructions:
430
431- Add another question for each candidate image. Each question evaluates its own candidate against the same shared reference.
432- Supply content parts directly in `instructions`, without a message wrapper or `role`.
433- Question images share the request's image limits with images in `input`.
434
318## Select from fixed options435## Select from fixed options
319 436
320A `choice` question selects one value from the options you provide. Use distinct values and descriptions that explain when each option applies.437A `choice` question selects one value from the options you provide. Use distinct values and descriptions that explain when each option applies.
584 701
585## Score against a rubric702## Score against a rubric
586 703
587A `score` question evaluates an input against ordered `levels`. Define the criteria for each level and arrange them from lowest to highest.704A `score` question evaluates an input against 2–10 ordered `levels`. Define the criteria for each level and arrange them from lowest to highest.
588 705
589 706
590 707
838 955
839## Ask multiple questions956## Ask multiple questions
840 957
841Put independent questions in the same `questions` array to evaluate shared input. For a product photo, you could check for damage and classify the product category in one request. Each question can use a different type.958Include between 1 and 400 questions in a request. Put independent questions in the same `questions` array to evaluate shared input. For a product photo, one request can check for damage and classify the product category. Each question can use a different type.
842 959
843For decisions that depend on an earlier answer, send separate requests. For example, check for damage first, then use the result to decide whether to request a repair category.960For decisions that depend on an earlier answer, send separate requests. For example, check for damage first, then use the result to decide whether to request a repair category.
844 961
850 967
851Use labeled examples from your application to set thresholds for routing, filtering, or review. Choose thresholds based on the cost of false positives and false negatives.968Use labeled examples from your application to set thresholds for routing, filtering, or review. Choose thresholds based on the cost of false positives and false negatives.
852 969
970## Reuse shared input with prompt caching
971
972Prompt caching lets repeated requests reuse a matching prefix of shared `input` and receive discounted cache-read pricing. For example, keep a reference document or image in `input` and change the questions for each request. Content in `questions`, including question-specific images, is outside the reusable prefix.
973
974By default, Decisions places an implicit cache breakpoint at the end of shared `input`. Existing requests can benefit without changing their request body. The reusable prefix must contain at least 1,024 tokens; question content doesn't count toward this threshold. Keep the prefix identical across requests to allow reuse.
975
976Use `prompt_cache_key` to partition cache reuse by a caller-provided key. For control over the boundary, add `prompt_cache_breakpoint: {"mode": "explicit"}` to text or image content parts in shared `input`. Set `prompt_cache_options.mode` to `"explicit"` to use only marked boundaries. In explicit mode, a request with no marked boundaries doesn't use prompt caching. Breakpoints aren't supported in question instructions.
977
978Check `usage.input_tokens_details.cached_tokens` for cache reads and `usage.input_tokens_details.cache_write_tokens` for cache writes. Both counts are included in `usage.input_tokens`; don't add them to that total. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for caching concepts and the [Decisions reference](https://developers.openai.com/api/reference/resources/decisions/methods/create) for supported request controls.
979
980## Monitor usage
981
982Use `GET /v1/organization/usage/decisions` to retrieve your organization's Decisions token usage and request counts. Authenticate with an admin API key and the `api.usage.read` permission.
983
984Choose a time range and bucket width, then filter or group the results by project, API key, or model. The `num_model_requests` field counts requests, not individual questions: a request with several questions counts once. See the [Decisions usage reference](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/usage/methods/decisions) for filters and pagination.
985
853## Pricing and availability986## Pricing and availability
854 987
855With `gpt-6-luna`, input costs **$0.10 per 1M tokens**. You pay only for input tokens: there are no cache-read, cache-write, or output-token charges.988With `gpt-6-luna`, uncached input costs **$0.10 per 1M tokens**. Prompt cache hits receive discounted input pricing; cache writes are charged. Cache-read and cache-write rates match the [standard `gpt-6-luna` prompt caching rates](https://developers.openai.com/api/docs/pricing). Output tokens are not charged.
856 989
857Regional processing premiums and long-context input pricing multipliers apply. These rates apply to `/v1/decisions`; other requests using `gpt-6-luna` follow the applicable [model and processing-tier pricing](https://developers.openai.com/api/docs/pricing).990Regional processing premiums and long-context input pricing multipliers apply. These rates apply to `/v1/decisions`; other requests using `gpt-6-luna` follow the applicable [model and processing-tier pricing](https://developers.openai.com/api/docs/pricing).
858 991
859The Decisions API supports Zero Data Retention (ZDR) and HIPAA use for eligible customers. Data residency and regional processing are supported in the United States and Europe (EEA + Switzerland). See [data controls](https://developers.openai.com/api/docs/guides/your-data) for eligibility requirements, required agreements, and limitations.992The Decisions API supports Zero Data Retention (ZDR) and HIPAA use for eligible customers. Data residency is available in all supported API regions. Regional processing is supported in the United States and Europe (EEA + Switzerland). See [data controls](https://developers.openai.com/api/docs/guides/your-data) for eligibility requirements, required agreements, and limitations.
860 993
861## Add voice control994## Add voice control
862 995
