brama video¶
A video is a job, not an answer: the start call returns an identifier and a status, and the render finishes minutes later. This command drives both halves over the same routes and refusals POST /v1/videos and GET /v1/videos/{id} serve.
Invocation¶
brama video start --prompt <TEXT> [--model <ALIAS|ROUTE>] [--size <SIZE>] [--seconds <N>] [--json] --allow-provider-cost
brama video status <JOB_ID> [--model <ALIAS|ROUTE>] [--json]| Input | Required/default | Meaning |
|---|---|---|
--prompt <TEXT> | required for start | What to render. |
<JOB_ID> | required for status | The provider's own job identifier, as start printed it. |
--model <ALIAS|ROUTE> | optional; video-model | The media alias, or a canonical route the catalogue lists as a video model. status needs the same model the job was started with. |
--size <SIZE> | optional | The provider's own size string. |
--seconds <N> | optional | Clip length. The endpoint accepts between one and sixty seconds. |
--json | optional; off | Print the provider's job document instead of lines. |
--allow-provider-cost | required by start | Acknowledge that starting a job performs a billable provider request. |
status takes no acknowledgement: reading a job back costs nothing.
Why status names a model¶
Brama keeps no job state. The identifier belongs to the provider that issued it, so the caller names the same model it started with; a gateway that guessed would eventually ask the wrong vendor, and one that stored the job would become a second source of truth about somebody else's queue.
Output and state¶
Both subcommands print the alias, the route it resolved to, the job identifier and the status the provider reports, plus its progress and error fields when it sends them. With --json the provider's document is printed whole under job.
A refused start prints the provider's own sentence and exits non-zero. This is a real one, against video-model routed to openai/sora-2 on a deployment whose OpenAI account has no credit:
$ brama video start --prompt "a red square" --seconds 4 --allow-provider-cost
provider_rate_limited: You have no credits remaining. Add credits to continue using the API at https://platform.openai.com/settings/organization/billing/.The command reads the route registry and writes nothing.
Refusals¶
| Sentence | Meaning |
|---|---|
refusing a billable video job without explicit --allow-provider-cost | Nothing was sent. |
alias `video-model` is a media alias this gateway knows but no route is declared for it; declare one with `brama routes set video-model <provider/model>` or `PUT /v1/admin/routes` | The alias has no route here. |
invalid_request: route `venice/venice-uncensored` does not generate video | The named route's provider serves no video endpoint. |
invalid_request: video id is not a provider job identifier | The identifier carried something an identifier cannot: a separator, a space, a control byte. |
provider_rate_limited: <the provider's own sentence> | The route was reached and refused. |
Every refusal prints on standard error. A missing --allow-provider-cost on video start is a usage error and exits 2 before anything is sent; every other refusal exits 1.
See media, brama image, brama speak, or the CLI tree.