Tools & SDKs

Command-line interface

vivideo generates AI videos from your terminal, shell scripts, CI, or as a subprocess an agent drives. It's a thin wrapper over the API with structured output and meaningful exit codes.

Install

terminal

npm install -g @vivideo/cli
vivideo --version

Authenticate

Provide your API key one of three ways (highest precedence first):

terminal

# 1. environment variable (best for CI / agents)
export VIVIDEO_API_KEY="vv_live_..."

# 2. stored securely in ~/.vivideo/config.json (0600, never printed)
vivideo configure                 # interactive
vivideo configure --api-key vv_live_... --verify   # non-interactive + validate

# 3. one-off flag (avoid in shared shells / history)
vivideo --api-key vv_live_... account

Create a key in the Vivideo app under Settings → More → API Keys (app.vivideo.ai/account/api-keys). The CLI never prints your key; vivideo config shows only where it's read from.

Make a video

terminal

# check your plan + credits
vivideo account

# auto-generate a full avatar video and wait for it
vivideo create auto --prompt "A 20-second product teaser" --wait

# or a specific model (manual mode)
vivideo create manual --model veo31_fast --prompt "waves at dusk" \
  --duration 4 --resolution 720p --wait

# → prints the video_url when completed

Commands

Command	What it does
`vivideo account`	Plan, premium status, credit balance.
`vivideo models [--mode]`	List models (and the auto pipeline).
`vivideo avatars / voices / brand-kits`	Discover media for auto mode.
`vivideo estimate ...`	Estimate credits before generating.
`vivideo create auto ...`	Auto-generate a video from a prompt.
`vivideo create manual ...`	Create with a specific model.
`vivideo status <id>`	A video’s current status/result.
`vivideo wait <id>`	Wait for a terminal state (bounded).
`vivideo videos [--status]`	List your videos.
`vivideo configure`	Store your key securely.

Every command accepts --json, --no-input, -y, --api-key, --base-url.

JSON & non-interactive (scripts, CI, agents)

--json prints structured JSON and implies non-interactive; a non-TTY (CI) is auto non-interactive. Errors print as { error: { code, kind, message, retryable, request_id, links } } — branch on those, never on text.

terminal

export VIVIDEO_API_KEY=vv_live_...
vivideo --json create manual --model veo31_fast --prompt "sunrise" \
  --duration 4 --resolution 720p --wait --timeout 300
echo "exit: $?"

Exit codes

Code	Meaning
0	success
2	usage error (bad flags)
3	auth / not configured
4	insufficient credits
5	rate limited
6	upgrade required (or free preview)
7	not found
8	network / timeout
9	invalid request
10	duplicate request

✓

Idempotent retries. Pass --idempotency-key <key> on create and reuse it when retrying — a retry never creates a second video or double-charges. Without one, the CLI generates a per-call key automatically.

← Previous

Errors & rate limits

MCP server

Machine-readable: interactive reference · openapi.yaml · llms-api.txt. Base URL https://api.vivideo.ai.