> ## 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 metadados da lista de modelos

>  - GET /v1/models: lista básica ampliada via expand com categorias, recursos e esquema de parâmetros
- Compatível com filtro `category` e JSON Schema via `expand=parameters`
- Útil para automação, formulários dinâmicos e pré-validação 

<Info>
  A **API de metadados da lista de modelos** (`GET /v1/models`) retorna, por padrão, apenas campos básicos, como o nome do modelo. Ao adicionar o parâmetro de consulta `expand`, cada modelo passa a incluir:

  * **Categoria** (`category`): `chat` / `image` / `video` / `audio`
  * **Tags de capacidade** (`capability_tags`): por exemplo, `Text to Video` e `Image to Image`
  * **Contrato de parâmetros** (`parameters`): JSON Schema padrão que indica campos obrigatórios/opcionais, enumerações, intervalos e valores padrão

  Use a API para buscar uma vez o catálogo completo e gerar código cliente, criar formulários de parâmetros dinamicamente ou validar solicitações localmente antes do envio.

  > **Compatibilidade retroativa**: sem `expand` (ou com um valor não reconhecido), a resposta é idêntica ao formato existente e não afeta os clientes atuais.
</Info>

<Warning>
  **Escopo dos modelos**: os modelos retornados dependem das restrições de modelos e do grupo atribuído à chave de API. `category=unknown` indica que a plataforma ainda não catalogou os metadados de categoria desse modelo.
</Warning>

## Obter a lista de modelos com metadados

**GET** `/v1/models`

### Cabeçalhos da solicitação

```
Authorization: Bearer YOUR_API_KEY
```

### Parâmetros de consulta

| Parâmetro  | Tipo   | Obrigatório | Descrição                                                                                                                                         |
| ---------- | ------ | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | string |     Não     | `category`: adiciona categoria e tags de capacidade (leve); `parameters`: também adiciona o JSON Schema completo dos parâmetros (resposta grande) |
| `category` | string |     Não     | Filtra por `chat` / `image` / `video` / `audio` / `unknown`. Só é aplicado quando `expand` é informado                                            |

O escopo dos modelos retornados é o mesmo de uma solicitação sem `expand`: ele depende das restrições de modelos e do grupo atribuído à chave de API.

### Exemplo 1: somente a categoria

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

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

Item individual (`input_schema.properties` mostra apenas alguns 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 da resposta

### Campos do item

| Campo                                                                 | Tipo      | Condição                                            | Descrição                                        |
| --------------------------------------------------------------------- | --------- | --------------------------------------------------- | ------------------------------------------------ |
| `id` / `object` / `created` / `owned_by` / `supported_endpoint_types` | -         | Sempre                                              | Igual à API existente                            |
| `category`                                                            | string    | Com `expand`                                        | `chat` / `image` / `video` / `audio` / `unknown` |
| `capability_tags`                                                     | string\[] | Com `expand` e quando houver tags                   | Consulte a tabela de tags de capacidade          |
| `parameters`                                                          | object    | Com `expand=parameters` e quando houver um contrato | Consulte o bloco parameters                      |

`category=unknown` indica que a plataforma ainda não catalogou os metadados de categoria desse modelo (normalmente, um nome não padrão configurado na lista permitida da chave de API). O modelo continua disponível para uso normal.

### Tags de capacidade

| Categoria | Tags possíveis                                      |
| --------- | --------------------------------------------------- |
| 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`                                             |

### Bloco parameters

| Campo                 | Descrição                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `operation`           | `image_generation` / `video_generation`                                                                 |
| `method` + `endpoint` | Método HTTP e caminho usados para chamar o modelo (por exemplo, `POST /v1/videos/generations`)          |
| `schema_version`      | Versão do contrato (data); entre versões, os campos são apenas adicionados                              |
| `source`              | Fonte dos dados do contrato para diagnóstico; `base` indica que existe somente o contrato base genérico |
| `input_schema`        | Contrato completo do corpo da solicitação em JSON Schema draft 2020-12                                  |

### Como ler input\_schema

É um JSON Schema padrão que as ferramentas mais usadas, como ajv, pydantic e openapi-generator, podem consumir diretamente.

* **Parâmetros obrigatórios** = matriz `required` de nível superior; `anyOf` significa “pelo menos uma das combinações a seguir” (no exemplo acima, uma entre `prompt`, `messages` ou as três entradas de mídia de referência)
* **Valores enumerados** = `enum` na propriedade
* **Intervalo** = `minimum` / `maximum`
* **Valor padrão** = `default`
* `additionalProperties: true`: permite parâmetros de extensão específicos do modelo que não estejam listados no esquema (encaminhados por `metadata`)

## Consultar um único modelo

Além da lista, há um endpoint dedicado para obter o contrato de um único modelo (mesma estrutura, com blocos adicionais que explicam a idempotência e o contrato da resposta):

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

# Para nomes de modelo que contenham "/", use o formato com parâmetro de consulta
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Observações

1. **Atualmente, os modelos chat / audio têm apenas `category` e `capability_tags`, sem `parameters`** (os contratos de parâmetros cobrem image / video e serão ampliados em versões futuras).
2. **O esquema é um contrato de melhor esforço; a validação no servidor é a autoridade final**. Algumas restrições dinâmicas, como combinações específicas de resolução e duração, podem não estar totalmente expressas no esquema. O servidor ainda pode rejeitar uma solicitação e retornar um motivo específico.
3. **A atualização dos dados ocorre em minutos**. O catálogo é armazenado em cache, portanto novos modelos ou alterações de parâmetros podem levar alguns minutos para aparecer.
4. **Uma resposta completa com `expand=parameters` pode chegar a centenas de KB**. Filtre por `category` quando possível e envie `Accept-Encoding: gzip`.
5. Este parâmetro se aplica apenas às listas de modelos no formato OpenAI. As listas nos formatos Anthropic / Gemini não são compatíveis com `expand`.