# 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](/developers/docs/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.