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

>  - GET /v1/models 기본 목록에 expand 매개변수로 카테고리, 기능 및 매개변수 스키마 추가
- `category` 필터 및 `expand=parameters`를 통한 JSON Schema 조회 지원
- 자동화 연동, 동적 폼 및 사전 검증에 활용 

<Info>
  **모델 목록 메타데이터 API**(`GET /v1/models`)는 기본적으로 모델 이름과 같은 기본 필드만 반환합니다. `expand` 쿼리 매개변수를 추가하면 각 모델에 다음 정보가 포함됩니다.

  * **카테고리**(`category`): `chat` / `image` / `video` / `audio`
  * **기능 태그**(`capability_tags`): `Text to Video`, `Image to Image` 등
  * **매개변수 계약**(`parameters`): 필수/선택, 열거형, 범위 및 기본값을 나타내는 표준 JSON Schema

  전체 카탈로그를 한 번 가져와 클라이언트 코드를 생성하거나, 매개변수 폼을 동적으로 구성하거나, 요청 전 로컬 검증을 수행하는 데 적합합니다.

  > **하위 호환성**: `expand`를 생략하거나 인식되지 않는 값을 사용하면 응답은 기존 형식과 동일하므로 기존 클라이언트에 영향을 주지 않습니다.
</Info>

<Warning>
  **모델 범위**: 반환되는 모델은 API 키의 모델 제한과 소속 그룹에 따라 결정됩니다. `category=unknown`은 플랫폼에 해당 모델의 카테고리 메타데이터가 아직 등록되지 않았음을 의미합니다.
</Warning>

## 메타데이터가 포함된 모델 목록 가져오기

**GET** `/v1/models`

### 요청 헤더

```
Authorization: Bearer YOUR_API_KEY
```

### 쿼리 매개변수

| 매개변수       | 유형     |  필수 | 설명                                                                           |
| ---------- | ------ | :-: | ---------------------------------------------------------------------------- |
| `expand`   | string | 아니요 | `category`: 카테고리와 기능 태그 추가(경량), `parameters`: 매개변수 JSON Schema도 추가(전체, 큰 응답) |
| `category` | string | 아니요 | `chat` / `image` / `video` / `audio` / `unknown`으로 필터링. `expand`가 있을 때만 적용   |

반환되는 모델 범위는 `expand`를 생략했을 때와 동일하며 API 키의 모델 제한과 소속 그룹에 따라 결정됩니다.

### 예제 1: 카테고리만 조회

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

### 예제 2: 비디오 모델의 전체 매개변수 계약

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

단일 항목(`input_schema.properties`에는 일부 필드만 표시):

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

## 응답 필드

### 항목 필드

| 필드                                                                    | 유형        | 표시 조건                           | 설명                                               |
| --------------------------------------------------------------------- | --------- | ------------------------------- | ------------------------------------------------ |
| `id` / `object` / `created` / `owned_by` / `supported_endpoint_types` | -         | 항상                              | 기존 API와 동일                                       |
| `category`                                                            | string    | `expand` 사용 시                   | `chat` / `image` / `video` / `audio` / `unknown` |
| `capability_tags`                                                     | string\[] | `expand` 사용 시 태그가 있는 경우         | 아래 기능 태그 표 참조                                    |
| `parameters`                                                          | object    | `expand=parameters`이고 계약이 있는 경우 | 아래 parameters 블록 참조                              |

`category=unknown`은 플랫폼에 해당 모델의 카테고리 메타데이터가 아직 등록되지 않았음을 의미합니다(일반적으로 API 키 화이트리스트에 비표준 이름이 설정된 경우). 모델 자체는 정상적으로 호출할 수 있습니다.

### 기능 태그

| 카테고리  | 가능한 태그                                              |
| ----- | --------------------------------------------------- |
| 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 블록

| 필드                    | 설명                                                        |
| --------------------- | --------------------------------------------------------- |
| `operation`           | `image_generation` / `video_generation`                   |
| `method` + `endpoint` | 모델 호출에 사용할 HTTP 메서드와 경로(예: `POST /v1/videos/generations`) |
| `schema_version`      | 계약 버전(날짜). 버전 간에는 필드가 추가되기만 함                             |
| `source`              | 문제 해결을 위한 계약 데이터 소스. `base`는 공통 기본 계약만 있음을 의미             |
| `input_schema`        | JSON Schema draft 2020-12 형식의 전체 요청 본문 계약                 |

### input\_schema 읽는 방법

표준 JSON Schema이며 주요 도구(ajv, pydantic, openapi-generator 등)에서 직접 사용할 수 있습니다.

* **필수 매개변수** = 최상위 `required` 배열. `anyOf`는 “다음 조합 중 하나 이상”을 의미합니다(위 예제에서는 `prompt`, `messages` 또는 세 가지 참조 미디어 입력 중 하나)
* **열거형 값** = 속성의 `enum`
* **범위** = `minimum` / `maximum`
* **기본값** = `default`
* `additionalProperties: true`: 스키마에 없는 모델별 확장 매개변수도 허용합니다(`metadata`를 통해 전달)

## 단일 모델 조회

목록 API 외에도 단일 모델의 계약을 가져오는 전용 엔드포인트가 있습니다(동일한 구조에 멱등성과 응답 계약 설명 블록이 추가됨).

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

# 모델 이름에 "/"가 포함된 경우 쿼리 매개변수 형식 사용
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## 주의사항

1. **현재 chat / audio 모델에는 `category`와 `capability_tags`만 있으며 `parameters`는 없습니다**(매개변수 계약은 현재 image / video만 지원하며 이후 버전에서 추가될 예정입니다).
2. **스키마는 최선 노력 계약이며 최종적으로 서버 측 검증이 우선합니다**. 특정 해상도와 길이 조합 같은 일부 모델의 동적 제약이 스키마에 완전히 표현되지 않을 수 있으며, 서버가 요청을 거부하고 구체적인 이유를 반환할 수 있습니다.
3. **데이터 갱신 주기는 분 단위입니다**. 카탈로그가 캐시되므로 새 모델이나 매개변수 변경 사항이 반영되는 데 몇 분이 걸릴 수 있습니다.
4. **전체 `expand=parameters` 응답은 수백 KB에 이를 수 있습니다**. 가능하면 `category`로 필터링하고 `Accept-Encoding: gzip`을 사용하세요.
5. 이 매개변수는 OpenAI 형식 모델 목록에만 적용됩니다. Anthropic / Gemini 형식의 모델 목록 API는 `expand`를 지원하지 않습니다.