Providers & Routing

videoclaw speaks to four different AI-video engines through one CLI — and it never silently swaps one for another behind your back. You pick a route, it checks that route's keys and tools, and it tells you exactly what is ready before a single credit is spent.

What it does

• Gives you four production routes to generate video, each with its own strengths:
  • veo-useapi — Google Veo through the UseAPI aggregator (unlocks portrait image-to-video, Omni Flash video-to-video, and native voice narration). Its native local transport drives the vclaw-cli Bun/Flow workspace on your machine.
  • seedance-direct — ByteDance Seedance 2.0 via xskill.ai (artistic, stylized, product shots; up to 9 reference images).
  • runway-useapi — Runway through UseAPI (multi-shot, lip-sync, extend, edit; free "explore" mode for overnight drafts).
  • dreamina-useapi — Dreamina (CapCut/ByteDance Seed) Seedance 2.0 through useapi.net (keyframe image-to-video, 1080p on CA accounts).
• Knows each route's exact capabilities — which operations (text-to-video, image-to-video, frames-to-video, extend, edit, add-audio) work in landscape vs portrait, and how many reference images are allowed.
• Resolves the transport in a strict order with no silent fallback: a custom adapter binary you set, then a built-in command shim, then the native in-process transport — and if none is usable, it throws instead of guessing.
• Verifies your environment before you run: checks API keys, local tools (ffmpeg, bun, python3, …), your build freshness, and your Gemini key pool, then prints a machine-readable health report.
• Marks each route available, degraded, or unavailable so an operator (human or agent) can choose a route that will actually work.

How to use it

All commands below use the repo form node dist/cli/vclaw.js video .... If you installed videoclaw globally, you can type the shorter vclaw video ... instead.

node dist/cli/vclaw.js video providers

Prints the full provider status report as JSON: every route, its maturity, required env vars, runtime dependencies, and availability. This is your "what can I run right now?" command.

node dist/cli/vclaw.js video providers --workspace-root ./my-workspace

Same report, but checks .env / .env.local and tools relative to the given workspace folder.

node dist/cli/vclaw.js video verify-env

Runs a deeper pre-flight: API keys (and where each came from — process env, .env.local, or .env), local dependencies, build age, Gemini key-pool size, plus the provider report. Emits blockingIssues, warnings, and a top-level ok: true|false.

node dist/cli/vclaw.js video verify-env --root ./my-workspace

The pre-flight scoped to a specific workspace (the --workspace-root flag is also accepted).

How it flows

Diagram source (live Mermaid)

The transport resolution at execution time runs in this order, and stops at the first match:

1. Custom adapter — if VCLAW_<ROUTE>_ADAPTER is set, that command is the adapter (JSON in on stdin, JSON out on stdout).
2. Built-in command shim — the bundled dist/cli/provider-adapter.js invoked with --route <id>, driven by per-route ..._SUBMIT_CMD / ..._POLL_CMD / ..._CANCEL_CMD shims.
3. Native in-process transport — native-veo.ts, native-seedance.ts, native-runway.ts, or native-dreamina.ts (no subprocess hop).

If none is usable, execution throws — e.g. Live execution for <route> requires VCLAW_<ROUTE>_ADAPTER to point at an adapter command. There is no silent fallback to a different route.

Artifacts & outputs

providers and verify-env are read-only inspectors — they print JSON to stdout and do not write project artifacts. Downstream execution (the route you choose here) is what writes projects/<slug>/artifacts/execution-report.json and the generated clips. See execute for that stage.

Credentials per route

capability	veo-useapi	seedance-direct	runway-useapi	dreamina-useapi
text-to-video	✓	✓	✓	✓
image-to-video	✓	✓	✓	✓
video-to-video / edit	✓	–	✓	–
native voice narration	✓	–	–	–
portrait (9:16)	✓	✓	✓	✓
reference images	—	up to 9	—	—
free draft mode	–	–	✓	–
1080p	✓	✓	✓	CA accounts
credential	USEAPI_API_TOKEN	SUTUI_API_KEY	USEAPI_API_TOKEN	USEAPI_API_TOKEN

Per-route capability matrix. Veo adds Omni Flash video-to-video and native voice; Runway has the free explore draft mode; Dreamina 1080p is CA-region only.

Route	Required env vars	Native transport
veo-useapi	USEAPI_API_TOKEN, USEAPI_ACCOUNT_EMAIL	built-in adapter (native local transport: native-veo.ts drives the vclaw-cli Bun/Flow workspace via bun)
seedance-direct	SUTUI_API_KEY	native-seedance.ts
runway-useapi	USEAPI_API_TOKEN, USEAPI_ACCOUNT_EMAIL	native-runway.ts (pure Node fetch+fs)
dreamina-useapi	USEAPI_API_TOKEN, VCLAW_DREAMINA_ACCOUNT (e.g. CA:ai@example.com)	native-dreamina.ts (pure Node fetch+fs)

Useful overrides: VCLAW_RUNWAY_MODE=credits (paid faster path; default is free queued explore), VCLAW_RUNWAY_MODEL, VCLAW_DREAMINA_MODEL (default seedance-2.0), VCLAW_DREAMINA_REGION (default CA), and the VCLAW_VEO_* knobs (VCLAW_VEO_CLI_ROOT, VCLAW_VEO_BUN_BIN, VCLAW_VEO_OUTPUT_DIR).

Tips & gotchas

Run verify-env first, every session

verify-env reads keys from your shell, then .env.local, then .env, and tells you the source of each. If a key is "missing", that route shows up unavailable before you waste a submission.

Real human faces get rejected

Both runway-useapi and dreamina-useapi (Seedance moderation) reject photoreal human faces as references. Describe characters by visual descriptor, not proper names, or feed an illustrated / stylized start frame. For identity-locked photoreal characters, use the Asset Library route — see characters.

Free routes are slow on purpose

runway-useapi defaults to explore mode: free, queued, one active slot. It can sit in queue for hours and is meant for overnight backfill drafts. Set VCLAW_RUNWAY_MODE=credits for the paid, faster lane.

Dreamina 1080p is region-gated

Seedance 2.0 at 1080p is CA-region only. 720p works on both US and CA accounts. Set the account region via VCLAW_DREAMINA_REGION.

Capability lives in the registry

Each route declares exactly which operation × aspect-ratio it supports. For example, Veo image-to-video portrait regresses on the direct Flow path, so the registry routes portrait I2V to veo-useapi instead. The providers JSON exposes all of this.

Driving it from an agent

An AI agent (e.g. Claude Code) should run node dist/cli/vclaw.js video verify-env and parse the JSON before any generation. Gate on the top-level ok field and on each route's availability:

• ok: false or non-empty blockingIssues → stop and fix env/build first.
• A target route showing availability: "unavailable" → do not submit to it; pick another available route or supply its missing credentials.

Both commands print JSON to stdout and exit 0 (they are inspectors). The hard stop is at execution time: an unconfigured route throws rather than falling back, so the agent always knows precisely which credential or adapter is missing.

Related

• execute — submit a project to the route you chose here.
• characters — Asset Library identity-locking for Seedance.
• batch — overnight free-mode queue across these routes.
• assemble — stitch the generated clips into a master.
• Deep reference: docs/PROVIDER_PLATFORM.md — descriptor schema, routing policy, and how to add a new route.