> ## 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 metadatos de la lista de modelos

>  - GET /v1/models: lista básica ampliable con categorías, capacidades y esquema de parámetros mediante expand
- Admite el filtro `category` y JSON Schema mediante `expand=parameters`
- Útil para automatización, formularios dinámicos y validación previa 

<Info>
  La **API de metadatos de la lista de modelos** (`GET /v1/models`) devuelve de forma predeterminada solo campos básicos, como el nombre del modelo. Al añadir el parámetro de consulta `expand`, cada modelo incluye:

  * **Categoría** (`category`): `chat` / `image` / `video` / `audio`
  * **Etiquetas de capacidad** (`capability_tags`): por ejemplo, `Text to Video` e `Image to Image`
  * **Contrato de parámetros** (`parameters`): JSON Schema estándar que indica campos obligatorios/opcionales, enumeraciones, rangos y valores predeterminados

  Resulta útil para obtener una vez el catálogo completo y generar código cliente, crear formularios de parámetros dinámicamente o validar las solicitudes localmente antes de enviarlas.

  > **Compatibilidad retroactiva**: sin `expand` (o con un valor no reconocido), la respuesta es idéntica al formato existente y no afecta a los clientes actuales.
</Info>

<Warning>
  **Ámbito de modelos**: los modelos devueltos dependen de las restricciones de modelos y del grupo asignado a la clave API. `category=unknown` indica que la plataforma aún no ha registrado los metadatos de categoría de ese modelo.
</Warning>

## Obtener la lista de modelos con metadatos

**GET** `/v1/models`

### Encabezados de solicitud

```
Authorization: Bearer YOUR_API_KEY
```

### Parámetros de consulta

| Parámetro  | Tipo   | Obligatorio | Descripción                                                                                                                                         |
| ---------- | ------ | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | string |      No     | `category`: añade categoría y etiquetas de capacidad (ligero); `parameters`: añade también el JSON Schema completo de parámetros (respuesta grande) |
| `category` | string |      No     | Filtra por `chat` / `image` / `video` / `audio` / `unknown`. Solo se aplica cuando se proporciona `expand`                                          |

El ámbito de los modelos devueltos es el mismo que sin `expand`: depende de las restricciones de modelos y del grupo asignado a la clave API.

### Ejemplo 1: solo la categoría

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

### Ejemplo 2: contrato completo de parámetros para modelos de vídeo

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

Elemento individual (`input_schema.properties` muestra solo algunos campos):

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

## Campos de respuesta

### Campos del elemento

| Campo                                                                 | Tipo      | Condición                                       | Descripción                                      |
| --------------------------------------------------------------------- | --------- | ----------------------------------------------- | ------------------------------------------------ |
| `id` / `object` / `created` / `owned_by` / `supported_endpoint_types` | -         | Siempre                                         | Igual que en la API existente                    |
| `category`                                                            | string    | Con `expand`                                    | `chat` / `image` / `video` / `audio` / `unknown` |
| `capability_tags`                                                     | string\[] | Con `expand` y si hay etiquetas                 | Consulta la tabla de etiquetas de capacidad      |
| `parameters`                                                          | object    | Con `expand=parameters` y si existe un contrato | Consulta el bloque parameters                    |

`category=unknown` indica que la plataforma aún no ha registrado los metadatos de categoría de ese modelo (normalmente, un nombre no estándar configurado en la lista permitida de la clave API). El modelo se puede seguir utilizando con normalidad.

### Etiquetas de capacidad

| Categoría | Etiquetas posibles                                  |
| --------- | --------------------------------------------------- |
| 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`                                             |

### Bloque parameters

| Campo                 | Descripción                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `operation`           | `image_generation` / `video_generation`                                                                       |
| `method` + `endpoint` | Método HTTP y ruta que se deben usar para llamar al modelo (por ejemplo, `POST /v1/videos/generations`)       |
| `schema_version`      | Versión del contrato (fecha); entre versiones solo se añaden campos                                           |
| `source`              | Fuente de los datos del contrato para diagnóstico; `base` significa que solo existe el contrato base genérico |
| `input_schema`        | Contrato completo del cuerpo de la solicitud en JSON Schema draft 2020-12                                     |

### Cómo leer input\_schema

Es un JSON Schema estándar que las herramientas habituales, como ajv, pydantic y openapi-generator, pueden consumir directamente.

* **Parámetros obligatorios** = matriz `required` de nivel superior; `anyOf` significa «al menos una de las siguientes combinaciones» (en el ejemplo anterior, una de `prompt`, `messages` o las tres entradas de medios de referencia)
* **Valores enumerados** = `enum` en la propiedad
* **Rango** = `minimum` / `maximum`
* **Valor predeterminado** = `default`
* `additionalProperties: true`: permite parámetros de extensión específicos del modelo que no aparecen en el esquema (se transmiten mediante `metadata`)

## Consultar un solo modelo

Además de la lista, existe un endpoint específico para obtener el contrato de un modelo individual (la misma estructura, con bloques adicionales que explican la idempotencia y el contrato de respuesta):

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

# Para nombres de modelo que contienen "/", usa la forma con parámetro de consulta
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Notas

1. **Actualmente, los modelos chat / audio solo tienen `category` y `capability_tags`, sin `parameters`** (los contratos de parámetros cubren image / video y se ampliarán en versiones posteriores).
2. **El esquema es un contrato de mejor esfuerzo; la validación del servidor es la autoridad final**. Algunas restricciones dinámicas, como determinadas combinaciones de resolución y duración, pueden no estar completamente expresadas en el esquema. El servidor todavía puede rechazar una solicitud y devolver un motivo específico.
3. **La actualización de los datos se mide en minutos**. El catálogo se almacena en caché, por lo que los modelos nuevos o los cambios de parámetros pueden tardar unos minutos en aparecer.
4. **Una respuesta completa con `expand=parameters` puede alcanzar varios cientos de KB**. Filtra por `category` cuando sea posible y envía `Accept-Encoding: gzip`.
5. Este parámetro solo se aplica a las listas de modelos con formato OpenAI. Las listas con formato Anthropic / Gemini no admiten `expand`.