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.

Next steps