# Getting started

The Faceless API turns a narration script into a finished faceless video (AI visuals, TTS voiceover, captions) and publishes it to connected YouTube, TikTok, Instagram, X, Facebook, LinkedIn and Threads accounts. This guide takes you from an empty terminal to a published video.

Base URL: `https://faceless.so/api/v1`. Every response uses one envelope: `{ "success": true, "data": ..., "pagination"? }` on success, `{ "success": false, "error": { "type", "message" } }` on failure.

## 1. Create an API key

Create a key in the dashboard, in your team settings at https://faceless.so/team. Pick the scopes the key needs; for this guide use `catalog:read`, `videos:read`, `videos:write` and `posts:write`. Keys look like `fl_live_...` and the full key is shown once at creation, so store it somewhere safe (an environment variable or secret manager).

```bash
export FACELESS_API_KEY=fl_live_...
```

## 2. Verify auth with /me

`GET /me` works with any valid key and returns your team, credit balance, plan and the scopes granted to the key.

```bash
curl -s https://faceless.so/api/v1/me \
  -H "Authorization: Bearer $FACELESS_API_KEY"
```

Or with the CLI:

```bash
npm install -g faceless-cli
faceless login        # or rely on the FACELESS_API_KEY env var
faceless whoami --json
```

## 3. Pick a voice

Every video needs a TTS voice for the narration. List the catalog and note a voice `id`:

```bash
curl -s https://faceless.so/api/v1/voices \
  -H "Authorization: Bearer $FACELESS_API_KEY"
```

```bash
faceless voices --json
```

Other catalogs (visual styles, niches, models with their credit costs) live at `GET /options?kind=...`; see `faceless options`.

## 4. Create a video

`POST /videos` takes a finished script and starts generation. Credits are charged now, at creation: 20 for `storyboard`, 50 for `motion_lite`, 100 for `motion_pro`. The call returns immediately with the video id.

```bash
curl -s -X POST https://faceless.so/api/v1/videos \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script": "Did you know the ocean has lakes and rivers of its own? ...", "voiceId": "EXAVITQu4vr4xnSDxMaL", "model": "storyboard"}'
```

```bash
faceless videos create --script "Did you know..." --voice-id EXAVITQu4vr4xnSDxMaL --model storyboard --wait --json
```

## 5. Poll until generation completes

Poll `GET /videos/{id}/status` every 10 to 30 seconds until `status` is `completed` (or `failed`; check `errorMessages`). The CLI's `--wait` flag in step 4 does this for you.

```bash
curl -s https://faceless.so/api/v1/videos/<videoId>/status \
  -H "Authorization: Bearer $FACELESS_API_KEY"
```

## 6. Render the MP4

Rendering is a separate, free step. `POST /videos/{id}/render` returns a `renderId`; poll `GET /renders/{renderId}` every 5 to 15 seconds until `status` is `done`, which includes the final MP4 `url`.

```bash
curl -s -X POST https://faceless.so/api/v1/videos/<videoId>/render \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codec": "h264"}'

curl -s https://faceless.so/api/v1/renders/<renderId> \
  -H "Authorization: Bearer $FACELESS_API_KEY"
```

```bash
faceless videos render <videoId> --wait --json
```

## 7. Publish

Publishing is free. Post the rendered video to a connected platform now:

```bash
curl -s -X POST https://faceless.so/api/v1/posts \
  -H "Authorization: Bearer $FACELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoId": "<videoId>", "platform": "youtube", "title": "The ocean has rivers underwater"}'
```

```bash
faceless posts publish --video-id <videoId> --platform youtube --title "The ocean has rivers underwater" --json
```

Connecting accounts (OAuth) happens in the web app, not over the API; `GET /accounts` lists what is connected. For future-dated posting see [publishing and scheduling](/developers/docs/publishing-and-scheduling).

## Next steps

- [Authentication and scopes](/developers/docs/authentication)
- [Videos](/developers/docs/videos) for the full lifecycle in detail
- [Series](/developers/docs/series) to automate a whole channel
- [CLI](/developers/docs/cli) and [MCP](/developers/docs/mcp)
- Full endpoint reference: [/developers/reference](/developers/reference) or https://faceless.so/llms.txt for agents