tegwick
e3ab268d6e
Hall of Helix needs a credential-safe render that returns a provenance receipt and refuses a batch before the quote exceeds its cap. OpenRouter is the only client; the model and the live budget stay with the founder. Assistant: grok Assistant-Session: 01a11ab6-1534-7d63-8606-662b92a80ed6
77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# Text-to-image rendering
|
|
|
|
`llm_connect.images` renders one square image from a prompt. It does not
|
|
choose a model or a budget. The caller passes both. Credentials stay in the
|
|
provider client and never appear on a receipt.
|
|
|
|
## Request
|
|
|
|
- Prompt: non-empty, at most 16 000 characters.
|
|
- Size: `WIDTHxHEIGHT`, square, edge from 1024 through 4096. Default
|
|
`1024x1024`.
|
|
- Format: `png` or `jpeg`. A file suffix `.png`, `.jpg`, or `.jpeg` must
|
|
match the format.
|
|
- An existing output file is left untouched unless `force` is set.
|
|
|
|
## Receipt
|
|
|
|
Each successful render returns image bytes and a receipt:
|
|
|
|
- `provider`, `model`
|
|
- `prompt_digest` — SHA-256 of the UTF-8 prompt. The prompt text is not stored.
|
|
- `cost_usd`, `cost_eur`, `cost_source` (`provider`, `quote`, or `unpriced`)
|
|
- `width`, `height`, `media_type`, `output_format`, `byte_length`
|
|
- `output_path` when a file was written
|
|
- `within_cap` — false when the provider cost exceeded a cap that was checked
|
|
before the call. The file is still written, because the provider already
|
|
charged it, and the batch stops.
|
|
|
|
## Spend gate
|
|
|
|
`ImageSpendPolicy` takes `max_cost_usd`, `max_batch_cost_usd`, and
|
|
`quote_usd`. A cap requires a quote. The quote is reserved before the
|
|
provider call. The provider-reported `usage.cost` replaces it on the receipt
|
|
when present. A failed HTTP call releases the reservation. Parallel `/images`
|
|
requests share one gate for the life of the server process.
|
|
|
|
## Provider
|
|
|
|
OpenRouter only, via `POST {api_base}/images` (default
|
|
`https://openrouter.ai/api/v1/images`). The request sends `n=1`,
|
|
`aspect_ratio=1:1`, an explicit pixel `size`, and `output_format`. The key
|
|
comes from the explicit argument, `OPENROUTER_API_KEY`, or
|
|
`apikey-openrouter.txt`. Only `b64_json` is accepted. A URL in the response
|
|
is not fetched.
|
|
|
|
There is no default image model.
|
|
|
|
## CLI
|
|
|
|
```bash
|
|
llm-connect image render \
|
|
--prompt "..." \
|
|
--model "<image-model>" \
|
|
--output visuals/name.jpg \
|
|
--max-cost-usd 0.15 \
|
|
--max-batch-cost-usd 15 \
|
|
--quote-usd 0.08
|
|
|
|
llm-connect image render --batch renders.jsonl --model "<image-model>" \
|
|
--max-cost-usd 0.15 --max-batch-cost-usd 15 --quote-usd 0.08
|
|
```
|
|
|
|
A batch file is JSONL. Each object has `prompt` and `output_path`. The
|
|
receipt JSON goes to stdout. Image bytes stay in the output file. Exit `2`
|
|
means a cap stopped the batch after any already-paid files were written.
|
|
|
|
## HTTP
|
|
|
|
`POST /images` exists when the server is started with `--image-model`,
|
|
`--image-max-cost-usd`, and `--image-quote-usd`. Without those flags the
|
|
path is not found. The body is `prompt`, optional `size`, and optional
|
|
`output_format`. The response is `receipt` plus `image_base64`. Caps are the
|
|
server's, not the caller's. `/execute` is unchanged.
|
|
|
|
Usage rows are appended only when `LLM_CONNECT_USAGE_LEDGER` is set (server)
|
|
or unless `--no-ledger` is passed (CLI). The row's tags carry `kind=image`
|
|
and the prompt digest.
|