Browse assets

GET

assets

Browse assets

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

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

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

{
  "assets": [
    {
      "asset_id": "d8b6elcregj72v34jr8g",
      "vector_id": "b1a2b4a5-cb89-51dc-a108-6dbfd8e742fc",
      "request_id": "019e6d0a-e5be-7b82-b329-35ae64296902",
      "url": "https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png",
      "type": "image",
      "title": "Cinematic portrait",
      "endpoint": "fal-ai/flux/dev",
      "created_at": "2026-05-23T20:00:00.000Z",
      "source": "upload",
      "prompt": "cinematic portrait of a character",
      "width": 1024,
      "height": 1024,
      "content_type": "image/png",
      "is_favorited": false,
      "collection_ids": [
        "d8b6elcregj72v34jr8g"
      ],
      "tags": [
        {
          "id": "d9k7q2m4n6p8r1s3t5uv",
          "name": "moodboard",
          "created_at": "2026-05-23T20:00:00.000Z"
        }
      ],
      "similarity": 0.92
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total_count": 1,
  "scope_truncated": false
}

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

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

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

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

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

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

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

{
  "error": {
    "type": "server_error",
    "message": "Upstream asset service failed"
  }
}

Authorizations

Authorization

string

header

required

Key on the READONLY preset, or any key whose permissions include the ones this API lists. 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=="

string

Text query for hybrid semantic search

Example:

"cinematic portrait"

search_image_url

string<uri>

fal-hosted image URL to use for semantic image search

Example:

"https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png"

search_video_url

string<uri>

fal-hosted video URL to use for semantic video search

Example:

"https://fal.media/files/example.mp4"

media_type

enum<string>[] | null

Filter by one or more media types

Asset media type

Available options:

image,

video,

audio,

3d

Example:

["image", "video"]

source

enum<string>[] | null

Filter by one or more indexed sources

Indexed asset source

Available options:

upload,

response

Example:

["upload", "response"]

section

enum<string>

default:all-media

Asset library section to browse

Available options:

all-media,

uploads,

favorites,

generated

Example:

"all-media"

collection_id

string

Collection scope to browse

Example:

"d8b6elcregj72v34jr8g"

character_identifier

string[] | null

Character identifiers to use as @mention semantic filters

Example:

["alice"]

tag_id

string[] | null

Tag IDs to filter by

Example:

["d9k7q2m4n6p8r1s3t5uv"]

tag_mode

enum<string>

default:any

Whether tag filters match any tag or all tags

Available options:

any,

all

Example:

"any"

Response

Successfully browsed assets

Paginated asset browse response

assets

object[]

required

Asset results

Hide child attributes

assets.asset_id

string | null

required

Asset ID (canonical catalog identity)

Example:

"d8b6elcregj72v34jr8g"

assets.vector_id

string

required

Vector ID. Prefer asset_id for addressing

Example:

"b1a2b4a5-cb89-51dc-a108-6dbfd8e742fc"

assets.request_id

string | null

required

Request ID

Example:

"019e6d0a-e5be-7b82-b329-35ae64296902"

assets.url

string | null

required

Media URL

Example:

"https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png"

assets.type

enum<string>

required

Asset media type

Available options:

image,

video,

audio,

3d

assets.title

string

required

Display title

Example:

"Portrait"

assets.endpoint

string | null

required

Model endpoint that produced the asset

Example:

"fal-ai/flux/dev"

assets.created_at

string | null

required

Asset creation time

Example:

"2026-05-23T20:00:00.000Z"

assets.source

string | null

required

Asset source

Example:

"upload"

assets.prompt

string | null

required

Saved prompt or description

Example:

"cinematic portrait"

assets.width

number | null

required

Width in pixels

Example:

1024

assets.height

number | null

required

Height in pixels

Example:

1024

assets.content_type

string | null

required

Media content type

Example:

"image/png"

assets.is_favorited

boolean

required

Whether the asset is favorited

Example:

false

assets.collection_ids

string[]

required

Collections containing this asset

Example:

["d8b6elcregj72v34jr8g"]

assets.tags

object[]

required

Assigned tags

Hide child attributes

assets.tags.id

string

required

Tag ID

Example:

"d9k7q2m4n6p8r1s3t5uv"

assets.tags.name

string

required

Tag name

Example:

"moodboard"

assets.tags.created_at

string | null

required

Tag creation time

Example:

"2026-05-23T20:00:00.000Z"

assets.similarity

number | null

required

Semantic similarity score when applicable

Example:

0.92

next_cursor

string | null

required

Cursor for the next page

has_more

boolean

required

Whether more results are available

total_count

number | null

required

Exact total when available; null when unavailable

scope_truncated

boolean

required

True when the requested scope (favorites, tags, or collection membership) exceeded the maximum number of assets a single search can cover, so results were drawn from a partial slice of it and some matches are missing. Narrow the scope for complete results. total_count remains accurate for the results that were returned.

⌘I

Browse assets

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

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

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

{
  "assets": [
    {
      "asset_id": "d8b6elcregj72v34jr8g",
      "vector_id": "b1a2b4a5-cb89-51dc-a108-6dbfd8e742fc",
      "request_id": "019e6d0a-e5be-7b82-b329-35ae64296902",
      "url": "https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png",
      "type": "image",
      "title": "Cinematic portrait",
      "endpoint": "fal-ai/flux/dev",
      "created_at": "2026-05-23T20:00:00.000Z",
      "source": "upload",
      "prompt": "cinematic portrait of a character",
      "width": 1024,
      "height": 1024,
      "content_type": "image/png",
      "is_favorited": false,
      "collection_ids": [
        "d8b6elcregj72v34jr8g"
      ],
      "tags": [
        {
          "id": "d9k7q2m4n6p8r1s3t5uv",
          "name": "moodboard",
          "created_at": "2026-05-23T20:00:00.000Z"
        }
      ],
      "similarity": 0.92
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total_count": 1,
  "scope_truncated": false
}

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

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

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

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

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

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

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

{
  "error": {
    "type": "server_error",
    "message": "Upstream asset service failed"
  }
}