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

# Models List Metadata API

>  - GET /v1/models — basic list
- + `expand` query parameter to include category, capability tags, and parameter schema
- For automation, dynamic forms, pre-validation 

<Info>
  The **model list metadata endpoint** (`GET /v1/models`) returns only basic fields such as the model name by default. Adding the `expand` query parameter appends the following metadata to each model:

  * **Category** (`category`): `chat` / `image` / `video` / `audio`
  * **Capability tags** (`capability_tags`): such as `Text to Video` and `Image to Image`
  * **Parameter schema** (`parameters`): standard JSON Schema indicating required/optional, enums, ranges, and defaults

  Use it to fetch the full catalog once and generate client code, build parameter forms dynamically, or validate requests locally before sending them.

  > **Backward compatible**: Without `expand` (or with an unrecognized value), the response is identical to the existing format, so existing clients are unaffected.
</Info>

<Warning>
  **Model scope**: The returned models are controlled by the API key's model restrictions and assigned group. `category=unknown` means that the platform has not yet cataloged the model's category metadata.
</Warning>

## Get model list (with metadata)

**GET** `/v1/models`

### Request headers

```
Authorization: Bearer YOUR_API_KEY
```

### Query parameters

| Parameter  | Type   | Required | Description                                                                                                                   |
| ---------- | ------ | :------: | ----------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | string |    No    | `category` adds category and capability tags (lightweight); `parameters` adds full JSON Schema (full payload, large response) |
| `category` | string |    No    | Filter by category: `chat` / `image` / `video` / `audio` / `unknown`. Only effective when `expand` is provided.               |

The returned model scope is the same as when `expand` is omitted: it is controlled by the API key's model restrictions and assigned group.

### Example 1: Just category

```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"]
    }
  ]
}
```

### Example 2: Full parameter contract for video models

```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
```

Single item (`input_schema.properties` shows only selected fields):

```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" }
      }
    }
  }
}
```

## Response field description

### Item fields

| Field                                                                 | Type      | Condition                                | Description                                      |
| --------------------------------------------------------------------- | --------- | ---------------------------------------- | ------------------------------------------------ |
| `id` / `object` / `created` / `owned_by` / `supported_endpoint_types` | -         | Always                                   | Same as legacy interface                         |
| `category`                                                            | string    | With `expand`                            | `chat` / `image` / `video` / `audio` / `unknown` |
| `capability_tags`                                                     | string\[] | With `expand` and tags                   | See capability tags table                        |
| `parameters`                                                          | object    | `expand=parameters` and contract present | See parameters block                             |

`category=unknown` indicates the platform has not yet cataloged metadata for that model (usually non-standard names configured in the Key's whitelist). The model itself can still be called normally.

### Capability tags

| Category | Possible tags                                       |
| -------- | --------------------------------------------------- |
| 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 block

| Field                 | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| `operation`           | `image_generation` / `video_generation`                                        |
| `method` + `endpoint` | HTTP method and path the model should use (e.g. `POST /v1/videos/generations`) |
| `schema_version`      | Contract version (date); fields only add, never remove                         |
| `source`              | Contract source for debugging; `base` means only generic base contract         |
| `input_schema`        | JSON Schema draft 2020-12 — full request body contract                         |

### How to read input\_schema

Standard JSON Schema. Most tooling (ajv, pydantic, openapi-generator, etc.) can consume it directly:

* **Required parameters** = the top-level `required` array; `anyOf` means “at least one of the following combinations” (in the example above, choose one of `prompt`, `messages`, or the three reference-media inputs)
* **Enum values** = `enum` on properties
* **Range** = `minimum` / `maximum`
* **Default** = `default`
* `additionalProperties: true` — allows extra fields not listed in the schema (typically passed via `metadata`)

## Query a single model

In addition to the list, single-model contracts have a dedicated endpoint (same shape, with extra idempotency and response contract explanation blocks):

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

# For model names containing "/", use the query-parameter form
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Notes

1. **Chat / audio models currently only have `category` and `capability_tags`, with no `parameters`** (parameter contracts currently cover image / video only and will be added for other categories in later versions).
2. **The schema is a best-effort contract; server-side validation is authoritative**: some dynamic constraints, such as specific resolution and duration combinations, may not be fully expressed in the schema. The server may still reject a request and return a specific reason.
3. **Data freshness is measured in minutes**: the catalog is cached, so newly added models or parameter changes may take a few minutes to appear.
4. **A full `expand=parameters` response can reach hundreds of KB**: filter by `category` when possible and send `Accept-Encoding: gzip`.
5. This parameter only affects OpenAI-format model lists; Anthropic / Gemini dialect model lists do not support `expand`.