> ## 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` は「次の組み合わせのうち少なくとも1つ」を意味します（上の例では `prompt`、`messages`、3種類の参照メディア入力の5つから1つ）
* **列挙値** = プロパティの `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` をサポートしません。