> ## 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 metadata daftar model

>  - GET /v1/models: daftar dasar dengan kategori, kemampuan, dan skema parameter melalui expand
- Mendukung filter `category` dan JSON Schema melalui `expand=parameters`
- Cocok untuk otomatisasi, formulir dinamis, dan validasi awal 

<Info>
  **API metadata daftar model** (`GET /v1/models`) secara default hanya mengembalikan kolom dasar seperti nama model. Menambahkan parameter kueri `expand` akan menyertakan informasi berikut pada setiap model:

  * **Kategori** (`category`): `chat` / `image` / `video` / `audio`
  * **Tag kemampuan** (`capability_tags`): misalnya `Text to Video` dan `Image to Image`
  * **Kontrak parameter** (`parameters`): JSON Schema standar yang menunjukkan kolom wajib/opsional, enumerasi, rentang, dan nilai default

  Gunakan API ini untuk mengambil katalog lengkap sekali lalu membuat kode klien, membangun formulir parameter secara dinamis, atau memvalidasi permintaan secara lokal sebelum dikirim.

  > **Kompatibilitas mundur**: tanpa `expand` (atau dengan nilai yang tidak dikenali), respons identik dengan format yang sudah ada sehingga klien lama tidak terpengaruh.
</Info>

<Warning>
  **Cakupan model**: model yang dikembalikan ditentukan oleh pembatasan model dan grup yang ditetapkan pada API key. `category=unknown` berarti platform belum mencatat metadata kategori model tersebut.
</Warning>

## Mendapatkan daftar model dengan metadata

**GET** `/v1/models`

### Header permintaan

```
Authorization: Bearer YOUR_API_KEY
```

### Parameter kueri

| Parameter  | Tipe   | Wajib | Deskripsi                                                                                                                                 |
| ---------- | ------ | :---: | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `expand`   | string | Tidak | `category`: menambahkan kategori dan tag kemampuan (ringan); `parameters`: juga menambahkan JSON Schema parameter lengkap (respons besar) |
| `category` | string | Tidak | Memfilter berdasarkan `chat` / `image` / `video` / `audio` / `unknown`. Hanya berlaku saat `expand` diberikan                             |

Cakupan model yang dikembalikan sama seperti saat `expand` tidak digunakan: ditentukan oleh pembatasan model dan grup yang ditetapkan pada API key.

### Contoh 1: hanya kategori

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

### Contoh 2: kontrak parameter lengkap untuk model video

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

Satu item (`input_schema.properties` hanya menampilkan sebagian kolom):

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

## Kolom respons

### Kolom item

| Kolom                                                                 | Tipe      | Kondisi                                         | Deskripsi                                        |
| --------------------------------------------------------------------- | --------- | ----------------------------------------------- | ------------------------------------------------ |
| `id` / `object` / `created` / `owned_by` / `supported_endpoint_types` | -         | Selalu                                          | Sama seperti API yang sudah ada                  |
| `category`                                                            | string    | Dengan `expand`                                 | `chat` / `image` / `video` / `audio` / `unknown` |
| `capability_tags`                                                     | string\[] | Dengan `expand` dan jika ada tag                | Lihat tabel tag kemampuan                        |
| `parameters`                                                          | object    | Dengan `expand=parameters` dan jika ada kontrak | Lihat blok parameters                            |

`category=unknown` berarti platform belum mencatat metadata kategori model tersebut (biasanya nama nonstandar yang dikonfigurasi dalam daftar model yang diizinkan untuk API key). Model tetap dapat dipanggil seperti biasa.

### Tag kemampuan

| Kategori | Tag yang mungkin                                    |
| -------- | --------------------------------------------------- |
| 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`                                             |

### Blok parameters

| Kolom                 | Deskripsi                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------- |
| `operation`           | `image_generation` / `video_generation`                                                       |
| `method` + `endpoint` | Metode HTTP dan path untuk memanggil model (misalnya `POST /v1/videos/generations`)           |
| `schema_version`      | Versi kontrak (tanggal); antarversi hanya menambahkan kolom                                   |
| `source`              | Sumber data kontrak untuk pemecahan masalah; `base` berarti hanya tersedia kontrak dasar umum |
| `input_schema`        | Kontrak lengkap body permintaan dalam JSON Schema draft 2020-12                               |

### Cara membaca input\_schema

Ini adalah JSON Schema standar yang dapat langsung digunakan oleh alat umum seperti ajv, pydantic, dan openapi-generator.

* **Parameter wajib** = array `required` tingkat atas; `anyOf` berarti “setidaknya satu dari kombinasi berikut” (pada contoh di atas, salah satu dari `prompt`, `messages`, atau tiga input media referensi)
* **Nilai enumerasi** = `enum` pada properti
* **Rentang** = `minimum` / `maximum`
* **Nilai default** = `default`
* `additionalProperties: true`: mengizinkan parameter ekstensi khusus model yang tidak tercantum dalam skema (diteruskan melalui `metadata`)

## Meminta satu model

Selain daftar, tersedia endpoint khusus untuk kontrak satu model (struktur yang sama, dengan blok tambahan yang menjelaskan idempotensi dan kontrak respons):

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

# Untuk nama model yang mengandung "/", gunakan bentuk parameter kueri
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Catatan

1. **Saat ini model chat / audio hanya memiliki `category` dan `capability_tags`, tanpa `parameters`** (kontrak parameter saat ini mencakup image / video dan akan ditambahkan untuk kategori lain pada versi berikutnya).
2. **Skema merupakan kontrak upaya terbaik; validasi sisi server tetap menjadi acuan akhir**. Beberapa batasan dinamis, seperti kombinasi resolusi dan durasi tertentu, mungkin tidak sepenuhnya dinyatakan dalam skema. Server masih dapat menolak permintaan dan memberikan alasan tertentu.
3. **Kesegaran data dihitung dalam menit**. Katalog disimpan dalam cache, sehingga model baru atau perubahan parameter mungkin membutuhkan beberapa menit untuk muncul.
4. **Respons lengkap `expand=parameters` dapat mencapai ratusan KB**. Filter dengan `category` jika memungkinkan dan kirim `Accept-Encoding: gzip`.
5. Parameter ini hanya berlaku untuk daftar model berformat OpenAI. Daftar model berformat Anthropic / Gemini tidak mendukung `expand`.