List asset characters

GET

assets

characters

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

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

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

{
  "characters": [
    {
      "id": "d7tatpsregjaga2cf3d0",
      "type": "character",
      "name": "Alice",
      "description": "A character with red hair and a blue jacket",
      "icon": "folder",
      "color": "blue",
      "cover_image_url": "https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png",
      "character_identifier": "alice",
      "parent_collection_id": null,
      "is_favorited": false,
      "created_at": "2026-05-23T20:00:00.000Z",
      "updated_at": "2026-05-23T20:00:00.000Z",
      "asset_count": null,
      "reference_images": [
        "https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png"
      ]
    }
  ]
}

{
  "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

default:50

Maximum number of collections to return

Required range: 1 <= x <= 100

Example:

50

offset

integer | null

default:0

Number of collections to skip

Required range: x >= 0

Example:

0

Response

Characters

characters

object[]

required

Asset characters visible to the authenticated user

Show child attributes

Create Asset CharacterCreate an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.

⌘I

List asset characters

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

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

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

{
  "characters": [
    {
      "id": "d7tatpsregjaga2cf3d0",
      "type": "character",
      "name": "Alice",
      "description": "A character with red hair and a blue jacket",
      "icon": "folder",
      "color": "blue",
      "cover_image_url": "https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png",
      "character_identifier": "alice",
      "parent_collection_id": null,
      "is_favorited": false,
      "created_at": "2026-05-23T20:00:00.000Z",
      "updated_at": "2026-05-23T20:00:00.000Z",
      "asset_count": null,
      "reference_images": [
        "https://v3b.fal.media/files/b/0a9b4900/PDbTGyzqRh1aijW2WQiY9_opengraph-1%20%281%29.png"
      ]
    }
  ]
}

{
  "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"
  }
}