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

# Text models

> Use Aion with Responses, Chat Completions, and existing text SDK adapters.

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](https://docs.aion.to/docs/resources/model-service.md#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](https://mintcdn.com/terminalresearch/J7tTAY16_LpxcJN4/assets/resources/model-service/model-usage-sdk.png?fit=max\&auto=format\&n=J7tTAY16_LpxcJN4\&q=85\&s=093f6cd899e35933bf0b4e2d38ec4e21)

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

```bash theme={null}
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:

```python theme={null}
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](https://docs.aion.to/sdk/langgraph/api/models.md) uses `aion_chat_model()`.
* [Google ADK Model Service](https://docs.aion.to/sdk/google-adk/api/models.md) uses `aion_lite_llm()`.
* [Aion API](https://docs.aion.to/sdk/python/packages/aion-api-client.md) provides shared authentication and Model Service
  configuration.

For a configurable application, an `llm` field in
[`aion.yaml`](https://docs.aion.to/sdk/python/configuration/aion-yaml#llm-fields) 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:

```toml theme={null}
# $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:

```python theme={null}
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:

```python theme={null}
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](https://docs.aion.to/docs/resources/model-service/decisions.md) for named probability, choice, score, and box questions.
The Decisions API has its own HTTP contract. Text SDK adapters do not implement that contract.


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