Skip to main content
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 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 Both require the same Bearer token as the rest of the Model API. See Authentication.

​
List models

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

​
Query parameters

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.

​
Request example

​
Response example

  • 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.
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.

​
List categories

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

​
Response example

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.

​
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

​
Response example

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. A few properties also carry validations, an array of API-enforced limits such as maximum upload size or image count.
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.
An unknown model_id returns 404001 ResourceNotFound. See Error Codes.

​
Discover, then run

The two endpoints compose into the normal flow:
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. For remaining funds, see Balance.