Syllaby CLI

The official command-line interface for the Syllaby v2 public API — generate faceless videos, text-to-video clips, storyboards, and launch clips straight from your terminal, with the same API keys, credits, and rate limits as the REST API.

Install

The CLI ships as @syllaby-ai/cli on npm and requires Node.js 22 or newer.

npm install -g @syllaby-ai/cli
syllaby --version

Every command and option is also discoverable from the terminal: syllaby --help, syllaby faceless --help, and so on.

Authentication

The CLI authenticates with the same Bearer API keys as the REST API. Create a key at ai.syllaby.io/settings/api-tokens — keys are shown once, so store them somewhere safe.

syllaby auth login                        # paste your key; saves a profile named after the environment
syllaby auth login --profile prod --set-default
syllaby auth status                       # verifies the resolved token against GET /me
syllaby auth logout --profile prod

Profiles live in ~/.config/syllaby/config.json, so you can keep several keys side by side and switch with --profile.

Token & base-URL resolution

Production keys are prefixed slb_live_ and automatically target https://api.syllaby.io/v2 — no base URL needed. Any other key requires an explicit base URL.

Global flags

These work on every command:

Quick start

One shot — topic in, rendered mp4 on disk:

syllaby faceless create --topic "5 facts about Roman aqueducts" \
  --type ai-visuals --render --yes --wait --download roman.mp4

Or the deliberate flow, with a credit check before rendering:

id=$(syllaby faceless create --topic "How espresso is made" --json | jq -r .data.id)
syllaby faceless estimate $id             # credit cost vs. your balance
syllaby faceless render $id --wait        # charges credits; polls until done
syllaby faceless download $id -o espresso.mp4

Command reference

Each command maps to a documented endpoint of the v2 API reference — the mapping is noted in every command's --help text.

Account & credits

syllaby me                                # account + plan + credit balance (GET /me)
syllaby credits costs                     # credit cost per feature
syllaby credits history --page 2          # spending ledger
syllaby account topup                     # show the auto top-up preference
syllaby account topup set --enabled true --type extra-credits --plan-id 123

Faceless videos

syllaby faceless create --topic "..."     # draft; add --render --wait --download for one-shot
syllaby faceless get 123 --wait           # fetch; --wait polls the render status
syllaby faceless scripts 123 --topic "..." --duration 60   # 30|60|180|300|600|900
syllaby faceless estimate 123             # render cost vs. balance
syllaby faceless render 123 --yes --wait  # --yes skips the credit confirmation prompt
syllaby faceless retry 123 --wait         # re-run a failed render (charges credits again)
syllaby faceless export 123 --captions --wait
syllaby faceless download 123 -o out.mp4
syllaby faceless options                  # voices, genres, engines (--json for the full tree)

Text-to-video clips

syllaby ttv models
syllaby ttv estimate --model veo-3-fast --duration 8 --resolution 1080p
syllaby ttv create --model veo-3-fast --prompt "A phone rotating on marble" \
  --wait --download clip.mp4
syllaby ttv get 42 --wait

Storyboards (text-to-scene)

id=$(syllaby storyboard create --title "Deep sea" --json | jq -r .data.id)
syllaby storyboard prompt $id --prompt "Bioluminescent creatures" --engine-id 12 --duration 30
syllaby storyboard get $id --wait-ready
syllaby storyboard scenes $id
syllaby storyboard scene-update ...       --help for per-scene edits
syllaby storyboard clips $id              # generate scene clips
syllaby storyboard estimate $id
syllaby storyboard render $id --wait --download storyboard.mp4

Launch clips

syllaby launchclip estimate               # flat credit cost
syllaby launchclip create --product-name "Acme" --domain acme.io \
  --idea "AI meeting notes for sales teams" --output launch.mp4
syllaby launchclip show 7 --wait

Ideas, voices, characters, presets

syllaby ideas discover --keyword "cold plunge" --network youtube
syllaby ideas list --keyword "cold plunge" --network youtube --sort -volume

syllaby voices list
syllaby voices slots

syllaby characters list
syllaby characters genres
syllaby characters create --image ./ref.png --name Aria
syllaby characters preview 1 --genre-id 3
syllaby characters train 1 --preview-id 501 --name Aria --age 25-34 --gender female
syllaby characters get 1

syllaby presets list
syllaby presets create --name "Dental shorts" --voice-id 12 --orientation portrait
syllaby presets update 1 --orientation landscape  # only passed flags change
syllaby presets delete 1

Raw API escape hatch

Anything the curated commands don't cover is reachable with syllaby api — it sends an authenticated request to any v2 endpoint and prints the raw envelope:

syllaby api GET /faceless/123
syllaby api GET /credits/history --query page=2
syllaby api POST /faceless --data '{"topic":"..."}'   # --data @file.json or - for stdin

Waiting & downloads

Rendering is asynchronous. Commands that accept --wait poll the API every 10 seconds (backing off to 20 seconds after 2 minutes) with a 15-minute timeout — a timeout exits with code 5. --download <file> (or --output on launch clips) implies waiting and writes the finished mp4 to disk.

Data goes to stdout, progress and spinners to stderr — both human and --json output are safe to pipe.

Scripting with --json

--json on any command prints the unmodified API envelope, which makes the CLI composable with jq and CI pipelines:

balance=$(syllaby me --json | jq .data.credits)
id=$(syllaby faceless create --topic "..." --json | jq -r .data.id)

For unattended use, set SYLLABY_API_KEY in the environment and pass --yes to commands that would otherwise prompt for credit confirmation.

Exit codes

Rate limits & retries

The CLI is subject to the API's standard limit of 30 requests per minute per token. On 429 responses it automatically retries GET requests (honoring Retry-After, at most twice). Mutating calls are never auto-retried, because renders charge credits.

Credits

Generative commands charge the same credits as their underlying endpoints — the CLI adds no fees and no free tier. Check prices with syllaby credits costs, estimate a specific job with the estimate subcommands, and audit spend with syllaby credits history (API-originated spend is tagged in the ledger). Commands that charge ask for confirmation unless you pass --yes. Like the API, the CLI requires an active paid subscription — trials are not eligible.

See also

• Interactive API reference — every endpoint the CLI wraps
• @syllaby-ai/cli on npm
• llms.txt — machine-readable docs index