Connect a video provider

Diagram source (live Mermaid)

So far you can plan a whole video for free. To make a real clip — actual moving pictures, not a rehearsal — videoclaw has to hand your request to an AI video engine. That engine is called a provider. This page shows you how to wire up one provider and confirm it's ready.

The good news: you only need one provider to make your first real video. Pick one, set one or two secret keys, run a check, and you're live.

Try the dry run first

You don't need any provider configured to plan a video. Add --dry-run to produce and videoclaw walks the whole pipeline and shows you exactly what it would send — without spending a cent. Set up a provider only when you're ready to render for real. See first video and how it works.

The commands below use the source-checkout form node dist/cli/vclaw.js video .... If you installed the published package, just type vclaw video ... instead.

The four providers

videoclaw can drive four different AI video engines. Each one has a route name — a short id you'll see in the readiness check and in your project's plan. A "route" just means "the exact path your request travels to reach that engine."

Route	veo-useapi	seedance-direct	runway-useapi	dreamina-useapi
Engine	Google Veo	ByteDance Seedance	Runway	Seedance 2.0 / Dreamina
Credential	USEAPI_API_TOKEN	SUTUI_API_KEY	USEAPI_API_TOKEN	USEAPI_API_TOKEN
Free tier	–	–	✓	–
Photoreal faces OK	✓	–	–	–

The four routes side by side. Runway has a free explore mode; Seedance, Runway, and Dreamina reject photoreal human faces. Set only the credential for the route you picked.

Provider	What it is	Route name(s)
Veo	Google's video model (via Google Flow or useapi.net)	veo-useapi
Seedance	ByteDance's Seedance model (great for character consistency)	seedance-direct
Runway	Runway's model via useapi.net (has a free draft mode)	runway-useapi
Dreamina	Seedance 2.0 / Dreamina (CapCut–ByteDance) via useapi.net	dreamina-useapi

New here? Start with Runway's free mode

runway-useapi has a free "explore" mode that makes low-resolution draft clips at no cost. It's slow, but it's the cheapest way to see a real video come out the end of the pipeline. More on that below.

Native transports vs. adapter overrides

There are two ways a route can talk to its provider. You almost always want the first one.

• Native transport (the default, built in). videoclaw already knows how to talk to each provider directly. You don't install anything extra — you just give it the right credential (a secret key or token), and it works. This is the recommended path.
• Adapter override (advanced). If you have your own script or a special setup, you can point a route at it with an environment variable (a setting you put in your shell), e.g. VCLAW_SEEDANCE_DIRECT_ADAPTER. videoclaw sends your script the request as JSON and reads the result back. Skip this unless you have a specific reason. (An "environment variable" is just a named value your terminal remembers — you set it with export NAME=value.)

What each route needs

Each native route needs its own credential. Set the one for the provider you chose — you don't need the others.

Route	Credential(s) to set	Notes
seedance-direct	SUTUI_API_KEY	Optional: VCLAW_SEEDANCE_BASE_URL (defaults to https://api.xskill.ai).
runway-useapi	USEAPI_API_TOKEN	A useapi.net token. Has a free explore mode.
dreamina-useapi	USEAPI_API_TOKEN, VCLAW_DREAMINA_ACCOUNT	Reuses the same useapi.net token as Runway — no new key. Account looks like CA:you@example.com.
veo-useapi	USEAPI_API_TOKEN, USEAPI_ACCOUNT_EMAIL	Google Veo through useapi.net. Its native local transport drives the vclaw-cli Bun/Flow workspace on your machine (Bun runtime); tune with VCLAW_VEO_CLI_ROOT / VCLAW_VEO_BUN_BIN if needed.

Here's how you set a credential in your terminal (do this once per session, or add it to your shell profile so it sticks):

export SUTUI_API_KEY="your-seedance-key-here"

Sets the Seedance key for seedance-direct. Nothing prints — that's normal. Replace the placeholder with your real key. Use the matching variable name from the table for whichever provider you picked.

Setting up Runway / Dreamina (they share one token)

export USEAPI_API_TOKEN="your-useapi-token-here"

Sets the useapi.net token. This one token powers both runway-useapi and dreamina-useapi — you do not need a separate Dreamina key. For Dreamina, also set the account:

export VCLAW_DREAMINA_ACCOUNT="CA:you@example.com"

Tells Dreamina which pre-registered account to bill. The account itself is set up on useapi.net's side beforehand; this just points videoclaw at it. Optional: VCLAW_DREAMINA_REGION (defaults to CA) and VCLAW_DREAMINA_MODEL (defaults to seedance-2.0).

Real human faces get rejected

Seedance, Dreamina, and Runway content filters reject photoreal human faces. Describe people by what they look like ("a tall woman in a red jacket"), not by name, and use stylized or illustrated characters where you can. See characters for how videoclaw keeps a character consistent without tripping the filter.

Check if a route is ready

Before you try to render, ask videoclaw which routes are wired up and which are still missing a credential.

node dist/cli/vclaw.js video providers

Prints a readiness report for every route. In a terminal it's pretty-printed; in a script it's JSON — each route shows up under routes[] with its routeId. Look for the route you set up and confirm it reads as ready.

node dist/cli/vclaw.js video providers | jq '.routes[].routeId'

Lists just the route ids, one per line. Handy if you only want to see the names. (jq is a small tool for reading JSON; install it with brew install jq if you don't have it.)

Routes fail loud — they never silently switch

This is the most important promise on this page, so read it twice.

If the route you asked for isn't configured, videoclaw stops and tells you, with a clear error. It will never quietly send your video to a different provider to "make it work." That protects you from surprise bills, mismatched output, and a render you didn't ask for.

One route, one path

If produce fails with a "route not configured" style message, the fix is always the same: set the credential for that route (from the table above) and run video providers again to confirm. videoclaw will not pick a fallback engine for you — that's a feature, not a bug.

So the safe rhythm is:

1. Plan for free with --dry-run (first video).
2. Set the credential for one route.
3. Confirm with video providers.
4. Run produce for real.

Free drafts with Runway explore mode

Want to watch a real clip come out without spending anything? Use Runway's free explore mode. It makes low-resolution "backfill draft" clips for free — slow, but $0. It's the cheapest way to prove the whole pipeline end-to-end before you pay for hi-res.

The overnight batch queue defaults to exactly this free Runway route, so you can line up many draft clips and let them finish overnight:

node dist/cli/vclaw.js video batch-submit --manifest batch.json --out runs/overnight

Queues every job in your batch.json manifest to the free runway-useapi explore route by default and writes runs/overnight/batch-queue.json. Add --route dreamina-useapi (or seedance-direct) instead when you want paid hi-res.

node dist/cli/vclaw.js video batch-monitor --out runs/overnight --once

Does one polling pass: downloads any finished clips into runs/overnight/ and updates runs/overnight/batch-status.json. Safe to run again and again — it never re-downloads a clip it already has.

You're ready

Once video providers shows your chosen route as ready, your produce runs will make real clips. When the clips are in, the next step is to look at them, approve the result, and ship it.

Next: Review & publish. Related: how it works · modes · assemble · troubleshooting · cheat sheet.