brama speak¶
Speak one text through a voice route, over the same credential redemption and refusals POST /v1/audio/speech uses. The provider answers encoded audio rather than JSON, so this command writes a file and says how many bytes went where; printing audio into a terminal is not an outcome anybody wanted, which is why --output is required rather than optional.
Invocation¶
brama speak --input <TEXT> --voice <VOICE> --output <FILE> [--model <ALIAS|ROUTE>] [--response-format <FORMAT>] [--speed <SPEED>] [--json] --allow-provider-cost| Input | Required/default | Meaning |
|---|---|---|
--input <TEXT> | required | What to say. The endpoint accepts up to four thousand and ninety-six bytes in one request. |
--voice <VOICE> | required | The provider's own voice name, such as alloy. Every declared voice provider requires one. |
--output <FILE> | required | Where the audio is written. |
--model <ALIAS|ROUTE> | optional; voice-model | The media alias, or a canonical route the catalogue lists as an audio model. |
--response-format <FORMAT> | optional | The container the provider should encode, such as mp3 or wav. |
--speed <SPEED> | optional | Playback speed between a quarter and four. |
--allow-provider-cost | required to send anything | Acknowledge that this performs a billable provider request. |
--json | optional; off | Print the result as one JSON document instead of key: value lines. |
Output and state¶
A successful run prints model, the route it resolved to, the audio content type the provider stated, how many bytes were written and the output file, as key: value lines or, with --json, as one document with the same fields. Brama re-encodes nothing: what lands on disk is exactly what the provider sent.
A refused run prints the provider's own sentence and exits non-zero. This is a real one, against voice-model routed to openai/gpt-4o-mini-tts on a deployment whose OpenAI account has no credit:
$ brama speak --input "Brama speaks." --voice alloy --output spoken.mp3 --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/.Refusals¶
| Sentence | Meaning |
|---|---|
refusing a billable speech request without explicit --allow-provider-cost | Nothing was sent. |
--speed must be a finite number, not NaN (likewise --stability and --similarity-boost) | A usage error, exit 2; the setting cannot be carried as JSON, so nothing was sent rather than a request with the setting dropped. |
alias `voice-model` is a media alias this gateway knows but no route is declared for it; declare one with `brama routes set voice-model <provider/model>` or `PUT /v1/admin/routes` | The alias has no route here. |
invalid_request: route `together/…` does not generate speech | The named route's provider serves no speech endpoint. |
provider_failure: provider returned no audio | The provider answered success with an empty body; no file was written. |
provider_rate_limited: <the provider's own sentence> | The route was reached and refused. |
cannot write <path>: <reason> | The audio arrived and the destination could not be written. |
Every refusal prints on standard error. A missing --allow-provider-cost is a usage error and exits 2 before anything is sent; every other refusal exits 1.
See media, brama image, brama video, or the CLI tree.