> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API метаданных списка моделей

>  - GET /v1/models: базовый список с категориями, возможностями и схемой параметров через expand
- Поддерживает фильтр `category` и получение JSON Schema через `expand=parameters`
- Подходит для автоматизации, динамических форм и предварительной проверки 

<Info>
  **API метаданных списка моделей** (`GET /v1/models`) по умолчанию возвращает только базовые поля, например имя модели. Параметр запроса `expand` добавляет к каждой модели следующие данные:

  * **Категория** (`category`): `chat` / `image` / `video` / `audio`
  * **Метки возможностей** (`capability_tags`): например, `Text to Video` и `Image to Image`
  * **Контракт параметров** (`parameters`): стандартная JSON Schema с обязательными и необязательными полями, перечислениями, диапазонами и значениями по умолчанию

  API можно использовать, чтобы один раз получить полный каталог и сгенерировать клиентский код, динамически построить формы параметров или локально проверить запрос перед отправкой.

  > **Обратная совместимость**: без `expand` (или с нераспознанным значением) ответ полностью совпадает с прежним форматом и не влияет на существующие клиенты.
</Info>

<Warning>
  **Область моделей**: возвращаемые модели зависят от ограничений моделей и группы, назначенной API-ключу. `category=unknown` означает, что метаданные категории этой модели еще не зарегистрированы на платформе.
</Warning>

## Получение списка моделей с метаданными

**GET** `/v1/models`

### Заголовки запроса

```
Authorization: Bearer YOUR_API_KEY
```

### Параметры запроса

| Параметр   | Тип    | Обязательный | Описание                                                                                                                                             |
| ---------- | ------ | :----------: | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | string |      Нет     | `category`: добавляет категорию и метки возможностей (компактный ответ); `parameters`: также добавляет полную JSON Schema параметров (большой ответ) |
| `category` | string |      Нет     | Фильтр по `chat` / `image` / `video` / `audio` / `unknown`. Действует только при наличии `expand`                                                    |

Область возвращаемых моделей совпадает с запросом без `expand` и определяется ограничениями моделей и группой, назначенной API-ключу.

### Пример 1: только категория

```bash cURL theme={null}
curl -s "https://api.apimart.ai/v1/models?expand=category" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "wan2.6",
      "object": "model",
      "created": 1626777600,
      "owned_by": "alibaba",
      "supported_endpoint_types": ["openai"],
      "category": "video",
      "capability_tags": ["Text to Video"]
    },
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["openai"],
      "category": "chat",
      "capability_tags": ["Text", "Vision"]
    }
  ]
}
```

### Пример 2: полный контракт параметров для видеомоделей

```bash cURL theme={null}
curl -s "https://api.apimart.ai/v1/models?expand=parameters&category=video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept-Encoding: gzip" --compressed
```

Один элемент (`input_schema.properties` содержит только часть полей):

```json theme={null}
{
  "id": "wan2.6",
  "object": "model",
  "created": 1626777600,
  "owned_by": "alibaba",
  "supported_endpoint_types": ["openai"],
  "category": "video",
  "capability_tags": ["Text to Video"],
  "parameters": {
    "operation": "video_generation",
    "method": "POST",
    "endpoint": "/v1/videos/generations",
    "schema_version": "2026-07-30",
    "source": "task_model_registry",
    "input_schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "additionalProperties": true,
      "required": ["model"],
      "anyOf": [
        { "required": ["prompt"] },
        { "required": ["messages"] },
        { "required": ["image_urls"] },
        { "required": ["image_with_roles"] },
        { "required": ["video_urls"] }
      ],
      "properties": {
        "model":      { "type": "string", "const": "wan2.6" },
        "prompt":     { "type": "string", "minLength": 1 },
        "duration":   { "type": "integer", "minimum": 1 },
        "resolution": { "type": "string" },
        "aspect_ratio": { "type": "string" }
      }
    }
  }
}
```

## Поля ответа

### Поля элемента

| Поле                                                                  | Тип       | Условие                                   | Описание                                         |
| --------------------------------------------------------------------- | --------- | ----------------------------------------- | ------------------------------------------------ |
| `id` / `object` / `created` / `owned_by` / `supported_endpoint_types` | -         | Всегда                                    | Как в существующем API                           |
| `category`                                                            | string    | С `expand`                                | `chat` / `image` / `video` / `audio` / `unknown` |
| `capability_tags`                                                     | string\[] | С `expand`, если есть метки               | См. таблицу меток возможностей                   |
| `parameters`                                                          | object    | С `expand=parameters`, если есть контракт | См. блок parameters                              |

`category=unknown` означает, что метаданные категории модели еще не зарегистрированы на платформе (обычно это нестандартное имя в списке разрешенных моделей API-ключа). Саму модель по-прежнему можно вызывать обычным образом.

### Метки возможностей

| Категория | Возможные метки                                     |
| --------- | --------------------------------------------------- |
| video     | `Text to Video`, `Image to Video`, `Video to Video` |
| image     | `Text to Image`, `Image to Image`                   |
| chat      | `Text`, `Embedding`, `Vision`, `Audio`, `Omni`      |
| audio     | `Audio`                                             |

### Блок parameters

| Поле                  | Описание                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| `operation`           | `image_generation` / `video_generation`                                                                |
| `method` + `endpoint` | HTTP-метод и путь для вызова модели (например, `POST /v1/videos/generations`)                          |
| `schema_version`      | Версия контракта (дата); между версиями поля только добавляются                                        |
| `source`              | Источник данных контракта для диагностики; `base` означает, что доступен только общий базовый контракт |
| `input_schema`        | Полный контракт тела запроса в формате JSON Schema draft 2020-12                                       |

### Как читать input\_schema

Это стандартная JSON Schema, которую могут напрямую обрабатывать распространенные инструменты, включая ajv, pydantic и openapi-generator.

* **Обязательные параметры** = массив `required` верхнего уровня; `anyOf` означает «как минимум одна из следующих комбинаций» (в примере выше — одна из `prompt`, `messages` или трех ссылок на медиа)
* **Перечисляемые значения** = `enum` в свойстве
* **Диапазон** = `minimum` / `maximum`
* **Значение по умолчанию** = `default`
* `additionalProperties: true`: разрешает специфичные для модели дополнительные параметры, не перечисленные в схеме (передаются через `metadata`)

## Запрос одной модели

Помимо списка, для контракта отдельной модели предусмотрен специальный endpoint (та же структура с дополнительными блоками об идемпотентности и контракте ответа):

```bash theme={null}
curl -s "https://api.apimart.ai/v1/models/wan2.6/schema" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Для имени модели с "/" используйте форму с параметром запроса
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Примечания

1. **Сейчас модели chat / audio содержат только `category` и `capability_tags`, без `parameters`** (контракты параметров пока охватывают только image / video и будут дополнены в следующих версиях).
2. **Схема является контрактом на основе доступных данных; окончательной считается серверная проверка**. Некоторые динамические ограничения, например определенные сочетания разрешения и длительности, могут быть выражены в схеме не полностью. Сервер все равно может отклонить запрос и вернуть конкретную причину.
3. **Данные обновляются с точностью до нескольких минут**. Каталог кэшируется, поэтому новые модели или изменения параметров могут появиться с небольшой задержкой.
4. **Полный ответ с `expand=parameters` может занимать несколько сотен КБ**. По возможности фильтруйте по `category` и отправляйте `Accept-Encoding: gzip`.
5. Этот параметр действует только для списков моделей в формате OpenAI. Списки в форматах Anthropic / Gemini не поддерживают `expand`.