> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runcomfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Catalog Endpoints

These endpoints let you **discover** which models you can run and **inspect** the request body each one expects, without leaving the API. They are the programmatic equivalent of browsing [Models](https://www.runcomfy.com/models) and reading a model's Input schema on its API page.

Use them when you know what you want to generate but not which `model_id` provides it, or when you are generating request bodies from code and need the parameter names, types, and defaults.

***

## Endpoints

**Base URL**: `https://model-api.runcomfy.net`

| Endpoint                | Method | Purpose                                                |
| ----------------------- | ------ | ------------------------------------------------------ |
| `/v1/models`            | `GET`  | List the models your account can run                   |
| `/v1/models/categories` | `GET`  | List the capability categories models are grouped into |
| `/v1/models/{model_id}` | `GET`  | Get one model's full input schema                      |

Both require the same Bearer token as the rest of the Model API. See **[Authentication](/model-apis/authentication)**.

***

## List models

Returns every `model_id` that `POST /v1/models/{model_id}` accepts, with a summary of each model's inputs.

```
GET /v1/models
```

### Query parameters

| Parameter        | Type    | Required | Description                                                                                                                    |
| ---------------- | ------- | :------: | ------------------------------------------------------------------------------------------------------------------------------ |
| `search`         | string  |    No    | Case-insensitive substring match against `model_id`, `display_name`, and `description`. E.g. `kontext`, `upscale`, `lip sync`. |
| `category`       | string  |    No    | Filter by capability, e.g. `text-to-image`, `image-to-video`. See [List categories](#list-categories).                         |
| `kind`           | string  |    No    | Filter by how the model runs: `model`, `workflow`, or `inference`.                                                             |
| `include_schema` | boolean |    No    | Include each model's full `input_schema` inline. Much larger response. Default `false`.                                        |
| `limit`          | integer |    No    | Page size, `1`–`500`. Default `100`.                                                                                           |
| `offset`         | integer |    No    | Rows to skip. Default `0`.                                                                                                     |

<Note>
  `category` is **what the model does**; `kind` is **how it runs**. They are independent — filter on `category` unless you specifically care about the execution path.
</Note>

### Request example

```bash theme={null}
curl --request GET \
  --url "https://model-api.runcomfy.net/v1/models?search=kontext&limit=20" \
  --header "Authorization: Bearer <token>"
```

### Response example

```json theme={null}
{
  "models": [
    {
      "model_id": "blackforestlabs/flux-1-kontext/dev/image-to-image",
      "display_name": "Flux Kontext Dev",
      "description": "Edit visuals via text with multi-layer control and style memory.",
      "publisher": "blackforestlabs",
      "categories": ["image-to-image"],
      "kind": "model",
      "tags": ["By Function/IMAGE/Generate Image"],
      "model_url": "https://www.runcomfy.com/models/blackforestlabs/flux-1-kontext-dev",
      "base_price_usd": 0.06,
      "price_unit": "output",
      "pricing_note": "The rate is $0.06 per image.",
      "supported_batch_size": [1, 2, 3, 4],
      "inputs": ["aspect_ratio", "image_url", "prompt", "seed"],
      "required_inputs": ["prompt", "image_url"]
    }
  ],
  "total": 371,
  "limit": 20,
  "offset": 0
}
```

* `model_id` (string): Pass this to `POST /v1/models/{model_id}` to run the model.
* `display_name` (string): Human-readable name, e.g. `Flux Kontext Dev`.
* `description` (string): One-line summary of what the model does.
* `publisher` (string): First segment of the `model_id`, e.g. `blackforestlabs`.
* `categories` (string\[]): What the model does, e.g. `image-to-image`. A few models declare several.
* `kind` (string): How it runs — `model`, `workflow`, or `inference`.
* `model_url` (string): The model's page on runcomfy.com. Absent for models without a public page.
* `base_price_usd` (number): Base rate in US dollars, per `price_unit`.
* `price_unit` (string): `second` for duration-billed models, otherwise `output`.
* `pricing_note` (string): Human-readable rate, where the model publishes one.
* `supported_batch_size` (integer\[]): Batch sizes the model accepts.
* `inputs` (string\[]): Every parameter name the model accepts.
* `required_inputs` (string\[]): The subset you must supply.
* `total` (integer): Matches **before** paging — use it to drive `offset`.

`inputs` and `required_inputs` tell you whether a model fits your use case. For types, defaults, enums, and ranges, either fetch the model or pass `include_schema=true`.

<Warning>
  `base_price_usd` is a **base rate**, not a final price. Most models multiply it by inputs such as resolution or duration. For what a run actually cost, call `GET /v1/requests/{request_id}/result?include_cost=true`.
</Warning>

***

## List categories

Returns every capability category present in the catalog — the valid values for the `category` filter.

```
GET /v1/models/categories
```

### Response example

```json theme={null}
{
  "categories": [
    "audio-to-audio", "audio-to-video", "edit-video", "image-to-image",
    "image-to-video", "reference-to-video", "speech-to-video",
    "text-to-audio", "text-to-image", "text-to-video", "video-to-video"
  ]
}
```

This list is derived from the catalog itself, so it grows as new kinds of model are published.

***

## Get a model

Returns the same fields as a list entry plus `input_schema`, the JSON Schema for the request body.

```
GET /v1/models/{model_id}
```

### Path parameters

`model_id` string (required). The identifier exactly as listed, **slashes included** — they are path segments, not something to escape. E.g. `blackforestlabs/flux-1-kontext/pro/edit`.

### Request example

```bash theme={null}
curl --request GET \
  --url "https://model-api.runcomfy.net/v1/models/blackforestlabs/flux-1-kontext/pro/edit" \
  --header "Authorization: Bearer <token>"
```

### Response example

```json theme={null}
{
  "model_id": "blackforestlabs/flux-1-kontext/pro/edit",
  "display_name": "Flux Kontext Pro",
  "description": "Edit visuals via text with multi-layer control and style memory.",
  "publisher": "blackforestlabs",
  "categories": ["image-to-image"],
  "kind": "model",
  "base_price_usd": 0.044,
  "price_unit": "output",
  "inputs": ["aspect_ratio", "image_url", "prompt", "seed"],
  "required_inputs": ["prompt", "image_url"],
  "input_schema": {
    "type": "object",
    "required": ["prompt", "image_url"],
    "properties": {
      "prompt": {
        "type": "string",
        "description": "",
        "default": "Convert the scene to blue hour with soft drizzle"
      },
      "aspect_ratio": {
        "type": "string",
        "default": "16:9",
        "enum": ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16", "9:21"]
      },
      "image_url": {
        "type": "string",
        "format": "image_uri"
      },
      "num_inference_steps": {
        "type": "integer",
        "description": "The number of inference steps to perform.",
        "default": 28,
        "minimum": 10,
        "maximum": 50
      }
    }
  }
}
```

`input_schema` is the contract for the body you send to `POST /v1/models/{model_id}`. Each property carries its `type`, and where the model defines them: `default`, `description`, `enum` (the allowed values), `minimum`/`maximum`, `maxLength`, `minItems`/`maxItems`, and `multipleOf`.

Properties marked `"format": "image_uri"` (or `video_uri` / `audio_uri`, and their plural `_uris` forms) take a **publicly accessible HTTPS URL** — see [Image/Video/Audio Inputs](/model-apis/async-queue-endpoints#imagevideoaudio-inputs).

A few properties also carry `validations`, an array of API-enforced limits such as maximum upload size or image count.

<Note>
  The schema describes the **request body**, not the RunComfy web UI. Presentation-only hints that the playground uses to render its controls — `title`, `x-order`, `x-rc-group-id`, and widget-style `format` values like `int_slider_with_range` — are stripped, so `format` appears only when it marks a file input.
</Note>

An unknown `model_id` returns `404001 ResourceNotFound`. See **[Error Codes](/model-apis/error-codes)**.

***

## Discover, then run

The two endpoints compose into the normal flow:

```bash theme={null}
# 1. Find a model by capability
curl -s --url "https://model-api.runcomfy.net/v1/models?category=image-to-image&search=kontext" \
  --header "Authorization: Bearer <token>"

# 2. Read the schema it expects
curl -s --url "https://model-api.runcomfy.net/v1/models/blackforestlabs/flux-1-kontext/pro/edit" \
  --header "Authorization: Bearer <token>"

# 3. Run it
curl --request POST \
  --url "https://model-api.runcomfy.net/v1/models/blackforestlabs/flux-1-kontext/pro/edit" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{"prompt": "make it snow", "image_url": "https://example.com/photo.webp"}'
```

<Note>
  `base_price_usd` gives you the base rate up front, but most models multiply it by inputs such as resolution or duration, so treat it as an estimate. For what a run actually cost, call `GET /v1/requests/{request_id}/result?include_cost=true` — see **[Retrieve Request Results](/model-apis/async-queue-endpoints#retrieve-request-results)**. For remaining funds, see **[Balance](/account/balance)**.
</Note>