videodraft
The official VideoDraft CLI creates AI videos, images, audio and 3D assets from your terminal. Built for humans and coding agents: every command supports --json, exit codes are stable, async jobs are first-class.
npx videodraft login
npx videodraft generate image "a red fox in snow, cinematic" --download ./out/
npx videodraft create "30s launch video for our espresso machine" --ar 9:16
Background removal
videodraft remove-background image portrait.png --download cutout.png
videodraft remove-background video clip.mp4 --estimate
videodraft remove-background video clip.mp4 --subject person --download cutout.webm
videodraft remove-background video product.mp4 --subject object --no-refine-edges --no-wait
Image removal uses Pixelcut and returns transparent PNG. Video removal uses VEED Fast and returns transparent WebM, preserving source resolution and timing. Video sources must be uploaded MP4/MOV files, up to 100 MB, five minutes and 120 fps; local files upload automatically. Use --max-credits to cap spending, --session to group results, and --idempotency-key <uuid> to safely retry the same request. VideoDraft credits and Fal BYOK are supported.
Install
npm install -g videodraft # global: adds the `videodraft` command to your PATH
videodraft --version # → confirms it's installed
# …or run without installing — npx fetches and runs the latest each time:
npx videodraft <command>
Requires Node ≥ 20.18.1. (Publishing to npm doesn't put videodraft on your PATH — npm i -g or npx does. A Homebrew tap and a curl | sh installer are on the way.)
Authenticate
videodraft login # opens your browser (OAuth)
videodraft login --token vd_mcp_… # personal access token from https://app.videodraft.ai/mcp-keys
export VIDEODRAFT_API_KEY=vd_mcp_… # headless / CI — no login command needed
Credentials are stored in ~/.config/videodraft/config.json (0600). videodraft logout revokes and clears them.
Asset generation first
Standalone images, clips, audio and 3D models are complete deliverables. They do not need a VideoDraft project unless you want to attach them to an existing project or turn them into a multi-scene production.
videodraft generate image "isometric workspace, warm light" --num 4 --download "./out/{job_id}_{index}.{ext}"
videodraft generate video "slow dolly over a misty lake" --model google-veo3.1 --duration 6 --estimate
videodraft generate video "A cyclist races through rain at night" --model minimax-h3-max --duration 8 --resolution 768p --prompt-expansion-mode balanced
videodraft generate video "Image 1 is the rider. Video 1 sets the camera move." --model minimax-h3-max --duration 8 --ar adaptive --ref rider.png --ref-video camera.mp4
videodraft generate video "Keep the product and match these camera moves" --model gemini-omni-1.1-flash --duration 8 --resolution 1080p --video-task generate --ref ./product.png --ref-video ./move-1.mp4 --ref-video ./move-2.mp4
videodraft generate video "Keep the subject and use this camera language" --model gemini-omni-1.1-flash --source-video ./source.mp4 --ref-video ./camera-ref.mp4 --ref-video-duration 2.5 --video-task edit --resolution 1080p
videodraft generate video "The scene continues as the camera follows her outside" --model gemini-omni-1.1-flash --source-video ./source.mp4 --extend --duration 8 --resolution 720p --download ./extended.mp4
videodraft generate video --model gemini-omni-1.1-flash --previous-interaction-id INTERACTION_ID --ref-video ./new-motion-ref.mp4 --ref-video-duration 3 --resolution 4K --download ./edited-turn.mp4 # conversational edit; add --extend to lengthen
videodraft generate audio "Read this in a calm documentary voice" --voice vivi_mixed_en_zh_ja_es_id --download narration.mp3
videodraft generate audio "Extend @Audio1 with soft rain" --ref-audio ./opening.wav --download extended.wav --format wav
videodraft generate voiceover "Welcome to VideoDraft" --download welcome.mp3
videodraft generate voiceover "Welcome to VideoDraft" --mode turbo --download welcome.mp3 # Eleven v4 Turbo: faster and cheaper
videodraft generate music "minimal ambient, 60 BPM" --download bgm.mp3
videodraft generate sound-effect "cinematic whoosh, sub hit" --duration 3 --download sfx.mp3
videodraft generate dialogue --line "elevenlabs-kPzsL2i3teMYv0FxEYQ6:Ready?" --line "elevenlabs-s3TPKV1kjDlVtZbl4Ksh:Let's go." --download dialogue.mp3
videodraft generate voice-changer ./speech.wav --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --duration 12 --download changed.mp3
videodraft generate dub ./clip.mp4 --to es --duration 30 --download dubbed.mp4
videodraft upscale image ./photo.png --scale 4x --download ./photo-4x.png
videodraft upscale video ./clip.mp4 --resolution 1080p --mode generative --download ./clip-1080p.mp4
videodraft interpolate ./clip.mp4 --fps 60 --download ./clip-60fps.mp4
videodraft avatar create ./founder.jpg --script "$(videodraft avatar script 'our launch' --json | jq -r .script)"
videodraft edit video ./clip.mp4 "Add falling snow" --model grok-imagine-video-edit --download ./clip-snow.mp4
videodraft edit motion ./character.png "Apply the reference dance" --motion-video ./dance.mp4 --download ./character-dance.mp4
videodraft generate video "Match this performance" --model kling-o3-video-ref-edit --ref-video ./performance.mp4 --ref ./wardrobe.png --download ./guided.mp4
videodraft kling-voices create ./speaker.wav --name "Narrator" --confirm-consent
videodraft kling-voices create ./speaker.wav --name "Narrator" --estimate
videodraft generate video "@Element1 says welcome" --model kling-3.0 --start-image ./scene.png --audio --element '{"video_url":"./speaker.mp4","voice_id":"VOICE_ID"}'
videodraft generate video "<<<voice_1>>> Welcome" --model kling-2.6-pro --start-image ./host.png --audio --voice-id VOICE_ID
generate audio automatically retries transient and lost responses with one
stable operation key. To recover after stopping or losing the CLI process, set
your own UUID up front and reuse it if needed:
videodraft generate audio "..." --idempotency-key "$(uuidgen)"
The server then returns the existing result or in-progress operation without generating or charging twice.
Discover the full asset lane:
videodraft tools list
videodraft tools list --lane assets
videodraft tools list --lane asset_io
videodraft models image
videodraft models video
videodraft models video --category video_edit
videodraft models audio
Asset I/O is part of the asset workflow: videodraft upload, videodraft download, generation --download, and local refs like --ref ./image.png make files usable by agents and visible in local workspaces.
3D model generation and rigging
Meshy 7.1 (--model meshy-7, or meshy-7.1) and Tripo H3.1 support text, image, and multi-image inputs through Fal. Meshy's geometry_resolution option sets the geometry detail: text and image take standard, 2k (the default) or 4k, and multi-image takes standard (the default) or 2k. 2k and 4k cost more. Saved 3D assets are independent of AI Studio sessions. Inspect the live catalog for each endpoint's exact options, view order, limits, default settings, output formats, and pricing:
videodraft models 3d --json
videodraft generate 3d "a weathered brass telescope" --model meshy-7 --estimate
videodraft generate 3d "a weathered brass telescope" --model meshy-7 --option geometry_resolution=4k --estimate
videodraft generate 3d --model meshy-7 --ref ./character.png --download
videodraft generate 3d --model tripo-h3.1 --input-mode multi_image --ref ./front.png --ref ./left.png --ref ./back.png --ref ./right.png --options @model-options.json --no-wait --json
videodraft wait JOB_ID --download ./media/3d --json
videodraft assets 3d list --status completed --json
videodraft assets 3d get ASSET_ID --download
videodraft rig 3d --asset ASSET_ID --estimate
videodraft rig 3d ./character.glb --download
The positional prompt is for text mode. Image modes do not accept a geometry prompt; Meshy has a separate texture_prompt option for texture guidance. --input-mode defaults to text without references, image with one reference, and multi-image with two or more. Meshy multi-image accepts 1-4 views; use explicit --input-mode multi_image for a single view. Tripo accepts 2-4 views in front, left, back, right order. Rigging accepts a compatible textured humanoid GLB as a saved asset, public URL, or local file. It does not promise a facial/dialogue rig. Local GLBs use the separate 3D upload lane.
--options '{...}' or --options @file.json passes exact provider fields. Repeat --option key=value to override individual fields; values preserve JSON objects, arrays, numbers, and booleans. Read the live schemas instead of assuming both models share option names. --estimate uses the same server pricing calculation as submission and does not upload local inputs. Charges are whole VideoDraft credits at 100 credits per dollar. Fal BYOK uses your connected Fal account and zero VideoDraft credits.
3D --download saves all returned model files, textures, materials, animations, and previews, plus manifest.json, under media/3d/<asset_id>/. A custom directory receives a per-asset subdirectory; {job_id} or {asset_id} can specify the directory layout. A single .glb filename or image/video {index}.{ext} template is rejected because it would discard the rest of the package. Existing downloads are preserved by adding a directory suffix. GLB/FBX/ZIP bytes are retained; glTF/OBJ/MTL dependency links are adjusted to their downloaded filenames. Provider-supplied dependency aliases restore texture paths required by original FBX files. Inspect package_warnings and the manifest's complete field before treating packages as self-contained. A failed download leaves no completed manifest.
Each submission includes a UUID request_id. Retry interrupted submissions with the same arguments and --request-id UUID. A local request journal in the CLI config directory reuses the originally uploaded references. Reusing a UUID with changed inputs fails. The journal contains the submitted prompt/options and public asset URLs and is stored with owner-only permissions. If a wait times out, use status or wait with the existing job ID; do not submit a new request.
Machine output preserves artifacts and adds output_files, downloaded_files, manifest_path, and package_warnings. Only rendered previews appear in output_media; meshes and texture maps never masquerade as playable images or videos. Use external 3D software to view/edit the meshes. This release does not add an AI Studio 3D viewer.
The project pipeline
Use projects when the user asks for a story, storyboard, editable web project, timeline, production flow, or exported MP4.
videodraft credits # know your budget
videodraft create "<idea>" --ar 9:16 # idea → script → visual assets → storyboard
videodraft shots <project> --grid --estimate # preview the cost…
videodraft shots <project> --grid # …then batch-generate every shot image
videodraft produce <project> # voiceovers + captions + production timeline
videodraft produce <project> --voice-mode turbo # ElevenLabs narration on Eleven v4 Turbo (faster, cheaper)
videodraft produce <project> --mode full_video # one Seedance video per scene
videodraft export <project> --download final.mp4
Seedance 2.x has no real-people option. A video that can't be made at the listed rate, usually one showing a real person, costs a higher rate, and the difference is charged before it starts.
Commands
call reaches every VideoDraft API tool (the full MCP catalog), including ones without a curated command — new platform features work in the CLI the day they ship.
Kling voice creation has a small charge on the platform Fal account and is free
with Fal BYOK. --estimate checks the active account without creating
a voice. Samples must be MP3, WAV, MP4, or MOV, 5-30 seconds, and no larger
than 50 MB. Voice IDs are opaque strings scoped to the Fal account that created
them; keep a voice_id inside its image-backed or video-backed element so the binding is preserved.
For agents and scripts
--jsonon any command prints a single JSON document on stdout.- Exit codes:
0ok ·1error ·2usage ·3auth required ·4insufficient credits. - Async generations wait by default;
--no-waitreturns{job_id}immediately,videodraft wait <job...>resumes,--wait-timeout 30m --wait-interval 5stune polling. - Many jobs at once? Submit them all with
--no-wait, thenvideodraft wait <id1> <id2> ...— one process polls every job with ONE batched request per tick (don't spawn N parallelwaitprocesses). Polling backs off adaptively (3s → 15s with jitter) on long jobs unless you pin--wait-interval. --downloadtemplates:{job_id},{index},{ext},{name}. Downloads are echoed asdownloaded_files[]in--jsonoutput.- Local file → public URL anywhere a URL is expected (
--ref photo.jpg), or explicitly viavideodraft upload. NO_COLORand--no-colorare respected; output is uncolored when piped.
Install the VideoDraft skill so your agent knows the workflow:
npx videodraft skills install # zero-install: npx fetches the CLI and installs the skill
videodraft skills install # if the CLI is on PATH — auto-detects your installed agents
videodraft skills install --agent claude,codex # target specific agents (repeatable/comma; --all for every agent)
videodraft skills install --project # into ./.claude/skills for just this repo (else global)
videodraft skills show # print the skill (also: skills show editor|models|3d|examples|pipeline|--all)
# Or install straight from the repo — no CLI on PATH needed first:
npx -y skills add videodraft-ai/cli -g # vercel-labs skills tool; npx -y skips npx's install prompt; -g = user scope
gh skill install videodraft-ai/cli videodraft --scope user # GitHub CLI; name the skill + user scope (else it lists / installs project-scoped)
# Claude Code: /plugin marketplace add videodraft-ai/cli then /plugin install videodraft@videodraft
# Codex: codex plugin marketplace add videodraft-ai/cli then codex plugin add videodraft@videodraft
Environment variables
Telemetry
The CLI sends anonymous usage events (command name, CLI version, OS, duration, success/error class — never prompts, file contents, or arguments) to help us improve it. Opt out any time:
videodraft config set telemetry false # or VIDEODRAFT_TELEMETRY=0 / DO_NOT_TRACK=1
Embedding (videodraft/client)
The CLI's core is exported for programmatic use (Node ≥ 20 and Bun):
import { VideoDraftClient, resolveAuth } from "videodraft/client";
const { tokenProvider, baseUrl } = resolveAuth({}); // flag/env/config-store resolution
const client = new VideoDraftClient({ tokenProvider, baseUrl });
const me = await client.callTool("whoami");
License
MIT © VideoDraft
Ideogram 4.5 (ideogram-v4.5) replaces the visible Ideogram 4.0 entry and stays Tier 2. Quality: low, medium (default) or high, priced per image; very_low for regular edits. Supports 1-8 outputs, 1K/2K, seed, a source plus four additional references (three with a mask), regular/high edit precision, and text-to-image prompt expansion. MCP uses source_image, reference_images, mask_url, edit_precision, enable_prompt_expansion, image_width, and image_height. CLI equivalents are --source-image, repeatable --ref, --mask, --edit-precision, --prompt-expansion, --image-width, and --image-height. Precise/masked edits require Auto size with no resolution or custom dimensions. Masks match source dimensions and contain both black edit regions and white preserved regions. Quotes for very_low require the source/reference count (reference_image_count or --ref-images). Legacy 4.0 jobs retain their original backend support.
FLUX 3 image (flux-3-image, separate from flux-3-max video) is Tier 2. It generates and edits with up to 10 references, 1-4 outputs, 1K/2K/4K (default 1K), prompt expansion (default on) and 14 aspect ratios plus auto. Each image is priced by output size (resolution and ratio); auto is quoted at the tier's highest price. Without an aspect ratio, a new image is 16:9 and an edit follows its first reference. No seed. MCP uses reference_images, num_images, resolution, aspect_ratio and enable_prompt_expansion; the CLI uses --ref, --num, --resolution, --ar and --prompt-expansion.
Kling 4.0 video
kling-4.0 is Kling's newest model. It runs on Atlas Cloud first, with Fal, Higgsfield and Pika as backups. It is Tier 1, the preferred Kling after Gemini Omni and Seedance (Kling 3.0 and O3 keep 4K). Three modes, like Kling O3: text to video; image to video from a start image (start_image_url) with an optional end image (end_image_url), where framing follows the image; and reference to video, chosen when references are given, with an optional start image, up to 10 images including it (reference_images, cited as @Image1), up to 5 reference videos (reference_videos, cited as @Video1, 3-30s each) and up to 7 elements (cited as @Element1; up to 3 with voice_id, up to 3 video-backed). Reference and element videos share 5 clips and 30 seconds, and 15 inputs is the total. Duration is 3-30 whole seconds (default 5), or 1-6 multi_prompt shots of 1-30s each and 3-30s in total. 720p/1080p, audio always on, aspect ratio 16:9/9:16/1:1/21:9 plus auto with references (none in image to video). Reference mode has no end frame. No seed, negative prompt or quality tier. Reference and element videos are billed by length plus the output, at least twice the output; quote with videodraft costs kling-4.0 --type video --duration 10 --ref-video-seconds 6 or --estimate. CLI: --model kling-4.0 with --start-image, --end-image, --ref, --ref-video, --element, --segment, --resolution. kling-4.0-video-edit edits a whole 3-30s source with videodraft edit video <source> "<prompt citing @Video1>" --model kling-4.0-video-edit, up to 10 --ref images and 7 image-only --element entries, and an optional output --duration (3-30; default the source length). It bills the source plus the output, at least twice the output; quote with videodraft costs kling-4.0-video-edit --type video --ref-video-seconds <source seconds>. See the model guide.
FLUX 3 Max video
flux-3-max replaces FLUX 3 in discovery. It is Tier 1 immediately before MiniMax H3 Max; Gemini Omni remains the default. It accepts a prompt, first/last frames, or up to 10 timed keyframes, at 720p/1080p for 5-20 whole seconds (default 5). Audio is optional. MCP uses reasoning_level: "low" | "high" (high default) and seed; CLI uses --reasoning-level, --seed, --duration, --start-image, --end-image, and repeatable --keyframe [email protected]. No Draft/quality option or auto duration. Get current pricing with videodraft costs flux-3-max --type video --duration 5 --resolution 720p or --estimate. See the model guide.
