Revid CLI

Create videos from the command line using the Revid public API.

The CLI is optimized for AI agents and automation:

• Stable JSON output with --json
• Exact API payload mode with --payload
• Fast one-line creation with --prompt, --text, or --url
• Guided JSON planning with revid guided --json so agents pick the right workflow and models before rendering
• Planning mode with revid plan for the same machine-readable planning contract
• Interactive guided creation with revid guided
• Async render handling through create, status, wait, and export
• Offline context for agents through revid guide --json
• Live helper commands for voices and visual presets
• Structured missing-field errors that tell agents exactly which helper command to run

Requires Node.js 18 or newer.

Install

npm install -g revid-cli

During local development from this folder:

npm link
revid --help

Authentication

For AI agents, CI, and production automation, use an environment variable:

export REVID_API_KEY="your_revid_api_key"

For local human use:

revid auth login
revid auth status

Auth precedence:

1. --api-key
2. REVID_API_KEY
3. Local config from revid auth login

Use --base-url or REVID_BASE_URL for staging or local API targets. The default production API is https://www.revid.ai.

Quick Start

If an agent has no Revid context, start with:

revid guide --json
revid guided --json --goal "Create a satirical Pixar-style roast video from this X profile picture" --reference-image-url "https://example.com/profile.jpg" --media-preset PIXAR
revid plan --goal "Create a satirical Pixar-style roast video from this X profile picture" --reference-image-url "https://example.com/profile.jpg" --media-preset PIXAR --json
revid workflows --json
revid presets --json
revid voices --json
revid examples prompt-to-video --json

Prompt to video:

revid create --prompt "A cinematic 30 second product launch video" --wait --json

For AI agents, the recommended way to start is the guided JSON flow:

revid guided --json \
  --goal "Create a satirical Pixar-style roast video from this X profile picture" \
  --reference-image-url "https://example.com/profile.jpg" \
  --media-preset PIXAR

This is recommended for agents because it returns stable JSON: workflow choice, expected output, model questions, common wrong choices, and a starter payload. Plain revid guided remains the interactive human wizard.

You can also call the planning command directly:

revid plan \
  --goal "Create a satirical Pixar-style roast video from this X profile picture" \
  --reference-image-url "https://example.com/profile.jpg" \
  --media-preset PIXAR \
  --json

revid plan returns the recommended workflow, expected output, model-selection questions, warnings for common wrong workflow choices, and a starter payload. For example, a profile picture used as inspiration should become prompt-to-video with media.provided[]; it should not become avatar-to-video unless the user explicitly wants a talking head.

Script to video:

revid create --text "Paste the narration script here." --aspect-ratio portrait --wait

Article to video:

revid create --workflow article-to-video --url "https://example.com/post" --wait --json

Guided mode:

revid guided

Agent Payload Mode

Send an exact Revid v3 render payload:

revid create --payload payload.json --wait --json

Read from stdin:

cat payload.json | revid create --payload - --wait --json

Override payload fields without editing the JSON file:

revid create --payload payload.json --set render.resolution=1080p --set options.outputCount=2 --wait --json

Print the request payload without calling Revid:

revid create --prompt "A clean SaaS launch video" --dry-run --json

Agent Discovery Commands

Use these when the caller does not already know Revid's API concepts:

revid guide --json
revid workflows --json
revid examples --json
revid examples prompt-to-video --json
revid template script-to-video
revid docs --json
revid docs --local --json
revid guided --json --goal "Create a product launch video"
revid plan --goal "Create a product launch video" --json
revid presets --json
revid presets --search cinematic --json
revid voices --json
revid voices labels --json
revid voices --gender female --language en --json

Core mental model:

• create starts an asynchronous Revid project and returns a pid.
• wait polls that pid until videoUrl is available or the job fails.
• webhookUrl is preferred for production callbacks.
• --payload sends exact Revid v3 JSON.
• --reference-image-url puts an image in media.provided[] as a visual/person/style reference for generated scenes.
• --avatar-url is only for talking-avatar videos where the provided image/video should become the on-screen speaker.
• Missing model choices return code: "MISSING_MODEL_SELECTION" with data.modelSelection.questions[].
• media.imageModel is requested only when image generation is relevant and media.type is not ai-video.
• media.videoModel is requested when generated video motion is relevant.
• Use --auto-models to accept the CLI's recommended defaults.
• --set path=value lets agents override a payload field without rewriting JSON.
• --dry-run --json prints the request payload before spending credits.
• Missing required fields return code: "MISSING_REQUIRED_FIELDS" with data.missingFields[], including the path, the flag to use, and a helper command.
• In an interactive terminal, missing required fields are prompted automatically. Use --no-prompt to force agent-style errors, or --ask-missing to prompt even with --json.

Voice and preset selection:

• Run revid voices --json to list voice IDs for voice.voiceId or --voice-id.
• Run revid voices labels --json to see filterable labels such as language, gender, accent, age, and use case.
• Run revid presets --json to list visual preset values for media.mediaPreset or --media-preset.
• Run revid presets --search <term> --json when the desired style is known loosely.

Workflow selection:

• Use prompt-to-video for a full generated video from a creative brief, including profile-picture roasts, stylized stories, satire, explainers, or creative videos with reference images.
• Use avatar-to-video only when the user wants the provided avatar/profile image to speak directly to camera as a talking avatar.
• Use script-to-video when the user provides the exact narration/script that should drive the video.
• Use caption-video when the user has an existing video and mainly wants subtitles/reframing.

Workflow requirements:

| Workflow | Required fields | | --- | --- | | script-to-video | source.text | | audio-to-video | source.url | | prompt-to-video | source.prompt | | music-to-video | source.url | | article-to-video | source.url | | avatar-to-video | source.text, avatar.url | | static-background-video | source.text or source.url | | motion-transfer | source.url, media.provided[] | | caption-video | source.url | | ad-generator | source.prompt or media.provided[] |

Async Render Flow

The recommended production flow is:

1. Start a render:

   revid create --payload payload.json --json

2. Store the returned pid.

3. Prefer --webhook-url for production systems.

4. For agents and local scripts, poll with:

   revid wait <pid> --json

5. Download the final video when needed:

   revid wait <pid> --output ./video.mp4 --json

--wait on create combines start and polling in one command. --output on create implies waiting.

Useful Commands

revid workflows --json
revid guided --json --goal "Satirical Pixar roast from a profile picture" --reference-image-url https://example.com/profile.jpg --media-preset PIXAR
revid plan --goal "Satirical Pixar roast from a profile picture" --reference-image-url https://example.com/profile.jpg --media-preset PIXAR --json
revid presets --json
revid voices --json
revid template prompt-to-video
revid docs --json
revid credits --payload payload.json --json
revid projects --limit 10 --json
revid status <pid> --json
revid export <pid> --json

Publishing

Before publishing:

npm test
npm run check
npm pack --dry-run

First manual publish:

npm login
npm publish --access public

Do not put Revid API keys in this package, test fixtures, docs, or npm metadata.