Assets

Assets are media files (video, image or audio) in your team's library, usable in projects and the editor. Over the API, assets are registered by URL: you host the file anywhere public and hand Faceless the link. Raw byte uploads are a dashboard feature, not an API one; upload files in the web app when you do not have a public URL.

Register an asset (POST /assets, scope assets:write)

bash 
curl -s -X POST https://faceless.so/api/v1/assets \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url": "https://example.com/broll.mp4", "name": "Intro b-roll", "fileType": "video/mp4"}'

Response (201):

json 
{
  "success": true,
  "data": { "id": "665f1b2a9c31a2b3c4d5ef01", "url": "https://example.com/broll.mp4", "name": "Intro b-roll" }
}

Fields:

  • url (required): a public URL to the media file. The platform fetches from it, so it must be reachable without auth and should stay live for as long as projects reference it.
  • name (optional): display name in the library; defaults from the URL.
  • fileType (optional): MIME type hint so the file lands in the right bucket, e.g. video/mp4, image/png, audio/mpeg. Inferred from the URL when omitted.

Registering the same URL twice creates two library entries; use an Idempotency-Key on retries to avoid duplicates (see errors and rate limits).

With the CLI

bash 
faceless assets create --url https://example.com/broll.mp4 --name "Intro b-roll" --json

Common errors

  • invalid_input (400): the url is missing or not a valid URL.
  • forbidden_scope (403): the key lacks assets:write.

No credits are charged for registering assets.