Decisions

A decision model does not write text. It reads one input and answers a set of questions you define, each with a closed set of possible answers, and returns a probability for every answer. Typical uses are routing, triage, moderation and policy checks, tool selection, and scoring against a rubric.

AI Gateway serves the three decisions APIs that exist today, each with its own request and response shape, and translates between them:

The contract is how your application talks to the gateway; it does not choose the provider. A public model is a pool of decisions deployments, and any of the three contracts can reach any deployment in it: a request in Gemini's shape can be answered by OpenAI's gpt-6-luna, and an OpenAI-shaped request can be answered by TypeSafe's Jev.

Each provider's decisions API accepts only its own decision models. Running decisions on a general chat model (emulating them with structured output and log probabilities) is not supported yet.

Question kinds

The three APIs share three kinds of question under different names; TypeSafe adds a fourth.

OpenAI returns answers as a list in question order; Gemini and TypeSafe return a map keyed by the question names you chose. The gateway keeps each contract's own convention whatever provider answered.

A box question can only be asked through /v1/systemone and is only answered by a Jev 1.14 deployment (jev-1.14.0, jev-latest, or OpenRouter's typesafe/jev-1.14).

OpenAI contract

from openai import OpenAI

client = OpenAI(base_url=f"{GATEWAY}/v1", api_key=API_KEY)

decision = client.decisions.create(
    model="triage",
    input="My card was charged twice for the March invoice, please reverse one.",
    questions=[
        {"type": "predicate", "name": "wants_refund",
         "instructions": "The customer asks for money back."},
        {"type": "choice", "name": "team",
         "instructions": "Which team should own this ticket?",
         "choices": [{"value": "billing"}, {"value": "technical"}, {"value": "other"}]},
        {"type": "score", "name": "urgency",
         "instructions": "How urgent is this ticket?",
         "levels": [{"label": "routine"}, {"label": "same day"}, {"label": "churn risk"}]},
    ],
)

Unknown fields return 400. The response carries model (the public name), answers in question order (predicate, choice, score, or refusal for a question the model declined), and usage with input_tokens, input_tokens_details.cached_tokens/cache_write_tokens, output_tokens, output_tokens_details.reasoning_tokens and total_tokens.

Gemini contract

The path keeps Google's version prefix so Google's SDKs only need a different base URL. The gateway accepts the key in x-goog-api-key, as well as Authorization: Bearer and x-api-key.

from google import genai

client = genai.Client(
    api_key=API_KEY,
    http_options={"base_url": GATEWAY, "api_version": "v1beta"},
)

decision = client.decisions.create(
    model="triage",
    input="My card was charged twice for the March invoice, please reverse one.",
    questions={
        "wants_refund": {"type": "noul", "instructions": "Is the customer asking for money back?"},
        "team": {"type": "choice", "instructions": "Which team should own this ticket?",
                 "criteria": {"billing": "Invoices and charges.", "technical": "", "other": ""}},
        "urgency": {"type": "score", "instructions": "How urgent is this ticket?",
                    "criteria": ["Routine.", "Needs a same-day reply.", "The customer threatens to leave."]},
    },
)

The response carries answers keyed by question name (each with confidence), usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), and prompt_feedback when the input was blocked.

TypeSafe contract

import requests

decision = requests.post(
    f"{GATEWAY}/v1/systemone",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "triage",
        "state": {"ticket": "My card was charged twice for March.", "plan": "pro"},
        "questions": {
            "refund": {"type": "noul", "instructions": "The customer asks for money back."},
            "tone": {"type": "choice", "criteria": {"angry": None, "calm": None, "confused": None}},
        },
    },
).json()

The body may also be multipart/form-data: a request part with the JSON, then one part per image, named by the asset's part field. Bodies are capped at 32 MiB, TypeSafe's own limit. The response carries model, answers keyed by question name, and usage.input_tokens/output_tokens. A question a non-TypeSafe provider refused comes back as { "type": "refusal" }, as OpenRouter does.

Translation between providers

The three APIs do not carry the same information, so a request crossing from one shape to another changes in these places:

