Model search

Unified endpoint for discovering model endpoints. Supports three usage modes:

1. List Mode (no parameters): Paginated list of all available model endpoints with minimal metadata.

2. Find Mode (endpoint_id parameter): Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs.

3. Search Mode (search parameters): Filter models by free-text query, category, or status.

Ordering (list/search):

sort=relevant uses Explore’s shared Trending browse order without keywords and relevance order with keywords. Trending data can fall back to publication dates when unavailable.
sort=recent sorts the complete filtered set by publication date (creation date when the publication date is missing), before pagination.
An explicit sort is acknowledged by ordering.sort. Omitting sort preserves the default response. Find mode always preserves the supplied endpoint ID order and has no ordering acknowledgement.
Keep sort, filters and limit unchanged when following next_cursor; cursors are page positions, not snapshots, and catalog/ranking updates can change later pages.

Expansion: Use expand to include additional data in each model object:

openapi-3.0 — full OpenAPI 3.0 schema in the openapi field
enterprise_status — enterprise readiness status (ready or pending) in the enterprise_status field

Examples of endpoint_id values:

fal-ai/flux/dev
fal-ai/wan/v2.2-a14b/text-to-video
fal-ai/minimax/video-01/image-to-video
fal-ai/hunyuan3d-v21

See fal.ai Model APIs for more details.

Authentication: Optional. Providing an API key grants higher rate limits.

Common Use Cases:

Browse available models for integration
Retrieve metadata for specific endpoints
Search for models by category or keywords
Get OpenAPI schemas for code generation
Build model selection interfaces

Authentication: not required.

GET

models

Model search

curl --request GET \
  --url https://api.fal.ai/v1/models \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/models', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "models": [
    {
      "endpoint_id": "fal-ai/flux/dev",
      "metadata": {
        "display_name": "FLUX.1 [dev]",
        "category": "text-to-image",
        "description": "Fast text-to-image generation",
        "status": "active",
        "tags": [
          "fast",
          "pro"
        ],
        "updated_at": "2025-01-15T12:00:00Z",
        "is_favorited": false,
        "thumbnail_url": "https://fal.media/files/example.jpg",
        "model_url": "https://fal.run/fal-ai/flux/dev",
        "date": "2024-08-01T00:00:00Z",
        "highlighted": false,
        "pinned": false
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

Key on the API preset, or any key whose permissions include the ones this API lists. APIs with no required permission accept any key. Prefix it with "Key ", e.g. Authorization: Key YOUR_API_KEY

Query Parameters

limit

integer

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Required range: x >= 1

Example:

50

cursor

string

Pagination cursor from previous response. Encodes the page number.

Example:

"Mg=="

endpoint_id

Endpoint ID(s) to retrieve (e.g., 'fal-ai/flux/dev'). Can be a single value or multiple values (1-50 models). When combined with search params, narrows results to these IDs. Use array syntax: ?endpoint_id=model1&endpoint_id=model2

Example:

["fal-ai/flux/dev", "fal-ai/flux-pro"]

string

Free-text search query to filter models by name, description, or category

Example:

"text to image"

Response

Successfully retrieved model endpoints

Response containing model data with pagination support

models

object[]

required

Array of model information

Hide child attributes

models.endpoint_id

string

required

Stable identifier used to call the model (e.g., 'fal-ai/wan/v2.2-a14b/text-to-video', 'fal-ai/minimax/video-01/image-to-video', 'fal-ai/hunyuan3d-v21')

models.metadata

object

Model metadata (optional - may be absent for endpoints without registry entries)

Hide child attributes

models.metadata.display_name

string

required

Human-readable label shown on Explore/Model pages

models.metadata.category

string

required

Model category (e.g., 'text-to-image', 'image-to-video', 'text-to-video', 'image-to-3d', 'training')

models.metadata.description

string

required

Brief description of the model's capabilities and use cases

models.metadata.status

enum<string>

required

'active' or 'deprecated'. Newest models are surfaced in Explore and may be flagged as 'new/beta' in tags

Available options:

active,

deprecated

models.metadata.tags

string[]

required

Freeform tags such as 'new', 'beta', 'pro', or 'turbo' (Explore badges)

models.metadata.updated_at

string

required

ISO8601 timestamp of when the model was last updated

models.metadata.is_favorited

boolean | null

required

Whether the model is favorited by the authenticated user (null when unauthenticated)

models.metadata.thumbnail_url

string

required

Main thumbnail image URL

models.metadata.model_url

string

required

Full model endpoint URL (e.g., https://fal.run/...)

models.metadata.date

string

required

ISO8601 timestamp of model creation

models.metadata.highlighted

boolean

required

deprecated

Whether the model is highlighted (deprecated, always false)

Example:

false

models.metadata.pinned

boolean

required

deprecated

Whether the model is pinned (deprecated, always false)

Example:

false

models.metadata.thumbnail_animated_url

string

Animated thumbnail URL (optional)

models.metadata.github_url

string

License or GitHub URL (optional)

models.metadata.license_type

enum<string>

License type for the model (optional)

Available options:

commercial,

research,

private

models.metadata.group

object

Model group information (optional)

Hide child attributes

models.metadata.group.key

string

required

Group key identifier

models.metadata.group.label

string

required

Human-readable group label

models.metadata.kind

enum<string>

Model kind - inference or training (optional)

Available options:

inference,

training

models.metadata.training_endpoint_ids

string[]

Related training endpoint IDs (optional, only present when non-empty, for inference models)

models.metadata.inference_endpoint_ids

string[]

Related inference endpoint IDs (optional, only present when non-empty, for training models)

models.metadata.stream_url

string

Streaming endpoint URL (optional)

models.metadata.duration_estimate

number

Estimated duration in minutes (optional)

models.openapi

object

OpenAPI 3.0 specification or error (present when expand=openapi-3.0 is requested)

Option 1
Option 2

Hide child attributes

models.openapi.openapi

string

required

OpenAPI version (e.g., '3.0.4')

models.openapi.{key}

any

models.enterprise_status

Enterprise readiness status (present when expand=enterprise_status is requested)

Available options:

ready,

pending

has_more

boolean

required

Boolean indicating if more results are available (convenience field derived from next_cursor)

next_cursor

string | null

Cursor for the next page of results, null if no more pages

ordering

object

Acknowledges an explicitly requested list/search sort. Absent on legacy default requests and endpoint_id find mode. Relevant is shared discovery ordering, not a quality or latency ranking; its Trending data can fall back to publication dates when unavailable.

Hide child attributes

ordering.sort

enum<string>

required

List/search ordering applied to this response

Available options:

relevant,

recent

⌘I

Model search

curl --request GET \
  --url https://api.fal.ai/v1/models \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/models', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "models": [
    {
      "endpoint_id": "fal-ai/flux/dev",
      "metadata": {
        "display_name": "FLUX.1 [dev]",
        "category": "text-to-image",
        "description": "Fast text-to-image generation",
        "status": "active",
        "tags": [
          "fast",
          "pro"
        ],
        "updated_at": "2025-01-15T12:00:00Z",
        "is_favorited": false,
        "thumbnail_url": "https://fal.media/files/example.jpg",
        "model_url": "https://fal.run/fal-ai/flux/dev",
        "date": "2024-08-01T00:00:00Z",
        "highlighted": false,
        "pinned": false
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}