Skip to main content
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. 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.
An illustrative response follows. Answer values and usage depend on the input and model.
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 before you run this code.
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.
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

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. 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:

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.
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. 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. Aion authentication, organization, permission, and credit errors use the common Model Service rules. 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 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.