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": [
    {
      "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": "43ce3411-1a25-4d14-875e-3562d341b090",
          "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

API key must be prefixed 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,

request

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:

["43ce3411-1a25-4d14-875e-3562d341b090"]

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

Show child attributes

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.

Upload AssetUpload asset for the authenticated user's fal Assets library.

⌘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": [
    {
      "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": "43ce3411-1a25-4d14-875e-3562d341b090",
          "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"
  }
}