@startanaicompany/vizion

Agent-side CLI for the vizion vision + image-gen gateway at vizion.startanaicompany.com. Three capabilities:

• describe — give it an image (file or URL), get a description back
• generate — give it a prompt, get a generated image back
• modify — give it an image + a prompt, get an edited image back

All three flow through the same gateway, are billed against the caller's ledger account, and use models controlled server-side by env vars.

Install

npm install -g @startanaicompany/vizion

Or as a one-off:

npx @startanaicompany/vizion describe ./screenshot.png

Env

VIZION_API_URL        optional  defaults to https://vizion.startanaicompany.com
SAAC_AGENT_API_KEY    required  injected automatically inside tech.saac-managed
                                agent/assistant containers; set yourself when
                                running the CLI from a regular shell.

Commands

vizion describe <path|url> [--focus "..."] [--model NAME] [--max-tokens N] [--json]
vizion generate "<prompt>"          [--output PATH] [--model NAME] [--json]
vizion modify   <path|url> "<prompt>" [--output PATH] [--model NAME] [--json]
vizion models   [--vision] [--image] [--json]
vizion health
vizion version

Discovering models

vizion models proxies OpenRouter's live catalogue (cached server-side ~5 min) and groups it into the two buckets agents care about:

vizion models            # both lists
vizion models --vision   # only models you can pass to `vizion describe`
vizion models --image    # only models you can pass to `generate`/`modify`
vizion models --json     # raw JSON, suitable for `| jq`

Each row shows the slug (use it as --model …), the friendly name, input→output modalities, context length, and a one-line pricing summary.

<path> is a local file (png/jpg/jpeg/webp/gif). Anything starting with http:// or https:// is treated as a URL — vizion fetches it server-side.

Generate / modify output

Without --output, the raw PNG is written to stdout and a one-line cost footer goes to stderr — same pattern as describe. Redirect or pipe:

vizion generate "watercolor fox in a forest" > fox.png
vizion modify ./fox.png "make it blue" --output blue-fox.png

With --json, you get { image_base64, media_type, model, cost_usd, request_id } on stdout (no file written).

Focus prompt

By default vizion returns a free-form description. Pass --focus to steer the output:

vizion describe screenshot.png --focus "extract every visible button label as JSON"
vizion describe receipt.jpg --focus "return the merchant, date, total, and line items"

Choosing a model

describe uses whatever the gateway has VIZION_DEFAULT_MODEL set to; generate and modify use VIZION_IMAGE_MODEL (default recraft/recraft-v4). Override per-call with --model:

vizion describe ./shot.png --model anthropic/claude-haiku-4-5
vizion generate "a sunset" --model openai/gpt-image-1

Output

Without --json, the description goes to stdout and a one-line cost footer goes to stderr — so pipes still work cleanly:

$ vizion describe ./test.png > description.txt
[vizion google/gemini-3.1-flash-lite-preview-20260303 • 1100+38 tok • $0.000324]

With --json, you get the full response on stdout:

$ vizion describe ./test.png --json
{
  "description": "...",
  "model": "google/gemini-3.1-flash-lite-preview-20260303",
  "usage": { "input_tokens": 1100, "output_tokens": 38, "image_tokens": 0 },
  "cost_usd": 0.000324,
  "request_id": "gen-1778073359-..."
}

cost_usd is the actual upstream USD spend (returned verbatim from the vision provider). The per-call ledger debit fires as a background task on the gateway after the response is sent, so the response body intentionally does not include credit/balance fields — query the ledger directly if you need them.

Exit codes

0 ok      1 usage      2 auth      3 not found      4 network      5 client error