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

# Metadaten-API für die Modellliste

>  - GET /v1/models: Basisliste plus Kategorien, Funktionen und Parameterschema über expand
- Unterstützt `category`-Filter und JSON Schema mit `expand=parameters`
- Für Automatisierung, dynamische Formulare und Vorabvalidierung 

<Info>
  Die **Metadaten-API für die Modellliste** (`GET /v1/models`) gibt standardmäßig nur Basisfelder wie den Modellnamen zurück. Mit dem Abfrageparameter `expand` werden jedem Modell folgende Informationen hinzugefügt:

  * **Kategorie** (`category`): `chat` / `image` / `video` / `audio`
  * **Funktions-Tags** (`capability_tags`): beispielsweise `Text to Video` und `Image to Image`
  * **Parametervertrag** (`parameters`): standardmäßiges JSON Schema mit Pflicht-/optionalen Feldern, Aufzählungswerten, Wertebereichen und Standardwerten

  Geeignet zum einmaligen Abrufen des vollständigen Katalogs für die Generierung von Client-Code, zum dynamischen Erstellen von Parameterformularen und zur lokalen Validierung vor dem Senden einer Anfrage.

  > **Abwärtskompatibel**: Ohne `expand` (oder mit einem unbekannten Wert) entspricht die Antwort vollständig dem bisherigen Format. Bestehende Clients bleiben unbeeinflusst.
</Info>

<Warning>
  **Modellumfang**: Die zurückgegebenen Modelle werden durch die Modellbeschränkungen und die zugewiesene Gruppe des API-Schlüssels bestimmt. `category=unknown` bedeutet, dass die Plattform die Kategoriemetadaten dieses Modells noch nicht erfasst hat.
</Warning>

## Modellliste mit Metadaten abrufen

**GET** `/v1/models`

### Anfrage-Header

```
Authorization: Bearer YOUR_API_KEY
```

### Abfrageparameter

| Parameter  | Typ    | Erforderlich | Beschreibung                                                                                                                                    |
| ---------- | ------ | :----------: | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | string |     Nein     | `category`: fügt Kategorie und Funktions-Tags hinzu (kompakt); `parameters`: fügt zusätzlich das vollständige JSON Schema hinzu (große Antwort) |
| `category` | string |     Nein     | Filtert nach `chat` / `image` / `video` / `audio` / `unknown`. Nur wirksam, wenn `expand` angegeben ist                                         |

Der Modellumfang entspricht dem einer Anfrage ohne `expand` und wird durch die Modellbeschränkungen und die zugewiesene Gruppe des API-Schlüssels gesteuert.

### Beispiel 1: Nur Kategorien

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

### Beispiel 2: Vollständiger Parametervertrag für Videomodelle

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

Einzelner Eintrag (`input_schema.properties` zeigt nur ausgewählte Felder):

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

## Antwortfelder

### Felder eines Eintrags

| Feld                                                                  | Typ       | Bedingung                                               | Beschreibung                                     |
| --------------------------------------------------------------------- | --------- | ------------------------------------------------------- | ------------------------------------------------ |
| `id` / `object` / `created` / `owned_by` / `supported_endpoint_types` | -         | Immer                                                   | Wie in der bisherigen API                        |
| `category`                                                            | string    | Mit `expand`                                            | `chat` / `image` / `video` / `audio` / `unknown` |
| `capability_tags`                                                     | string\[] | Mit `expand`, wenn Tags vorhanden sind                  | Siehe Tabelle der Funktions-Tags                 |
| `parameters`                                                          | object    | Mit `expand=parameters`, wenn ein Vertrag vorhanden ist | Siehe parameters-Block                           |

`category=unknown` bedeutet, dass die Plattform die Kategoriemetadaten dieses Modells noch nicht erfasst hat (üblicherweise bei nicht standardmäßigen Namen in der Modellfreigabe des API-Schlüssels). Das Modell kann trotzdem normal aufgerufen werden.

### Funktions-Tags

| Kategorie | Mögliche 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

| Feld                  | Beschreibung                                                                                                   |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| `operation`           | `image_generation` / `video_generation`                                                                        |
| `method` + `endpoint` | HTTP-Methode und Pfad für den Aufruf des Modells (z. B. `POST /v1/videos/generations`)                         |
| `schema_version`      | Vertragsversion (Datum); über Versionen hinweg werden Felder nur hinzugefügt                                   |
| `source`              | Quelle der Vertragsdaten für die Fehleranalyse; `base` bedeutet, dass nur der allgemeine Basisvertrag vorliegt |
| `input_schema`        | Vollständiger Vertrag für den Anfragekörper als JSON Schema draft 2020-12                                      |

### input\_schema lesen

Es handelt sich um standardmäßiges JSON Schema, das von gängigen Werkzeugen wie ajv, pydantic und openapi-generator direkt verarbeitet werden kann.

* **Pflichtparameter** = oberstes `required`-Array; `anyOf` bedeutet „mindestens eine der folgenden Kombinationen“ (im obigen Beispiel eine von `prompt`, `messages` oder den drei Referenzmedien-Eingaben)
* **Aufzählungswerte** = `enum` an einer Eigenschaft
* **Wertebereich** = `minimum` / `maximum`
* **Standardwert** = `default`
* `additionalProperties: true`: erlaubt modellspezifische Erweiterungsparameter, die nicht im Schema aufgeführt sind (Weitergabe über `metadata`)

## Einzelnes Modell abfragen

Neben der Liste gibt es einen eigenen Endpunkt für den Vertrag eines einzelnen Modells (gleiche Struktur, ergänzt um Blöcke zur Idempotenz und zum Antwortvertrag):

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

# Bei Modellnamen mit "/" die Abfrageparameter-Form verwenden
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Hinweise

1. **Chat- und Audiomodelle besitzen derzeit nur `category` und `capability_tags`, aber keine `parameters`** (Parameterverträge decken aktuell nur image / video ab und werden in späteren Versionen ergänzt).
2. **Das Schema ist ein Best-Effort-Vertrag; maßgeblich ist die serverseitige Validierung**. Dynamische Einschränkungen einzelner Modelle, etwa bestimmte Kombinationen aus Auflösung und Dauer, sind möglicherweise nicht vollständig im Schema ausgedrückt. Der Server kann eine Anfrage weiterhin mit einem konkreten Grund ablehnen.
3. **Die Datenaktualität liegt im Minutenbereich**. Der Katalog wird zwischengespeichert; neue Modelle oder Parameteränderungen können daher erst nach einigen Minuten erscheinen.
4. **Eine vollständige Antwort mit `expand=parameters` kann mehrere hundert KB groß sein**. Filtern Sie möglichst nach `category` und senden Sie `Accept-Encoding: gzip`.
5. Dieser Parameter gilt nur für Modelllisten im OpenAI-Format. Modelllisten im Anthropic- oder Gemini-Format unterstützen `expand` nicht.