Models List Metadata API

• GET /v1/models — basic list
• • expand query parameter to include category, capability tags, and parameter schema
• For automation, dynamic forms, pre-validation

GET /v1/models

Models List Metadata API

cURL

curl --request GET \
  --url https://api.apimart.ai/v1/models

The model list metadata endpoint (GET /v1/models) returns only basic fields such as the model name by default. Adding the expand query parameter appends the following metadata to each model:

• Category (category): chat / image / video / audio
• Capability tags (capability_tags): such as Text to Video and Image to Image
• Parameter schema (parameters): standard JSON Schema indicating required/optional, enums, ranges, and defaults

Use it to fetch the full catalog once and generate client code, build parameter forms dynamically, or validate requests locally before sending them.

Backward compatible: Without expand (or with an unrecognized value), the response is identical to the existing format, so existing clients are unaffected.

Model scope: The returned models are controlled by the API key’s model restrictions and assigned group. category=unknown means that the platform has not yet cataloged the model’s category metadata.

Get model list (with metadata)

GET /v1/models

Request headers

Authorization: Bearer YOUR_API_KEY

Query parameters

Parameter	Type	Required	Description
expand	string	No	category adds category and capability tags (lightweight); parameters adds full JSON Schema (full payload, large response)
category	string	No	Filter by category: chat / image / video / audio / unknown. Only effective when expand is provided.

The returned model scope is the same as when expand is omitted: it is controlled by the API key’s model restrictions and assigned group.

Example 1: Just category

cURL

curl -s "https://api.apimart.ai/v1/models?expand=category" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Example 2: Full parameter contract for video models

cURL

curl -s "https://api.apimart.ai/v1/models?expand=parameters&category=video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept-Encoding: gzip" --compressed

Single item (input_schema.properties shows only selected fields):

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

Response field description

Item fields

Field	Type	Condition	Description
id / object / created / owned_by / supported_endpoint_types	-	Always	Same as legacy interface
category	string	With expand	chat / image / video / audio / unknown
capability_tags	string[]	With expand and tags	See capability tags table
parameters	object	expand=parameters and contract present	See parameters block

category=unknown indicates the platform has not yet cataloged metadata for that model (usually non-standard names configured in the Key’s whitelist). The model itself can still be called normally.

Capability tags

Category	Possible tags
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 block

Field	Description
operation	image_generation / video_generation
method + endpoint	HTTP method and path the model should use (e.g. POST /v1/videos/generations)
schema_version	Contract version (date); fields only add, never remove
source	Contract source for debugging; base means only generic base contract
input_schema	JSON Schema draft 2020-12 — full request body contract

How to read input_schema

Standard JSON Schema. Most tooling (ajv, pydantic, openapi-generator, etc.) can consume it directly:

• Required parameters = the top-level required array; anyOf means “at least one of the following combinations” (in the example above, choose one of prompt, messages, or the three reference-media inputs)
• Enum values = enum on properties
• Range = minimum / maximum
• Default = default
• additionalProperties: true — allows extra fields not listed in the schema (typically passed via metadata)

Query a single model

In addition to the list, single-model contracts have a dedicated endpoint (same shape, with extra idempotency and response contract explanation blocks):

curl -s "https://api.apimart.ai/v1/models/wan2.6/schema" \
  -H "Authorization: Bearer YOUR_API_KEY"

# For model names containing "/", use the query-parameter form
curl -s "https://api.apimart.ai/v1/model-schema?model=provider/model-name" \
  -H "Authorization: Bearer YOUR_API_KEY"

Notes

1. Chat / audio models currently only have category and capability_tags, with no parameters (parameter contracts currently cover image / video only and will be added for other categories in later versions).
2. The schema is a best-effort contract; server-side validation is authoritative: some dynamic constraints, such as specific resolution and duration combinations, may not be fully expressed in the schema. The server may still reject a request and return a specific reason.
3. Data freshness is measured in minutes: the catalog is cached, so newly added models or parameter changes may take a few minutes to appear.
4. A full expand=parameters response can reach hundreds of KB: filter by category when possible and send Accept-Encoding: gzip.
5. This parameter only affects OpenAI-format model lists; Anthropic / Gemini dialect model lists do not support expand.