> ## 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 de métadonnées de la liste des modèles

>  - GET /v1/models : liste de base enrichie via expand avec les catégories, capacités et schémas de paramètres
- Prend en charge le filtre `category` et JSON Schema via `expand=parameters`
- Adaptée à l'automatisation, aux formulaires dynamiques et à la prévalidation 

<Info>
  L'**API de métadonnées de la liste des modèles** (`GET /v1/models`) renvoie par défaut uniquement les champs de base, comme le nom du modèle. Le paramètre de requête `expand` ajoute les informations suivantes à chaque modèle :

  * **Catégorie** (`category`) : `chat` / `image` / `video` / `audio`
  * **Balises de capacité** (`capability_tags`) : par exemple `Text to Video` et `Image to Image`
  * **Contrat des paramètres** (`parameters`) : JSON Schema standard indiquant les champs obligatoires/facultatifs, les valeurs énumérées, les plages et les valeurs par défaut

  Cette API permet notamment de récupérer une fois le catalogue complet pour générer du code client, de construire dynamiquement des formulaires de paramètres et de valider localement une requête avant son envoi.

  > **Rétrocompatibilité** : sans `expand` (ou avec une valeur inconnue), la réponse est identique au format existant et n'affecte pas les clients actuels.
</Info>

<Warning>
  **Périmètre des modèles** : les modèles renvoyés dépendent des restrictions de modèles et du groupe associé à la clé API. `category=unknown` signifie que les métadonnées de catégorie de ce modèle ne sont pas encore enregistrées sur la plateforme.
</Warning>

## Obtenir la liste des modèles avec leurs métadonnées

**GET** `/v1/models`

### En-têtes de requête

```
Authorization: Bearer YOUR_API_KEY
```

### Paramètres de requête

| Paramètre  | Type   | Obligatoire | Description                                                                                                                                                   |
| ---------- | ------ | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | string |     Non     | `category` : ajoute la catégorie et les balises de capacité (léger) ; `parameters` : ajoute aussi le JSON Schema complet des paramètres (réponse volumineuse) |
| `category` | string |     Non     | Filtre sur `chat` / `image` / `video` / `audio` / `unknown`. Actif uniquement lorsque `expand` est fourni                                                     |

Le périmètre des modèles renvoyés est le même que sans `expand` : il dépend des restrictions de modèles et du groupe associé à la clé API.

### Exemple 1 : catégorie uniquement

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

### Exemple 2 : contrat complet des paramètres pour les modèles vidéo

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

Élément unique (`input_schema.properties` ne présente qu'une partie des champs) :

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

## Champs de la réponse

### Champs d'un élément

| Champ                                                                 | Type      | Condition                                        | Description                                      |
| --------------------------------------------------------------------- | --------- | ------------------------------------------------ | ------------------------------------------------ |
| `id` / `object` / `created` / `owned_by` / `supported_endpoint_types` | -         | Toujours                                         | Identique à l'API existante                      |
| `category`                                                            | string    | Avec `expand`                                    | `chat` / `image` / `video` / `audio` / `unknown` |
| `capability_tags`                                                     | string\[] | Avec `expand` et si des balises existent         | Voir le tableau des balises de capacité          |
| `parameters`                                                          | object    | Avec `expand=parameters` et si un contrat existe | Voir le bloc parameters                          |

`category=unknown` signifie que les métadonnées de catégorie de ce modèle ne sont pas encore enregistrées sur la plateforme (généralement pour un nom non standard configuré dans la liste autorisée de la clé API). Le modèle reste utilisable normalement.

### Balises de capacité

| Catégorie | Balises possibles                                   |
| --------- | --------------------------------------------------- |
| 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`                                             |

### Bloc parameters

| Champ                 | Description                                                                                                             |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `operation`           | `image_generation` / `video_generation`                                                                                 |
| `method` + `endpoint` | Méthode HTTP et chemin à utiliser pour appeler le modèle (par exemple `POST /v1/videos/generations`)                    |
| `schema_version`      | Version du contrat (date) ; les champs sont uniquement ajoutés entre les versions                                       |
| `source`              | Source des données du contrat pour le diagnostic ; `base` signifie que seul le contrat de base générique est disponible |
| `input_schema`        | Contrat complet du corps de la requête au format JSON Schema draft 2020-12                                              |

### Lire input\_schema

Il s'agit d'un JSON Schema standard, directement exploitable par les principaux outils tels que ajv, pydantic et openapi-generator.

* **Paramètres obligatoires** = tableau `required` de premier niveau ; `anyOf` signifie « au moins une des combinaisons suivantes » (dans l'exemple ci-dessus, l'une de `prompt`, `messages` ou des trois entrées de média de référence)
* **Valeurs énumérées** = `enum` sur la propriété
* **Plage** = `minimum` / `maximum`
* **Valeur par défaut** = `default`
* `additionalProperties: true` : autorise les paramètres d'extension propres au modèle qui ne figurent pas dans le schéma (transmis via `metadata`)

## Interroger un modèle unique

En plus de la liste, un point de terminaison dédié permet d'obtenir le contrat d'un seul modèle (même structure, avec des blocs supplémentaires décrivant l'idempotence et le contrat de réponse) :

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

# Pour un nom de modèle contenant "/", utiliser la forme avec paramètre de requête
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Remarques

1. **Les modèles chat / audio ne disposent actuellement que de `category` et `capability_tags`, sans `parameters`** (les contrats de paramètres couvrent actuellement image / video et seront complétés dans des versions ultérieures).
2. **Le schéma est un contrat fourni au mieux ; la validation côté serveur fait autorité**. Certaines contraintes dynamiques, telles que des combinaisons particulières de résolution et de durée, peuvent ne pas être entièrement exprimées dans le schéma. Le serveur peut toujours rejeter une requête avec une raison précise.
3. **Les données sont actualisées à l'échelle de quelques minutes**. Le catalogue étant mis en cache, les nouveaux modèles ou les modifications de paramètres peuvent apparaître avec quelques minutes de retard.
4. **Une réponse complète avec `expand=parameters` peut atteindre plusieurs centaines de Ko**. Filtrez si possible avec `category` et envoyez `Accept-Encoding: gzip`.
5. Ce paramètre s'applique uniquement aux listes de modèles au format OpenAI. Les listes aux formats Anthropic / Gemini ne prennent pas en charge `expand`.