brama image¶
Render one image from a shell through the same route, the same Skarbiec credential redemption and the same refusals POST /v1/images/generations uses. It exists for the two moments the HTTP surface cannot cover: establishing that a media route answers at all before a gateway runs, and diagnosing one that stopped.
Invocation¶
brama image --prompt <TEXT> [--model <ALIAS|ROUTE>] [--size <SIZE>] [--n <COUNT>] [--quality <QUALITY>] [--image <FILE>]... [--mask <FILE>] [--aspect-ratio <RATIO>] [--output <FILE>] [--json] --allow-provider-cost| Input | Required/default | Meaning |
|---|---|---|
--prompt <TEXT> | required | What to render. |
--model <ALIAS|ROUTE> | optional; image-model | The media alias, or a canonical provider/model route the catalogue lists as an image model. |
--size <SIZE> | optional | The provider's own size string, such as 1024x1024. |
--n <COUNT> | optional | How many images. The endpoint accepts between one and ten. |
--quality <QUALITY> | optional | The provider's own quality string. |
--image <FILE> | optional; repeatable | An input image the picture is made from. A provider that declares an edit endpoint (OpenAI) is sent an edit on /v1/images/edits; Gemini and Seedream read the images in their generation request. This is the same edit POST /v1/images/edits serves. |
--mask <FILE> | optional; needs --image | A PNG over the first input image whose transparent pixels are what the edit repaints. Only a provider with an edit endpoint takes it. |
--aspect-ratio <RATIO> | optional | An aspect ratio such as 3:4, for the providers that take one. |
--output <FILE> | optional | Decode the returned bytes and write them there. Several images are numbered beside that name. |
--json | optional; off | Print the provider's document instead of lines. |
--allow-provider-cost | required to send anything | Acknowledge that this performs a billable provider request. |
Output and state¶
A successful run prints the alias, the route it resolved to, how many images came back, and for each one either the URL the provider returned or the path and byte count this command wrote. Without --output the encoded length is reported rather than dumped into a terminal.
A refused run prints the provider's own sentence and exits non-zero. This is a real one, against image-model routed to openai/gpt-image-1 on a deployment whose OpenAI account has no credit:
$ brama image --prompt "a plain red square on a white background" --size 1024x1024 --output square.png --allow-provider-cost
credential obtained at final use event="credential_obtained" resource="provider:openai" path="read-grant"
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 only the file it was asked for.
Refusals¶
| Sentence | Meaning |
|---|---|
refusing a billable image generation without explicit --allow-provider-cost | Nothing was sent. Nothing is spent by running this command by accident. |
alias `image-model` is a media alias this gateway knows but no route is declared for it; declare one with `brama routes set image-model <provider/model>` or `PUT /v1/admin/routes` | The alias has no route here. |
invalid_request: route `anthropic/claude-sonnet-4-6` does not generate images | The named route's provider serves no image endpoint. |
invalid_request: image[0] must be a data: URL; an edit is handed the image, Brama does not fetch it | An edit route was handed an https address instead of image bytes. |
provider_rate_limited: <the provider's own sentence> | The route was reached and refused — no credits, a rate limit, a rejected key. |
the provider's image is not base64: <reason> | The answer arrived but its bytes could not be decoded, so no file was 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 video, brama speak, or the CLI tree.