# Models and tools

> List the AI models and the AI tools available on the server, to pick a model for chat and tools for assistants.

The model catalogue and the tool catalogue are the same for every user of the server.
Use them to find the `model_id` to send to [chat](chat.md) or to put on an
[assistant](assistants.md), and the tool `name`s an assistant's tool list refers to.

Both endpoints return the whole catalogue in one response; there is no paging.

## List models

| | |
|---|---|
| Endpoint | `POST /api/v3/ai_model/get_all` |
| Scope | any API key |
| Rate limit | [default](conventions.md#rate-limits) |

Returns the AI models known to the server, optionally only those of one type. The list
is not personalised: every user gets the same catalogue, regardless of organization.

The list also contains models the administrators have switched off (`is_enabled`
`false`) or retired (`is_deprecated` `true`). Chat refuses both (`422` `model is disabled`
/ `model is deprecated`, see [Chat](chat.md#errors)); pick models with `is_enabled` `true`
and `is_deprecated` `false`. The list is not sorted in any guaranteed order.

Concrete prices are not exposed. Use [`price_tier`](#price-tiers) for a relative price
indication, and [conversation cost](account.md#get-the-cost-of-a-conversation) for what a
conversation actually cost.

### Request

The body is required; send `{}` to get models of every type.

| Field | Type | Required | Description |
|---|---|---|---|
| `model_type` | string | No | Return only models of this [type](#model-types). |

### Response

`200 OK` with an array of [models](#model).

### Errors

| Status | `detail` | Cause |
|---|---|---|
| `422` | validation error | The body is missing, or `model_type` is not a known type. |

Authentication, rate limit and server errors are described in
[conventions](conventions.md#errors).

### Example

```bash
curl -X POST "https://ayeto.ai/api/v3/ai_model/get_all" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_type": "llm"}'
```

```json
[
  {
    "id": "3f2a6c1e-8b4d-4e2a-9c7f-1d5e8a2b4c6d",
    "model_id": "example-chat-large",
    "model_type": "llm",
    "provider": "openai_responses",
    "display_name": "Example Chat Large",
    "description": "General purpose model for complex tasks.",
    "multilang_description": {
      "CZ": "Univerzální model pro složité úlohy.",
      "EN": "General purpose model for complex tasks."
    },
    "max_tokens": 32000,
    "max_reasoning_tokens": 0,
    "capabilities": ["chat", "stream", "assistant", "tools", "vision", "reasoning"],
    "use_system_prompt": true,
    "is_deprecated": false,
    "is_enabled": true,
    "is_beta": false,
    "price_tier": 3,
    "price_tier_max": 3,
    "auto_tiers": [],
    "is_new": false
  },
  {
    "id": "9a1b2c3d-4e5f-4061-8a7b-6c5d4e3f2a10",
    "model_id": "example-auto",
    "model_type": "llm",
    "provider": "openai_responses",
    "display_name": "Auto",
    "description": "Picks a suitable model for every message.",
    "multilang_description": {},
    "max_tokens": 16000,
    "max_reasoning_tokens": 0,
    "capabilities": ["chat", "stream", "assistant", "tools"],
    "use_system_prompt": true,
    "is_deprecated": false,
    "is_enabled": true,
    "is_beta": true,
    "price_tier": 1,
    "price_tier_max": 3,
    "auto_tiers": ["example-chat-mini", "example-chat-large"],
    "is_new": true
  }
]
```

## Model

| Field | Type | Description |
|---|---|---|
| `id` | UUID | Identifier of the catalogue entry. Not used by other endpoints; use `model_id`. |
| `model_id` | string | The model identifier. This is the value for the `model` field in [chat](chat.md) and on an [assistant](assistants.md). |
| `model_type` | string | What kind of model it is, see [model types](#model-types). |
| `provider` | string | The AI provider and API family that serves the model, for example `openai`, `openai_responses`, `anthropic`, `google`, `xai`, `deepseek`, `kimi`. Informational. |
| `display_name` | string | Human readable name. |
| `description` | string | Short description, usually in English. |
| `multilang_description` | object | Descriptions by language code (`EN`, `CZ`, `FR`). Keys can be missing; fall back to `description`. |
| `max_tokens` | integer | The largest `max_tokens` (output limit) a chat request may ask for with this model. `0` means the server sets no limit. |
| `max_reasoning_tokens` | integer | Reasoning token budget of reasoning models; `0` when not set. Informational. |
| `capabilities` | array of string | What the model can do, see [capabilities](#capabilities). |
| `use_system_prompt` | boolean | Whether the model receives instructions as a system prompt. Informational. |
| `is_deprecated` | boolean | The model is retired. Chat requests with a deprecated model fail. |
| `is_enabled` | boolean | `false` when the administrators have switched the model off; chat refuses it. |
| `is_beta` | boolean | The model is offered as a beta. |
| `price_tier` | integer or null | Relative price, see [price tiers](#price-tiers). |
| `price_tier_max` | integer or null | Upper end of the price range. Equal to `price_tier` except for [auto models](#auto-models). |
| `auto_tiers` | array of string | For an [auto model](#auto-models), the `model_id`s it chooses from, cheapest first. Empty for every other model. |
| `is_new` | boolean | The model was added to the catalogue recently (by default within the last 14 days). |

### Model types

| `model_type` | Models for |
|---|---|
| `llm` | Text chat. These are the models you use in [chat](chat.md) and on [assistants](assistants.md). |
| `openai_img_gen`, `google_img_gen`, `xai_img_gen` | Image generation, used by the image tools. |
| `stt` | Speech to text. |
| `tts` | Text to speech, see [text to speech](files-and-media.md#text-to-speech). |
| `embeddings` | Text embeddings for knowledge bases. |
| `realtime` | Real-time voice conversations in the app. |
| `classification` | Internal yes/no and choice decisions. |
| `img_gen` | Old image models, kept only for old conversations. |

Only `llm` models can be used directly through this API (in chat and on assistants). The
other types are listed so you can see what the server's tools use.

### Capabilities

| Capability | Meaning |
|---|---|
| `chat` | Can be used in chat. |
| `assistant` | Can run an assistant. Chat always runs an assistant (the default one when you send only `model`), so a chat model needs both `chat` and `assistant`. |
| `stream` | Supports streamed responses. |
| `tools` | Can call AI tools. |
| `tools_caching` | The provider caches the tool definitions between calls (lower cost). |
| `vision` | Accepts images as input. |
| `reasoning` | Reasoning ("thinking") model. |
| `adaptive_reasoning` | The model decides how much to reason by itself. |
| `relevant_history` | Supports the `relevant_history` option of chat. |
| `image_to_image` | Image model that accepts an input image. |
| `image_upscale` | Image model that can upscale images. |
| `image_prompt_edit` | Image model that can edit an image from a text prompt. |
| `image_use_translation` | The image prompt is translated to English before generation. |

### Price tiers

`price_tier` places the model on a scale from `1` (cheapest) to `4` (most expensive),
based on its output price compared with fixed boundaries per model type:

| Value | Meaning |
|---|---|
| `1` to `4` | Relative price, comparable between models of the same type. |
| `0` | Free, or the price is not known. |
| `null` | The model type has no price indication (for example `stt`, `tts`, `embeddings`). |

The actual cost of using a model is charged in credits; see [account](account.md).

### Auto models

An auto model is an `llm` model whose `auto_tiers` list is not empty. It does not answer
by itself: for every message it picks one of the models in `auto_tiers`, a cheaper one
for simple messages and a stronger one for demanding ones. Use its `model_id` like any
other model. Its `price_tier` and `price_tier_max` span the cheapest and the most
expensive of those models. Its capabilities are those that all of its tier models share,
and its `max_tokens` is the smallest limit among them.

## List tools

| | |
|---|---|
| Endpoint | `POST /api/v3/ai_tool/get_all` |
| Scope | any API key |
| Rate limit | [default](conventions.md#rate-limits) |

Returns the AI tools an [assistant](assistants.md) may use. An assistant lists the
tools it may use in `ai_tools`, by tool [`name`](#tool).

The list leaves out tools that are not meant to be picked by hand (hidden helpers the
server adds automatically where they are needed) and retired tools, so `is_hidden` and
`is_deprecated` are always `false` in it. It includes tools that only work inside an
organization (`organization_only`). Some tools also need a connected account (for
example Google or Microsoft) or a paired desktop client to do anything.

`display_name`, `description` and `category` are translated to the language in the
`language` request header (`EN`, `CZ` or `FR`; default `EN`).

### Request

No body is needed.

### Response

`200 OK` with an array of [tools](#tool).

### Errors

This endpoint has no endpoint-specific errors. Authentication, rate limit and server
errors are described in [conventions](conventions.md#errors).

### Example

```bash
curl -X POST "https://ayeto.ai/api/v3/ai_tool/get_all" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "language: EN"
```

```json
[
  {
    "name": "DownloadUrlFunctionTool",
    "display_name": "Download URL",
    "description": "Download content from a URL",
    "icon": "ayeto",
    "is_advanced": false,
    "is_hidden": false,
    "is_deprecated": false,
    "is_silent": false,
    "organization_only": false,
    "tags": ["download", "url", "web", "content", "internet"],
    "category": "Web service",
    "group": null,
    "in_default_assistant": true,
    "always": false,
    "companion_of_group": null,
    "order": 0
  },
  {
    "name": "AssistantMemoryFunctionTool",
    "display_name": "Assistant Memory",
    "description": "Manage the assistant's memory which persists across conversations. Use to store important information that the assistant should remember.",
    "icon": "ayeto",
    "is_advanced": false,
    "is_hidden": false,
    "is_deprecated": false,
    "is_silent": true,
    "organization_only": false,
    "tags": [],
    "category": "General",
    "group": null,
    "in_default_assistant": false,
    "always": false,
    "companion_of_group": null,
    "order": 0
  }
]
```

## Tool

| Field | Type | Description |
|---|---|---|
| `name` | string | The tool identifier. This is the value to put in an assistant's `ai_tools`. |
| `display_name` | string | Human readable name, translated. |
| `description` | string | What the tool does, translated. |
| `icon` | string | Icon name used by the app. |
| `category` | string | Category for grouping tools in a list, translated. |
| `group` | string or null | Tools that belong together (for example all tools of one connected service) share a group. |
| `tags` | array of string | Search keywords. |
| `order` | integer | Sort hint within a list. |
| `is_advanced` | boolean | The app lists the tool under advanced tools. |
| `is_hidden` | boolean | Always `false` in this list (hidden tools are left out). |
| `is_deprecated` | boolean | Always `false` in this list (retired tools are left out). |
| `is_silent` | boolean | Calls of the tool are not shown as tool calls in the conversation, only as a short status. |
| `organization_only` | boolean | The tool is available only when the chat runs in an organization. |
| `in_default_assistant` | boolean | The tool is part of the default assistant (chat with only a `model`). |
| `always` | boolean | Every assistant gets the tool automatically; you do not need to list it. |
| `companion_of_group` | string or null | The tool is added automatically to any assistant that uses a tool of this group. |