• Conversation and tools. Gemini and TypeSafe take a single input. A lone user message passes through as is; anything richer (system or developer messages, earlier assistant turns, tool calls and results) becomes one input with each item labeled by role, such as System: or Tool result (call_1):.
• Structured input. OpenAI's input_json and TypeSafe's structured state become JSON text for Gemini. TypeSafe receives them as JSON.
• Yes/no criteria. OpenAI predicates have no criteria, so a noul question's true_description/false_description (or TypeSafe's criteria.true/false) are appended to its instructions as True when: and False when:.
• Score levels. Gemini and TypeSafe name a level with one string, so an OpenAI level becomes label: description. In the other direction, a level without a label is shown by its description.
• Choice values. OpenAI choices are typed; Gemini and TypeSafe key options by text. A question whose options include both "true" and true cannot go to them.
• Question names. A name the upstream cannot take (OpenAI allows any string or none) is replaced upstream by q<index>; answers always come back under the name you sent.
• Media. Audio, video and documents are only accepted by Gemini. Images inside questions are only accepted by OpenAI and TypeSafe. TypeSafe and OpenRouter take images only as inline PNG or JPEG (TypeSafe up to 16 MiB each); an image URL can only go to OpenAI or Gemini.
• Refusals. OpenAI refuses per question; Gemini blocks the whole input. A Gemini-shaped response leaves a refused question out of answers, and reports a request where every question was refused as prompt_feedback with block_reason.
• Azure OpenAI documents only user messages of text and images, and none of OpenAI's caching or end-user fields. Its requests carry the whole input as one user message labeled by role, like Gemini's, and leave out prompt_cache_key, prompt_cache_options and safety_identifier.
• Box questions have no equivalent outside Jev 1.14.

Routing and validation

Every decision model declares a decision.create profile in its catalog entry: the question kinds it answers, its input modalities, what it accepts inside questions, and its documented limits (see Model catalog). Before routing, each deployment in the pool is checked against the request: question kinds and counts, choice and level counts, input modalities, and the media its transport accepts. A deployment that cannot answer the request as asked is skipped, and the router uses the rest of the pool. When none can, the request fails with 400 and unsupported_parameter, naming what no deployment supports.

Every response is checked before it is returned: one answer per question, each of the kind asked or a refusal, probabilities between 0 and 1, a known chosen option and a finite score. A response that fails becomes a retryable upstream_protocol_error, penalizes that deployment and lets the router retry or fall back.

The endpoints never stream and never use the response cache. The default execution policy is 60 seconds to the first response, 3 minutes in total and at most three attempts, configurable as the decisions entry of the router settings. Canonical request and response extensions run on decisions like on the other operations.

Errors

Each route answers errors in its own API's shape:

Pricing and observability

Decision models bill input tokens. The catalog prices Gemini Decision 1 at $0.10 and Jev at $0.042 per million input tokens, with free output. gpt-6-luna uses that model's catalog rates, on OpenAI and on Azure OpenAI alike. OpenRouter models carry no catalog price: the cost OpenRouter reports for each request is the accounting fallback, unless the deployment sets its own pricing.

Operation logs keep the request's shape, never its content: the number of input items and parts by type, the input text size, the number of questions by kind, the answer kinds, usage and cost.

Deployments

{
  "publicModel": "triage",
  "adapterKey": "googleaistudio",
  "upstreamModel": "gemini-decision-1",
  "credentials": { "apiKey": "..." }
}

Add openai or azureopenai with gpt-6-luna, typesafe with jev-1.14.0 or openrouter with typesafe/jev-1.14 under the same publicModel to build a mixed pool. TypeSafe's long context (262,144 tokens instead of 65,536) is opt-in: send its header from the deployment with "credentials": { "apiKey": "...", "headers": { "TypeSafe-Danger-Zone-Long-Context": "true" } }. The gateway adds TypeSafe-Danger-Zone-Images: true by itself to requests with images or box questions.

Next steps

• TypeSafe provider — credentials, models and image limits.
• Creating deployments — a mixed decisions pool.
• Model catalog — the decision.create profile.
• Routing — retries, fallback, health and price strategy.