0001 Video Provider Spec

1. A versioned video provider spec

Status: accepted
Date: 2026-08-05
Context: adding MiniMax H3 alongside BytePlus Seedance

Context and constraints

vs generated video against exactly one backend, BytePlus ModelArk. Adding MiniMax H3 makes that two, and the shape of the codebase assumed one:

src/provider.ts declared a VideoProvider port, but no command used it. (It has since been deleted: VideoModelV4 is the port, and vs doctor's raw status probe is typed by the one method it calls.) generate.ts, status.ts, and doctor.ts all typed the client as ArkClient. Its own doc comment said no adapter existed "and none should".
CreateTaskRequest in src/types.ts is simultaneously the canonical internal request and the Ark wire body. Every caller that builds a generation is therefore writing an Ark payload, whether it knows it or not.
src/cost.ts prices in tokens end to end. Billing.perSecond was declared and never implemented, so a per-second model quoted $0.00 and walked straight through --max-cost.
Model capabilities were already data in src/models.ts, but four authoring behaviours were gated on an isSeedance25() family-string predicate.

Constraints that shape the answer:

Single package, single consumer. This is one CLI binary, not a published SDK with third-party providers. Nobody outside this repo implements the spec.
Cost is a safety property (SECURITY.md). A quote must never be lower than the bill, and --dry-run must work with no API key at all.
Generated video is immutable and paid for. payloadHash in the manifest is an audit record; churning it silently invalidates every existing film's history.
Two providers is a measurement. Three is a pattern. This decision commits to what two providers prove and explicitly defers the rest.

Decision

Adopt a versioned provider spec in the shape of the Vercel AI SDK's , in-package, with the pieces that two divergent wire formats actually justify and none of the pieces that only a published SDK needs.

Context and constraints

vs generated video against exactly one backend, BytePlus ModelArk. Adding MiniMax H3 makes that two, and the shape of the codebase assumed one:

src/provider.ts declared a VideoProvider port, but no command used it. (It has since been deleted: VideoModelV4 is the port, and vs doctor's raw status probe is typed by the one method it calls.) generate.ts, status.ts, and doctor.ts all typed the client as ArkClient. Its own doc comment said no adapter existed "and none should".

CreateTaskRequest in src/types.ts is simultaneously the canonical internal request and the Ark wire body. Every caller that builds a generation is therefore writing an Ark payload, whether it knows it or not.

src/cost.ts prices in tokens end to end. Billing.perSecond was declared and never implemented, so a per-second model quoted $0.00 and walked straight through --max-cost.

Model capabilities were already data in src/models.ts, but four authoring behaviours were gated on an isSeedance25() family-string predicate.

Constraints that shape the answer:

Single package, single consumer. This is one CLI binary, not a published SDK with third-party providers. Nobody outside this repo implements the spec.

Cost is a safety property (SECURITY.md). A quote must never be lower than the bill, and --dry-run must work with no API key at all.

Generated video is immutable and paid for. payloadHash in the manifest is an audit record; churning it silently invalidates every existing film's history.

Two providers is a measurement. Three is a pattern. This decision commits to what two providers prove and explicitly defers the rest.

Term	Meaning	Lives in
Film	A `shots.json` and its output directory	`src/shots.ts`
Shot	One authored unit of generation	`src/types.ts`
Revision	One paid attempt at a shot (`vNNN`), append-only	`src/manifest.ts`
Pass	`draft` or `final`; picks the manifest and output dir	`src/paths.ts`
Reference	A role-tagged input image/video/audio on a shot	`src/types.ts`
Ordinal	A reference's 1-based index within its media type	`src/payload.ts`
Model	A generation model id, e.g. `dreamina-seedance-2-5-260628`	`src/models.ts`
Provider	The backend a model id is generated on	`src/models.ts`
Capabilities	What a model accepts and how it bills	`src/models.ts`

Not doing	Why	Promote when
Separate npm packages per provider (`packages/ark`, `packages/minimax`)	One binary, one consumer. A package split buys independent versioning nobody needs and couples release cycles.	Someone outside this repo implements the spec.
Adopting the AI SDK's `experimental_generateVideo` in place of this port	`@ai-sdk/provider` ships `VideoModelV4`, and this port now takes its version number and field names from it. What upstream does not carry is `capabilities` (so `--dry-run` and cost estimation would need a key and a network call), `toRequestBody` (so `payloadHash` could not be a byte-stable audit record), and any billing model at all. `generateVideo` also polls inside a single call, where `tasks.json` has to resume across processes.	Upstream exposes a capability or billing surface, or `payloadHash` stops being a pinned audit record.
A `--flex` flag for BytePlus offline inference	The wire field is real (`service_tier: "flex"`, plus `execution_expires_after`) and the discount is a flat 50% on the token rate, so the existing estimator would just take a 0.5 multiplier. But offline inference is unsupported on the whole Seedance 2.0 series AND 2.5, which is every model this repo generates on; it exists only for 1.0/1.5-pro. It is also incompatible with `--draft` (last-frame return is disabled under it).	BytePlus enables offline inference on 2.5 or the 2.0 series. Then it is a capability bit in `src/models.ts` plus a rate multiplier, so `--dry-run` can refuse it with no key.
Widening the task handle to upstream's opaque `operation: JSONValue`	`ManifestEntry.taskId` is a string that `vs status <task-id>` and the `--json` key contract both depend on, and both shipped providers key on an id. Widening it is a manifest migration for no present gain.	A provider whose resumption handle is not expressible as a string.
Middleware / `wrapVideoModel`	No current requirement. Retry and rate limiting already live at the seam (`ModelLimiter`, the shared HTTP loop).	A cross-cutting concern appears that is not retry or concurrency.
A plugin loader for third-party providers	Providers are compiled in; a dynamic loader is an attack surface for a tool that spends money. `vs` ships no library entry at all now, so there is nothing for a plugin to link against.	Never, unless `vs` becomes a library.
Streaming	Video generation is submit-then-poll. There is no token stream.	A provider ships partial-frame streaming.
Unifying the stills backends (Seedream, Gemini) behind the spec	Stills cost cents, not dollars, and are already routed by model id in `stills.ts`. `src/provider.ts` already documents this as deliberate.	A third stills backend, or stills start costing dollars.
Extracting the model registry into its own package	Same reason as the provider split.	Same trigger.
A cross-provider capability negotiation layer (auto-picking a model that fits a shot)	Speculative. Model choice is an authoring decision with cost and look consequences the tool should not make silently.	An explicit user request for it.

Not doing

Why

Promote when

Separate npm packages per provider (packages/ark, packages/minimax)

One binary, one consumer. A package split buys independent versioning nobody needs and couples release cycles.

Someone outside this repo implements the spec.

Adopting the AI SDK's experimental_generateVideo in place of this port

@ai-sdk/provider ships VideoModelV4, and this port now takes its version number and field names from it. What upstream does not carry is capabilities (so --dry-run and cost estimation would need a key and a network call), toRequestBody (so payloadHash could not be a byte-stable audit record), and any billing model at all. generateVideo also polls inside a single call, where tasks.json has to resume across processes.

Upstream exposes a capability or billing surface, or payloadHash stops being a pinned audit record.

A --flex flag for BytePlus offline inference

The wire field is real (service_tier: "flex", plus execution_expires_after) and the discount is a flat 50% on the token rate, so the existing estimator would just take a 0.5 multiplier. But offline inference is unsupported on the whole Seedance 2.0 series AND 2.5, which is every model this repo generates on; it exists only for 1.0/1.5-pro. It is also incompatible with --draft (last-frame return is disabled under it).

BytePlus enables offline inference on 2.5 or the 2.0 series. Then it is a capability bit in src/models.ts plus a rate multiplier, so --dry-run can refuse it with no key.

Widening the task handle to upstream's opaque operation: JSONValue

ManifestEntry.taskId is a string that vs status <task-id> and the --json key contract both depend on, and both shipped providers key on an id. Widening it is a manifest migration for no present gain.

A provider whose resumption handle is not expressible as a string.

Middleware / wrapVideoModel

No current requirement. Retry and rate limiting already live at the seam (ModelLimiter, the shared HTTP loop).

A cross-cutting concern appears that is not retry or concurrency.

A plugin loader for third-party providers

Providers are compiled in; a dynamic loader is an attack surface for a tool that spends money. vs ships no library entry at all now, so there is nothing for a plugin to link against.

Never, unless vs becomes a library.

Streaming

Video generation is submit-then-poll. There is no token stream.

A provider ships partial-frame streaming.

Unifying the stills backends (Seedream, Gemini) behind the spec

Stills cost cents, not dollars, and are already routed by model id in stills.ts. src/provider.ts already documents this as deliberate.

A third stills backend, or stills start costing dollars.

Extracting the model registry into its own package

Same reason as the provider split.

Same trigger.

A cross-provider capability negotiation layer (auto-picking a model that fits a shot)

Speculative. Model choice is an authoring decision with cost and look consequences the tool should not make silently.

An explicit user request for it.

Rule	Enforced by
Commands never import a provider client directly	Import-boundary lint rule: nothing under `src/commands/` may import `src/providers/*`
Providers never import commands	Same rule, reversed
Every registry entry is complete	Type check: `RegistryEntry` is a total `Omit<ModelCapabilities, …>`
A per-second model never quotes $0	Unit test in `src/cost.test.ts`
A rate table prices exactly the resolutions its model accepts	Ratchet test in `src/models.test.ts`
A paid POST is never replayed after an ambiguous failure	Unit tests in `src/ark.test.ts`; `requestWithRetry` splits its retry predicate by method
A submit that never returned an id is not silently resubmitted	`isUnresolved` guard in `vs generate`, tested in `src/commands/generate.test.ts`
`--max-cost` is checked against the ceiling, not the low end	Unit test in `src/cost.test.ts`
Ark payload bytes are unchanged	Pinned-hash test
Documented commands and flags are real	`src/docs-drift.test.ts` (already exists)
Shipped example films lint clean	`src/examples.test.ts` (already exists)

0001 Video Provider Spec

1. A versioned video provider spec

Context and constraints

Decision

0001 Video Provider Spec

1. A versioned video provider spec

Context and constraints

Decision

Glossary

The four layers

Model id resolution

Why the interface is versioned

`payloadHash` stays stable

Consequences

Out of scope (deferred)

Enforcement

0001 Video Provider Spec

1. A versioned video provider spec

Context and constraints

Decision

0001 Video Provider Spec

1. A versioned video provider spec

Context and constraints

Decision

Glossary

The four layers

Model id resolution

Why the interface is versioned

payloadHash stays stable

Consequences

Out of scope (deferred)

Enforcement

`payloadHash` stays stable