vidgate

CLI-first gateway for AI video generation providers built with NestJS.

vidgate gives you one interface to submit, poll, and download video generations across multiple providers:

• Google Veo 3.1
• OpenAI Sora 2
• Kling v2.6
• MiniMax Hailuo 2.3
• Runway API

It can run as a CLI by default, and can also expose a small REST API when VIDGATE_MODE=serve.

Features

• Unified CLI for video generation across providers
• Interactive credential setup with vidgate auth add
• Job persistence in SQLite
• Provider auto-selection by strategy: cheapest, fastest, quality
• Cost estimation across configured providers
• Optional REST mode for programmatic access
• Credentials loaded from OS keychain when available, with file fallback

Requirements

• Node.js 18+
• npm or pnpm
• Python 3.x — required by node-gyp to compile native addons (better-sqlite3, keytar) during npm install
• C++ build tools:
  • Windows: Visual Studio Build Tools with the "Desktop development with C++" workload (or run npm install --global windows-build-tools)
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux: build-essential (sudo apt install build-essential)
• Provider credentials for at least one supported service

Install

npm install -g vidgate

Development setup

Clone the repo and install dependencies:

npm install
npm run build

Run locally in CLI mode:

npm run start:cli -- generate --prompt "A cinematic drone shot of rice fields"

Or link for local development:

npm link
vidgate providers

Quick Start

1. Install dependencies and build the project.
2. Add credentials for a provider.
3. Generate a video.

Example:

vidgate auth add runway
vidgate generate --provider runway --prompt "A cinematic product shot of a watch"

CLI Commands

Generate a video

vidgate generate --prompt "A cat walking on the moon"

Common options:

vidgate generate \
  --provider runway \
  --prompt "A cinematic product shot of a watch" \
  --duration 5 \
  --aspect-ratio 16:9 \
  --no-audio \
  --output ./output

You can also explicitly enable or disable audio per request:

vidgate generate --prompt "A concert crowd at sunset" --audio true
vidgate generate --prompt "A silent cinematic landscape" --no-audio

Image-to-video:

vidgate generate \
  --provider runway \
  --prompt "The camera slowly pushes in" \
  --image "https://example.com/input.jpg"

Skip auto-download and only print the result URL:

vidgate generate --provider sora --prompt "A fox in a snowy forest" --no-download

Manage credentials

vidgate auth add
vidgate auth add veo
vidgate auth list
vidgate auth test runway
vidgate auth remove minimax

List providers

vidgate providers

List jobs

vidgate jobs
vidgate jobs --limit 50

Check a job

vidgate status <job-id>

Estimate cost

vidgate estimate --duration 5 --aspect-ratio 16:9

Supported Providers

| Provider | Inputs | Max duration | Audio | Auth | |---|---|---:|---|---| | Veo | text, image | 8s | native audio | VEO_API_KEY or Google OAuth/Vertex flow | | Sora | text | 12s | no | OPENAI_API_KEY | | Kling | text, image | 10s | yes in pro mode | KLING_ACCESS_KEY + KLING_SECRET_KEY | | MiniMax | text, image | 6s | no | MINIMAX_API_KEY | | Runway | text, image | 10s | no | RUNWAYML_API_SECRET |

Notes:

• Provider-specific validation still applies.
• Some providers only support specific durations or input types.
• Cost estimates are approximate and depend on provider pricing assumptions in code.

Credentials

Use the interactive setup:

vidgate auth add

Credentials are resolved in this order:

1. Shell environment variables
2. OS keychain via keytar
3. File fallback at ~/.vidgate/credentials.json

At startup, vidgate preloads known credentials into process.env before NestJS bootstraps.

Environment Variables

See .env.example.

Common variables:

VIDGATE_MODE=cli
PORT=8420

VEO_API_KEY=
OPENAI_API_KEY=
KLING_ACCESS_KEY=
KLING_SECRET_KEY=
MINIMAX_API_KEY=
RUNWAYML_API_SECRET=
RUNWAYML_MODEL=gen4.5

VIDGATE_DB_PATH=
VIDGATE_CONFIG_PATH=

Config File

Runtime config is loaded from:

• VIDGATE_CONFIG_PATH, or
• ~/.vidgate/config.toml

If no config file exists, built-in defaults are used.

The repository also contains config/default.toml as a sample template for expected structure.

Example:

[general]
default_provider = ""
default_strategy = "cheapest"
output_dir = "~/vidgate-output"
auto_download = true

[generation]
default_duration_secs = 5
default_aspect_ratio = "16:9"
default_with_audio = true

[providers.veo]
model = "veo-3.1-lite-generate-preview"
project_id = ""
region = "us-central1"

[providers.kling]
model = "kling-v2-6"
mode = "std"

[providers.sora]
model = "sora-2"

[providers.minimax]
model = "MiniMax-Hailuo-2.3"

[providers.runway]
model = "gen4.5"

[polling]
interval_ms = 5000
max_wait_ms = 600000

[budget]
max_usd_per_job = 0

The generation section lets you define default parameters for every vidgate generate run. CLI flags still override config values.

For example, to default all generations to 10 seconds without audio:

[generation]
default_duration_secs = 10
default_aspect_ratio = "16:9"
default_with_audio = false

REST Mode

Start the REST API:

VIDGATE_MODE=serve npm run start

Default port:

8420

Endpoints:

• POST /api/v1/generate
• GET /api/v1/jobs/:id
• GET /api/v1/jobs
• GET /api/v1/providers
• POST /api/v1/estimate

Example request:

curl -X POST http://localhost:8420/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic product shot of a watch",
    "provider": "runway",
    "durationSecs": 5,
    "aspectRatio": "16:9",
    "withAudio": false,
    "negativePrompt": "blurry, low quality"
  }'

Project Structure

src/
  application/
    cli/
    rest/
  core/
    error/
    model/
    port/
  gateway/
  infrastructure/
    auth/
    config/
    storage/
  providers/
    veo/
    sora/
    kling/
    minimax/
    runway/

Architecture Overview

• application/cli: command-line UX built with nest-commander
• application/rest: HTTP controller layer for REST mode
• gateway: orchestration, routing, polling, job lifecycle
• providers: adapters for each video provider API
• infrastructure: SQLite storage, config loading, HTTP client, credential stores
• core: shared models, ports, and domain errors

Flow:

1. Build VideoGenerationParams from CLI or REST input
2. Select provider explicitly or via routing strategy
3. Validate params against provider capability
4. Submit provider task
5. Persist job in SQLite
6. Poll provider until completion or failure
7. Download result or return output URL

Persistence

Jobs are stored in SQLite at:

• VIDGATE_DB_PATH, or
• ~/.vidgate/jobs.db

The database is created automatically on startup.

Video metadata

After each successful generation, vidgate saves a JSON metadata file alongside the video in the output directory:

~/vidgate-output/
  runway-a1b2c3d4.mp4        ← downloaded video
  runway-a1b2c3d4.json       ← metadata

The metadata file contains the full job details: provider, generation params, result URL, duration, resolution, audio flag, cost, and timestamps. This works even with --no-download; only the .json is written in that case.

Development

Run in watch mode:

npm run start:dev

Run tests:

npm test

Lint:

npm run lint

Known Notes

• config/default.toml is a template, not the file automatically loaded at runtime.
• Provider pricing, durations, and capability metadata are coded locally and may need updates as upstream APIs change.
• Some provider result metadata is incomplete today, so returned duration/resolution can be approximate.

References

• Architecture spec: vidgate-architecture-nestjs.md
• Environment template: .env.example