Vincent

Make video in your terminal — by talking to an AI agent.

Vincent is a conversational AI agent that turns a product photo into a marketing video, or a plain-language idea into a narrated, multi-scene story video. It drafts a storyboard for your review, renders when you approve, and keeps editing by conversation. No video editing skills required.

Gemini + Veo are the zero-config default — one GEMINI_API_KEY gets image, video, and voice. Advanced users can opt into Replicate (Flux, Flux Kontext), fal, ElevenLabs, or OpenAI per operation; Vincent never prints your keys.

Requirements

Node.js ≥ 22 (LTS), Node 24 recommended. Install via nvm: nvm install 24 && nvm use 24.

Install

npm install -g @magyk/vincent
vincent --version

Get a Gemini API key

Google AI Studio is the fastest way to get a key — one key covers the LLM, image generation, and Veo video generation.

1. Go to aistudio.google.com and sign in with your Google Account.
2. Click Get API key (or API keys) in the sidebar.
3. Click Create API key. You can create it in a new or existing Google Cloud project.
4. Copy the key and keep it somewhere safe — you'll paste it into Vincent on first run.

Billing note: AI Studio uses a tiered billing system. New accounts start on a free tier with generous rate limits. For high-volume or production use you'll need to link a billing account.

Usage

Run vincent to start a conversation. It works in two modes — Product (turn a product photo into a marketing video) and Story (turn an idea into a narrated, multi-scene video). In Story mode Vincent proposes a storyboard for your review before it renders; switch modes anytime with /mode.

vincent                          # start a new session (chat — pick Product or Story)
vincent product.jpg              # start with a product image already loaded
vincent --image product.jpg      # same, explicit flag (useful in scripts)

First run: Vincent will prompt you to paste your Gemini API key — it's saved automatically and you won't be asked again. The TUI shows you how to provide an image, describe a story, and what commands are available.

Consistency: upload a reference image and ask Vincent to use it — it anchors every scene to that image so a character or setting stays consistent across the whole story.

API keys are stored in ~/.local/share/magyk/settings.json (Linux) or ~/Library/Application Support/magyk/settings.json (macOS). You can also use /settings inside the TUI to manage them, or set GEMINI_API_KEY in your environment (takes priority over the saved key).

Non-interactive — vincent make

Render a story video from the command line (no TUI). It saves a normal session, so you can open it later in the interactive app via /resume and keep editing.

# From a prose idea (one-shot — generates a storyboard, then renders):
vincent make story "A 30-second story about a lighthouse keeper who finds a message in a bottle" --length 4

# From a storyboard JSON you control (deterministic):
vincent make storyboard ./storyboard.json --json --out ./out.mp4

# From a product image + a brief (one hero shot → video):
vincent make product ./product.jpg "on a model in a sunlit loft" --out ./out.mp4

Flags: --json (one JSON result on stdout; progress on stderr — scriptable), --out <path|dir> (copy the mp4 out; --force to overwrite), --no-session (render only), --session-id/--session-name. make product also takes --video-model veo3|veo3-lite and --ar 16:9|9:16. A storyboard JSON example: docs/examples/storyboard.json.

vincent make story/make product use a one-shot director, not the interactive agent. For iterative, conversational authoring (and multi-scene product videos), run vincent and use Story or Product mode.

Options

vincent [image] [options]

  --image <url|path>     Product image URL or local path (equivalent to positional arg)
  --video-model <id>     veo3 or veo3-lite (default: veo3-lite)
  --storage <path>       Override artifact output directory
  --self-test            Run built-in diagnostics and exit
  --version, -v          Print version and exit
  -h, --help             Show help

vincent make story "<prose>" [pipeline flags] [--json] [--out <path>] [--no-session]
vincent make storyboard <path.json>           [--json] [--out <path>] [--no-session]

vincent models list [--slot llm|imageGenerate|imageEdit|video|tts] [--provider <id>] [--json]
vincent models current [--json]               # the resolved model per slot
vincent models doctor [--json]                # configured providers + per-slot readiness
vincent models capabilities <id> | --slot <slot> [--json]
vincent models set <slot> <model-id>          # persist a model choice (llm|imageGenerate|imageEdit|video|tts)
vincent models preset [<name>]                # apply starter-google|google-pro|open-providers

vincent diagnostics [<id>] [--latest] [--out <dir>]   # zip a session + environment report for a bug report

Hit a bug? Run /diagnostics inside the TUI (or vincent diagnostics --latest after quitting) to package the current session — its transcript, logs, and an environment report — into a single .zip in the current directory. It contains no API keys (those live outside the session folder) and rewrites your home path to <HOME>. Attach it to your report at https://github.com/magyk-ai/vincent/issues.

Gemini + Veo are the default ("starter") models — one GEMINI_API_KEY gets you everything. vincent models (never prints keys) lets you inspect the curated registry and persist choices. The llm slot is the planner/pipeline model used by make — not the interactive Vincent agent.

Local / self-hosted inference (advanced)

Prefer not to use the cloud? Vincent can run the generative models on your own hardware (an Apple-Silicon Mac is the reference setup) for privacy and no per-use cost — at the cost of slower renders. Local providers are configured by endpoint URL rather than an API key:

vincent local connect <host>     # point ComfyUI / local-LLM / Kokoro / Whisper at one box
vincent models set imageGenerate local-flux-schnell   # then pick local models per slot

See the Local / self-hosted inference section of the user guide for the full setup (the local model line-up, the optional whisper subtitle server, and performance tuning).

License

See LICENSE for terms. © 2026 Magyk Inc.