ai-gateway

# ai-gateway CLI A thin wrapper around the `ai-gateway` CLI (https://vercel.com/ai-gateway) for one-shot text, image, and video generation. Use it whenever a single CLI call beats writing SDK code. ## Defaults - Text model: `xai/grok-4.1-fast-non-reasoning` (cheap + capable) - Image model: `google/imagen-4.0-fast-generate-001` - Video model: `xai/grok-imagine-video` - Override per-call with `-m <model-id>`. Browse with `ai-gateway models --type image|language|video`. ## Notable models - Image-only: `bfl/flux-2-pro`, `bfl/flux-pro-1.1`, `openai/gpt-image-2`, `google/imagen-4.0-generate-001`, `xai/grok-imagine-image`. - Multimodal LLMs (auto-routed through chat completions): `google/gemini-2.5-flash-image` (Nano Banana), `google/gemini-3.1-flash-image-preview` (Nano Banana 2), `google/gemini-3-pro-image`. - Text quality: `anthropic/claude-opus-4.6`, `openai/gpt-5.4`, `xai/grok-4.3`. - Video: `xai/grok-imagine-video` (cheap), `bytedance/seedance-v1.0-lite-t2v`, `google/veo-3.1-fast-generate-001` (premium, audio), `klingai/kling-v2.6-t2v`. ## Steps ### 1. Verify the CLI is installed Run `which ai-gateway`. If missing, install: `npm install -g @vesely/ai-gateway-cli`. **Success criteria**: `which ai-gateway` returns a path. ### 2. Verify the API key is reachable The CLI looks for the key in this order: `--key` flag → `AI_GATEWAY_API_KEY` env → `~/.config/ai-gateway-cli/config.json`. If `AI_GATEWAY_API_KEY` is unset AND the config file is missing/empty, ask the user for it once: tell them to either `export AI_GATEWAY_API_KEY=...` or run `ai-gateway config set key <value>`. Get a key at https://vercel.com/ai-gateway. **Success criteria**: `ai-gateway config` shows a key (masked) OR `$AI_GATEWAY_API_KEY` is set. ### 3. Run the generation **Text** (streamed to stdout): ```bash ai-gateway "<prompt>" # default model ai-gateway -m anthropic/claude-opus-4.6 "<prompt>" ai-gateway --json "<prompt>" # full JSON response (.text, .usage) cat file.md | ai-gateway "<prompt>" # piped stdin is prepended as context ``` **Image** (saves to disk, prints path): ```bash ai-gateway image "<prompt>" # ./ai-image-<timestamp>.png ai-gateway image -o output.png "<prompt>" # custom path ai-gateway image -n 4 "<prompt>" # 4 images, auto-suffixed ai-gateway image -m bfl/flux-2-pro -o cover.png "<prompt>" # specific image-only model ai-gateway image -m google/gemini-2.5-flash-image "<prompt>" # Nano Banana (auto-routed via chat completions) ``` **Video** (saves .mp4 to disk, multi-minute job — prints a spinner with elapsed time): ```bash ai-gateway video "<prompt>" # default model, ./ai-video-<timestamp>.mp4 ai-gateway video -o clip.mp4 --duration 5 "<prompt>" # 5-second clip ai-gateway video -m google/veo-3.1-fast-generate-001 \ --aspect 9:16 --resolution 1080p -o vertical.mp4 "<prompt>" # vertical 1080p Veo ai-gateway video --json --duration 5 "<prompt>" # JSON with cost + elapsed ``` **Success criteria**: - Text: streamed output ends with a newline, exit 0. - Image: stdout contains `Saved: <absolute path>` and the file exists on disk. - Video: stdout contains `Saved: <absolute path>` to a non-empty `.mp4` (or `.webm`). ### 4. Report the result back For text: relay the model output to the user (it's already on stdout). For image: report the absolute path(s) printed by the CLI. Do not re-encode or open the file unless asked. **Success criteria**: User has the answer/file path. ## Rules - Never hardcode an API key in scripts. Resolution is env > config; agents should not read or write `~/.config/ai-gateway-cli/config.json` directly. - For multi-image batches with multimodal LLMs (Nano Banana etc.), the CLI loops `n` times against `/v1/chat/completions` since chat has no native batch — be patient with `-n 4`. - Video generation is slow (often 1-5 minutes) and requires a $10 minimum balance on the AI Gateway account. Don't kill the spinner — wait it out. - If the model id is unknown, run `ai-gateway models --search <substring>` to discover it instead of guessing. - Don't pass `--json` to the image/video command if the user wants a human-readable result; it suppresses the friendly "Saved: ..." lines. - The default text model is non-reasoning + fast; for harder reasoning tasks pick `xai/grok-4.1-fast-reasoning`, `anthropic/claude-opus-4.6`, or `openai/gpt-5.4` via `-m`. ## Troubleshooting - `Unauthorized (401)` → key is wrong/expired. Reset with `ai-gateway config set key <value>`. - `Not found (404). Unknown model?` → run `ai-gateway models --search <hint>`. - `Model "<id>" does not support image generation` → the chosen model isn't an image-only model and lacks the `image-generation` tag. Pick from `ai-gateway models --type image` or use a multimodal LLM listed above. - `Video generation requires a minimum balance of $10` → top up at https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%3Fmodal%3Dtop-up before retrying.