Faceless.so

Faceless.so turns a narration script into a finished faceless video: TTS voiceover, AI-generated visuals, captions and music. Videos render in the cloud and publish to connected YouTube, TikTok, Instagram, X, Facebook, LinkedIn and Threads accounts, either immediately or on a schedule. Series generate and post new episodes automatically.

When to use this skill

"Make a faceless video from this script" -> videos create, poll status, render, publish
"Post this to YouTube Shorts / TikTok" or "schedule it for Friday 6pm" -> posts publish or posts schedule
"Set up a channel that posts a scary story every day" -> series create
"Generate the next episode now" -> series generate
"What is queued? How did my posts do?" -> calendar, analytics
"How many Faceless credits do I have?" -> credits

Setup: install the CLI if missing

Check the CLI: faceless --version
If not found, install it: npm install -g faceless-cli (or use npx -y faceless-cli <command> without installing)
Authenticate, one of:
- FACELESS_API_KEY environment variable already set: nothing to do
- Otherwise ask the user for an API key (created at https://faceless.so/developers) and run faceless login
Verify: faceless whoami

If npm is unavailable, fall back to the raw HTTP API (see the last section).

Core concepts

A team owns credits, API keys and connected social accounts; every command runs in the key's team context (faceless whoami shows it).
Credits are charged at video creation time, by model: storyboard 20, motion_lite 50, motion_pro 100 credits per video. Rendering and publishing are free.
Videos generate asynchronously: videos create returns an id immediately; poll videos status until completed, then videos render and poll renders get for the MP4 URL.
Series are set-and-forget channels: they generate and auto-post a new episode on their schedule, charging the per-episode model cost each time.
Scheduling to a platform requires that platform's post metadata on the video first (videos update), and a connected account (faceless accounts).
Always pass --json when running commands from a script or agent and parse the success field.

Command reference

Command	What it does	Endpoint
`faceless whoami`	Identify the caller	GET /me
`faceless credits`	Credit balance and history	GET /credits
`faceless buy-credits`	Buy a credit pack with an agent payment token	POST /credits
`faceless videos create`	Create a faceless video from a script	POST /videos
`faceless videos captions`	Caption an existing video or audio file	POST /videos/captions
`faceless videos list`	List the team's videos	GET /videos
`faceless videos get`	Get one video	GET /videos/{id}
`faceless videos update`	Update a video's name or post metadata	PATCH /videos/{id}
`faceless videos select-thumbnail`	Choose which thumbnail a video uses	POST /videos/{id}/thumbnail
`faceless videos status`	Poll video generation progress	GET /videos/{id}/status
`faceless videos render`	Render a video to MP4	POST /videos/{id}/render
`faceless videos delete`	Delete a video	DELETE /videos/{id}
`faceless renders get`	Poll render progress	GET /renders/{id}
`faceless series create`	Create an automated video series	POST /series
`faceless series list`	List the team's series	GET /series
`faceless series get`	Get one series	GET /series/{id}
`faceless series update`	Update a series	PATCH /series/{id}
`faceless series delete`	Delete a series	DELETE /series/{id}
`faceless series generate`	Generate the next episode now	POST /series/{id}/generate
`faceless series episodes`	List a series' episodes	GET /series/{id}/episodes
`faceless posts publish`	Publish a rendered video to a platform now	POST /posts
`faceless posts schedule`	Schedule a video to one or more platforms	POST /posts/schedule
`faceless posts cancel`	Cancel a scheduled post	DELETE /posts/{id}
`faceless calendar`	Posting calendar	GET /calendar
`faceless accounts`	List connected social accounts	GET /accounts
`faceless voices`	List TTS voices	GET /voices
`faceless options`	List content option catalogs	GET /options
`faceless assets create`	Register a media asset by URL	POST /assets
`faceless analytics`	Cross-platform posting analytics	GET /analytics
`faceless ads search`	Search Meta ads shown in the EU and UK	GET /ads/search
`faceless ads saved`	List the team's saved ads	GET /saved-ads
`faceless ads save`	Save an ad from a search	POST /saved-ads
`faceless ads unsave`	Remove a saved ad	DELETE /saved-ads/{id}
`faceless ads brief`	Write an ad brief for your brand from a competitor's ad	POST /ads/briefs

Full flag-level detail: references/api-reference.md (or https://faceless.so/llms-full.txt).

Common workflows

Script to published video, end to end

faceless videos create --script "Did you know the ocean has rivers of its own? ..." \
  --voice-id EXAVITQu4vr4xnSDxMaL --model storyboard --json   # charges 20 credits, returns id
faceless videos status <videoId> --json    # poll every 10-30s until status "completed"
faceless videos render <videoId> --json    # returns renderId
faceless renders get <renderId> --json     # poll every 5-15s until status "done", gives the MP4 url
faceless posts publish --video-id <videoId> --platform youtube --title "Underwater rivers are real" --json

Pick a voice with faceless voices --json; enumerate styles, niches, models and more with faceless options --kind <kind> --json.

Automated series

faceless series create --name "Deep sea facts" --source "Facts & stories" \
  --niche "Ocean facts" --voice EXAVITQu4vr4xnSDxMaL --duration 60 \
  --auto-post-time 18:00 --timezone America/New_York --json
faceless series generate <seriesId> --json   # force the next episode now (charges the model cost)
faceless series episodes <seriesId> --json   # track output

Schedule one video to several platforms

faceless videos update <videoId> \
  --youtube-title "Underwater rivers are real" --tiktok-title "underwater rivers #ocean" --json
faceless posts schedule --video-id <videoId> --platforms youtube,tiktok \
  --scheduled-time "2026-08-01T18:00:00Z" --json
faceless calendar --start-date 2026-08-01 --end-date 2026-08-07 --json   # confirm the queue

Every platform in --platforms must have its post metadata set on the video first; scheduling rejects platforms whose metadata is missing. Cancel with faceless posts cancel <videoId> --json.

Error handling

Errors look like { "success": false, "error": { "type", "message" } }.

unauthorized (401): re-run faceless login (or fix FACELESS_API_KEY)
forbidden_scope (403): the key lacks a scope; ask the user to create a key with the needed scopes at https://faceless.so/developers
insufficient_credits (402): tell the user to buy credits at https://faceless.so/credits
rate_limited (429): respect the Retry-After header, wait and retry
invalid_input (400): fix the flags per references/api-reference.md
not_found (404): the id is wrong or belongs to another team

Raw HTTP fallback (no CLI)

Base URL https://faceless.so/api/v1, header Authorization: Bearer $FACELESS_API_KEY.

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

Machine-readable surface: https://faceless.so/api/v1/openapi.json and https://faceless.so/llms-full.txt. A remote MCP server is also available at https://faceless.so/api/v1/mcp (same Authorization header).