> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Decision models

> Use the experimental Decisions API for probabilities, choices, scores, and image boxes.

> [!WARNING]
>
> The Aion Decisions API is experimental. Its contract and available model capabilities can change.

Decision models answer named questions about supplied state. They return structured values for application logic.
Use Decisions for classification, selection, assessment, and supported image localization tasks.

## Before you begin

Use the common [Model Service authentication](https://docs.aion.to/docs/resources/model-service.md#authentication).
The caller needs `model.execute` and sufficient organization credits. Personal API keys and deployment tokens use
the same permission, principal, and attribution rules as Text calls.

Inline media does not require a File Service account or a Daemon Identity beyond the existing Model Service rules.
Aion does not create files or retain request media for this operation.

## Choose a model

Open **Resources > Models**, select the **Decisions** category, and check the model's available operation and question
types.
Some catalog entries only provide metadata. An output category alone does not authorize execution.

Use `GET https://api.aion.to/alpha/decisions/models` for the verified Decisions catalog.
The response uses the existing model-list structure. Its prices use Aion credits.
The Text catalog at `/v1/models` retains its existing scope.

Models can have more than one category. Accepted input media is separate from output categories.
For example, a decision model that accepts an image does not necessarily generate images.

## Send a request

Set `AION_API_KEY` to your personal API key. Replace the model ID if the live catalog no longer offers this model.

```bash theme={null}
curl https://api.aion.to/alpha/decisions \
  -H "Authorization: Bearer $AION_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "typesafe/jev-1.14",
  "state": {"ticket": "The checkout screen is blank after I click Pay."},
  "questions": {
    "is_incident": {
      "type": "noul",
      "instructions": "Does the ticket report a defect?"
    },
    "team": {
      "type": "choice",
      "instructions": "Which team should investigate?",
      "criteria": {
        "frontend": "Rendering and layout",
        "payments": "Payment processing"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this ticket?",
      "criteria": ["Can wait", "Needs attention", "Blocking revenue"]
    }
  }
}
JSON
```

An illustrative response follows. Answer values and usage depend on the input and model.

```json theme={null}
{
  "model": "typesafe/jev-1.14",
  "answers": {
    "is_incident": {"type": "noul", "noul": 0.95},
    "team": {"type": "choice", "choice": "frontend", "confidence": 0.8},
    "urgency": {"type": "score", "score": 1.8}
  },
  "usage": {"input_tokens": 64, "output_tokens": 20, "cost": 0.000003}
}
```

The endpoint returns one JSON response. It does not provide SSE, background jobs, or a poll endpoint.
Use HTTP directly or the Python example below.

### Python SDK

Import `create_decision()` and its request and answer types from `aion.api.decisions`.
Install `aionto-sdk` and `openai` in your project. Configure
[deployment client credentials](https://docs.aion.to/docs/resources/model-service.md#deployment-client-credentials) before you run this code.

```python theme={null}
from openai import OpenAI
from aion.api import aion_openai_config
from aion.api.decisions import DecisionRequest, create_decision

config = aion_openai_config()
request: DecisionRequest = {
    "model": "typesafe/jev-1.14",
    "state": "The checkout screen is blank after I click Pay.",
    "questions": {
        "is_incident": {
            "type": "noul",
            "instructions": "Does the ticket report a defect?",
        }
    },
}

with OpenAI(**config.openai_kwargs(), timeout=60.0) as client:
    response = create_decision(client, request)
    answer = response["answers"]["is_incident"]
    if answer["type"] == "noul":
        print(answer["noul"])
```

The helper uses `/alpha/decisions` on the configured Aion host. It adds the current request attribution for each call.
The client refreshes the Aion credential.
The helper disables automatic SDK retries because Aion controls execution retries.

The caller controls the client timeout and closes the client. Aion validates the request and answers.
`DecisionRequest` and `DecisionResponse` provide static types for application code.

Use `create_decision_async()` in asynchronous agent code. This example reuses the request above.

```python theme={null}
import asyncio

from openai import AsyncOpenAI
from aion.api.decisions import (
    DecisionRequest,
    DecisionResponse,
    create_decision_async,
)
from aion.api.model_service_client import aion_jwt_api_key, aion_model_base_url

async def evaluate(request: DecisionRequest) -> DecisionResponse:
    async with AsyncOpenAI(
        base_url=aion_model_base_url(),
        api_key=aion_jwt_api_key,
        timeout=60.0,
    ) as client:
        return await create_decision_async(client, request)

# In an existing event loop, use: response = await evaluate(request)
response = asyncio.run(evaluate(request))
```

These helpers use the OpenAI client's generic HTTP transport with Aion's Decisions contract.
They do not use a native Decisions resource in that client.

The existing Aion LangGraph and Google ADK model adapters implement Text operations. Call Decisions from application
or tool code; those chat adapters and Codex do not provide a Decisions configuration.

## Request fields

| Field | Requirement and meaning |
| - | - |
| `model` | Required exact model ID from the verified catalog. |
| `state` | Required string, object, or array with the evidence for the questions. |
| `questions` | Required object with at least one named question. Each name identifies an answer. |
| `provider` | Optional routing preference object, or `null`, using the compatible API standard. |
| `session_id` | Optional string, at most 256 characters. Groups related evaluations. |
| `user` | Optional string, at most 256 characters. Request metadata only; does not select the authenticated user. |
| `trace` | Optional trace metadata object. |

`X-Session-Id` supplies a session ID only when the body omits `session_id`.
User, session, and trace fields do not change the trusted principal, organization, or payer.
Use the existing Aion attribution headers for authorized runtime attribution.

Aion rejects other top-level fields before model execution. Unsupported fields include `stream`, `models`,
`service_tier`, `temperature`, `max_tokens`, `messages`, and file-service asset references.

### Questions and answers

Each question requires `type` and `instructions`. `criteria` is optional except for types that prohibit it.
Use string instructions and simple criterion descriptions for portability.
Jev models also accept structured JSON instructions and criterion descriptions, including inline images.

| Type | Criteria | Answer |
| - | - | - |
| `noul` | Optional object with `true` and/or `false` descriptions. | `noul`: a probability from 0 to 1. |
| `choice` | Optional nonempty object with choice keys and descriptions or `null`. | `choice`: a selected key. |
| `score` | Optional ordered array with at least two levels. | `score`: a nonnegative number, which can be fractional. |
| `box` | Omit criteria. Requires a model with verified Box support. | `box`: normalized image coordinates. |

Array score criteria define a zero-based scale. Three levels permit scores from 0 to 2, including values such as 1.8.
An answer can also contain `confidence`, `probabilities`, or a score `legend`. These fields are optional.
A response can include an opaque `id`. The documented answer fields and token counts are returned when available.

Choose application thresholds for probability and confidence values. They are model estimates, not guarantees.
Aion checks answer names, types, ranges, and explicit choice or score criteria before it returns the response.

For a Box answer, coordinates range from 0 to 1. Top must not exceed bottom, and left must not exceed right.
For example, an answer value can be:

```json theme={null}
{
  "type": "box",
  "box": {"top": 0.1, "bottom": 0.9, "left": 0.2, "right": 0.8},
  "confidence": 0.9
}
```

## Transient media

Media must be inline. Aion does not fetch remote media URLs, upload media to File Service, or return durable file
references.
The request media exists only for the active request. Usage records exclude state, instructions, media, and raw answers.

The wire shapes below use placeholders. Replace each base64 placeholder with valid bytes for the declared format.

```json theme={null}
{
  "state": [
    "Assess the supplied evidence.",
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,BASE64_IMAGE"}},
    {"type": "input_audio", "input_audio": {"data": "BASE64_AUDIO", "format": "wav"}},
    {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,BASE64_VIDEO"}}
  ]
}
```

This fragment needs `model` and `questions` in a complete request. Audio and video require Clef Omni.
Other models accept image parts only where the following table permits them.
Use a plain string for text parts. The Chat Completions `{"type":"text","text":"..."}` shape is not supported here.

### Model limits

The following limits apply to Aion Decisions requests. The live catalog must also list the input modality.
Model-specific content checks can reject media within these size limits.

| Model | Question types | Inline media |
| - | - | - |
| `typesafe/jev-1.14` | Noul, Choice, Score, Box | PNG/JPEG nested in state, instructions, or criteria. |
| `typesafe/jev-1.13` | Noul, Choice, Score | Same Jev image limits. No Box. |
| `cloudflare/clef`, `cloudflare/clef-flash` | Noul, Choice, Score | 4 top-level PNG/JPEG/WebP images. |
| `cloudflare/clef-omni` | Noul, Choice, Score | 4 images, 4 audio clips, and 2 videos, all top-level. |
| `inception/mercury-decide` (including `:free`) | Noul, Choice, Score | 16 top-level PNG/JPEG/WebP images. |
| `openai/gpt-6-luna-decisions` | Noul, Choice, Score | 128 top-level PNG/JPEG/WebP images. |

Top-level media must be direct elements of the `state` array.

Size and content limits:

* Jev: at most 128 images, 16 MiB per image, and 32 MiB of processed RGBA image data.
  Each side must be 256–1568 pixels. Each image must have 78,400–2,458,624 pixels. Animated PNG is not supported.
* Clef and Clef Flash: at most 300 KiB per image. State text can be truncated near 2,000 tokens.
* Mercury Decide: at most 7 MiB per image.
* Clef Omni and GPT decisions: at most 16 MiB per image.
* Clef Omni audio: at most 8 MiB per clip. Maximum duration: 300 seconds.
  Formats include WAV, MP3, MPEG, M4A, MP4, AAC, AIFF, AIF, FLAC, OGG, Opus, and WebM. Use lowercase format values.
* Clef Omni video: at most 16 MiB per clip. Maximum duration: 60 seconds.
* Combined audio and video: at most 16 MiB of decoded bytes per request.
* All media: at most 24 MiB of decoded bytes per request, including repeated occurrences.
* Encoded request and response: at most 32 MiB each. JSON can have at most 64 nested levels.

Aion checks positions, declared formats, base64 bytes, counts, size limits, and Jev image dimensions before execution.
Media decoding and audio/video duration checks can fail during execution. Such failures can still incur a charge.

## Usage and prices

All prices in the Aion catalog and usage pages are Aion customer prices, expressed in Aion credits.
The applicable rate depends on the model, operation, and organization pricing policy.

The response's `usage` object contains token counts when available.
Its optional `cost` field is Aion's price in USD for the returned result.
Aion calculates this quote with the applicable organization policy when it returns the response.
The example cost above illustrates the response format. It is not a fixed rate.

If Aion cannot calculate the quote, it omits `usage.cost` and returns the answers.
An absent cost does not mean a free request. Token totals can also be incomplete.
The quote does not include other billable attempts and is not a final settlement receipt.
Policy changes or later usage information can change the settled charge.
Use the model's **Metrics** tab and Aion billing records to inspect settled charges in credits.

A failed request can consume credits. Each execution attempt can incur a charge, including an automatic retry.
Separate client requests are separate invocations; do not assume they are deduplicated.

## Errors and retries

Aion can retry once after a temporary execution failure or an invalid result. All attempts share a 25-second budget.
Invalid request parameters do not trigger an automatic retry.

A capacity error means no invocation slot is available. Aion does not queue the request for later execution.
A timeout or service restart can end the request. Work already performed can incur a charge even if no result arrives.

| HTTP status / code | Meaning |
| - | - |
| `400 invalid_decision_request` | Check request structure, question types, media, and model constraints. |
| `413 decision_payload_too_large` | The payload exceeds a supported limit. |
| `429 decisions_busy` | No invocation capacity is available. |
| `503 decisions_unavailable` | The service is unavailable or could not finish within its deadline. |
| `502 decision_protocol_error` | The result did not satisfy the Decisions response contract. |
| `502 decision_execution_failed` | The request could not be completed. |

Aion authentication, organization, permission, and credit errors use the
[common Model Service rules](https://docs.aion.to/docs/resources/model-service.md#troubleshoot-a-request).
Correct invalid inputs before a retry. After an availability error, apply bounded retries in your client.
Account for the risk of additional charges after ambiguous failures.

## API compatibility

Aion follows the [OpenRouter Decisions API
standard](https://openrouter.ai/docs/api/api-reference/alphadecisions/submit-a-decisions-request)
for request fields and answer shapes. Use the Aion endpoint, credentials, catalog, and limits documented here.
Aion defines authentication, usage reporting, billing, and operational limits for this service.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.