Before you begin
Use the common Model Service authentication. The caller needsmodel.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. UseGET 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
SetAION_API_KEY to your personal API key. Replace the model ID if the live catalog no longer offers this model.
Python SDK
Importcreate_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.
/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.
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 requirestype 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.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.
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’susage 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.