Text models

Text models accept a prompt or conversation and return text. Some models also accept images or other input media. Input support does not imply that a model can generate that media type. Use the common Model Service authentication and permissions. Choose a model with the Text operation in Resources > Models.

Usage

Open Resources > Models, select a model, and open Usage to see copyable examples populated with that model’s exact ID.

Choose a client

Option	Use it for	Authentication
HTTP API	Scripts and OpenAI-compatible Responses clients.	Personal API key
Python SDK	OpenAI-compatible clients running in an Aion deployment.	Deployment client credentials
LangGraph	LangGraph applications using an Aion-managed chat model.	Deployment client credentials
Google ADK	Google ADK applications using an Aion-managed model.	Deployment client credentials
Codex	Configuring Aion as a Responses-compatible model provider.	Personal API key

Model Service Usage tab showing the Python SDK example and deployment credential guidance

Make an HTTP request

Copy a model ID from Resources > Models. Model availability and pricing can change, so use an ID from the live catalog instead of guessing a provider model name. Replace PASTE_MODEL_ID_HERE with the model ID you copied:

curl https://api.aion.to/v1/responses \
  -H "Authorization: Bearer $AION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "PASTE_MODEL_ID_HERE",
    "store": false,
    "input": [
      {
        "role": "user",
        "content": "Summarize the latest project status."
      }
    ]
  }'

A successful request returns an OpenAI-compatible Response object containing the model output and token usage. Aion does not retain the response for later retrieval.

Use an SDK adapter

The Python SDK example uses aion_openai_config() with the OpenAI client. Framework adapters provide model objects configured for the same service:

from openai import OpenAI
from aion.api import aion_openai_config

client = OpenAI(**aion_openai_config().openai_kwargs())

response = client.responses.create(
    model="PASTE_MODEL_ID_HERE",
    input="Summarize the latest project status.",
    store=False,
)

print(response.output_text)

LangGraph Model Service uses aion_chat_model().
Google ADK Model Service uses aion_lite_llm().
Aion API provides shared authentication and Model Service configuration.

For a configurable application, an llm field in aion.yaml lets a deployer choose a model from the live catalog. Application code passes that selected model ID to its SDK adapter.

Configure Codex

Set AION_API_KEY, then add Aion as a provider in your Codex home configuration:

# $CODEX_HOME/config.toml
model = "PASTE_MODEL_ID_HERE"
model_provider = "aion"

[model_providers.aion]
name = "Aion Model Service"
base_url = "https://api.aion.to/v1"
env_key = "AION_API_KEY"
wire_api = "responses"

Provider preferences and service tiers

Both creation endpoints accept optional provider and service_tier fields. These request options do not require a different model ID or a server configuration change.

Provider preferences

Set provider.sort to choose the order in which Model Service tries providers for your selected model:

Value	Preference
`latency`	Shortest delay before the first token.
`throughput`	Highest output rate in tokens per second.
`price`	Lowest price.

Low latency helps a response start sooner. High throughput helps long responses finish sooner. These preferences do not guarantee response times or select a different model. Omit provider.sort to retain the default provider selection. A provider sort option does not enable a different service tier.

Service tiers

Set one service_tier string per request, not an array. Model Service maps these names to each provider’s capacity options:

Value	Capacity preference
`default`	Standard capacity and cost.
`flex`	Lower cost, with higher latency and lower availability.
`fast`	Faster capacity at a higher cost.
`ultrafast`	Faster capacity than `fast`, at a higher cost. Available on select models.

Availability and rates depend on the model and provider. Responses report fast as priority. With fallbacks enabled, fast can use standard capacity. ultrafast can use fast, then standard capacity. If flex endpoints exist, flex does not fall back to standard capacity. Without flex endpoints, it uses standard rates. Check the response’s service_tier for the actual tier, or null if unavailable. The actual tier determines the applicable Aion rate.

SDK examples

Use service_tier as a keyword argument and extra_body for the provider object:

from openai import OpenAI
from aion.api import aion_openai_config

client = OpenAI(**aion_openai_config().openai_kwargs())

response = client.responses.create(
    model="PASTE_MODEL_ID_HERE",
    input="Summarize the latest project status.",
    store=False,
    service_tier="fast",
    max_output_tokens=4096,
    extra_body={"provider": {"sort": "latency"}},
)

print(response.output_text)
print(response.service_tier)

The LangGraph adapter accepts the same options:

from aion.langgraph.authoring import aion_chat_openai

model = aion_chat_openai(
    model="PASTE_MODEL_ID_HERE",
    service_tier="fast",
    max_tokens=4096,
    extra_body={"provider": {"sort": "latency"}},
)

Replace the model placeholder with a catalog ID. Adjust the output limit for your workload. For an HTTP request, put provider and service_tier at the top level of the JSON body, not inside an extra_body object. If your client’s type definitions do not accept a newer tier value, put service_tier in extra_body instead.

API behavior

Endpoint	Purpose
`GET /v1/models`	List the current text-producing model catalog.
`GET /v1/models/{model}`	Retrieve one catalog entry by its exact model ID.
`POST /v1/responses`	Create a stateless OpenAI-compatible Response.
`POST /v1/chat/completions`	Create a chat completion.

Use stream: true or send Accept: text/event-stream to stream either creation endpoint. The Responses endpoint emits named events such as response.output_text.delta and response.completed. Chat Completions emits data frames and ends with [DONE]. The Responses endpoint is intentionally stateless. Set store to false, include the full conversation context in each request, and do not send stateful fields such as previous_response_id, conversation, or background: true.

Response cost

When Aion can calculate a price, usage.cost contains Aion’s USD quote for the returned result. The quote uses the applicable organization policy and the effective service tier. This applies to Chat Completions and Responses. It also applies to SSE events that contain usage. For Chat Completions streams, request stream_options: {"include_usage": true} to receive usage. An event without usage does not receive a cost field. If the quote is unavailable, Aion omits usage.cost and preserves the output. An absent cost does not mean a free request. 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 Metrics and Aion billing records for settled charges in credits.

Troubleshoot a request

Error code	What to check
`model_not_found`	Copy the exact model ID from Resources > Models.
`model_not_supported`	Choose a text-producing model supported by the requested endpoint.
`model_authorization_denied`	Confirm that the user or runtime Identity has `model.execute`.
`response_state_not_supported`	Remove stateful Responses fields and set `store` to `false`.
`insufficient_credits`	Review the organization’s available Aion credits.
`billing_organization_required`	Select an active organization or use runtime credentials tied to one.
`credit_policy_suspended`	Ask an organization administrator to review the credit policy.

Other operations

Use Decisions for named probability, choice, score, and box questions. The Decisions API has its own HTTP contract. Text SDK adapters do not implement that contract.

Guides

Core Concepts

Ions

Resources

Distributions

Tools

Other

Usage

Choose a client

Make an HTTP request

Use an SDK adapter

Configure Codex

Provider preferences and service tiers

Provider preferences

Service tiers

SDK examples

API behavior

Response cost

Troubleshoot a request

Other operations

​Usage

​Choose a client

​Make an HTTP request

​Use an SDK adapter

​Configure Codex

​Provider preferences and service tiers

​Provider preferences

​Service tiers

​SDK examples

​API behavior

​Response cost

​Troubleshoot a request

​Other operations

Usage

Choose a client

Make an HTTP request

Use an SDK adapter

Configure Codex

Provider preferences and service tiers

Provider preferences

Service tiers

SDK examples

API behavior

Response cost

Troubleshoot a request

Other operations