zevairouter 1.1.38 → 1.1.40

package/skills/zevai/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: zevairouter
+description: Entry point for ZevaiRouter — local/remote AI gateway with OpenAI-compatible REST for chat, image, video, TTS, embeddings, web search, and web fetch. Use when the user mentions ZevaiRouter, ZEVAI_URL, or wants AI without writing provider boilerplate. This skill covers setup and indexes capability skills.
+---
+
+# ZevaiRouter
+
+Local/remote AI gateway exposing OpenAI-compatible REST. One key, many providers, auto-fallback.
+
+## Setup
+
+```bash
+export ZEVAI_URL="http://localhost:1997"      # or VPS / tunnel URL
+export ZEVAI_KEY="sk-..."                      # from Dashboard → Keys (only if requireApiKey=true)
+```
+
+All requests: `${ZEVAI_URL}/v1/...` with header `Authorization: Bearer ${ZEVAI_KEY}` (omit if auth disabled).
+
+Verify: `curl $ZEVAI_URL/api/health` → `{"ok":true}`
+
+## Discover models
+
+```bash
+curl $ZEVAI_URL/v1/models                  # chat/LLM (default)
+curl $ZEVAI_URL/v1/models/image            # image-gen
+curl $ZEVAI_URL/v1/models/video            # video-gen
+curl $ZEVAI_URL/v1/models/tts              # text-to-speech
+curl $ZEVAI_URL/v1/models/embedding        # embeddings
+curl $ZEVAI_URL/v1/models/web              # web search + fetch (entries have `kind` field)
+curl $ZEVAI_URL/v1/models/stt              # speech-to-text
+curl $ZEVAI_URL/v1/models/image-to-text    # vision
+```
+
+Use `data[].id` as `model` field in requests. Combos appear with `owned_by:"combo"`.
+
+Response shape:
+```json
+{ "object": "list", "data": [
+  { "id": "openai/gpt-5", "object": "model", "owned_by": "openai", "created": 1735000000 },
+  { "id": "tavily/search", "object": "model", "kind": "webSearch", "owned_by": "tavily", "created": 1735000000 }
+]}
+```
+
+## Capability skills
+
+When the user needs a specific capability, fetch that skill's `SKILL.md` from its raw URL:
+
+| Capability | Raw URL |
+|---|---|
+| Chat / code-gen | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai-chat/SKILL.md |
+| Image generation | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai-image/SKILL.md |
+| Video generation | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai-video/SKILL.md |
+| Text-to-speech | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai-tts/SKILL.md |
+| Speech-to-text | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai-stt/SKILL.md |
+| Embeddings | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai-embeddings/SKILL.md |
+| Web search | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai-web-search/SKILL.md |
+| Web fetch (URL → markdown) | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai-web-fetch/SKILL.md |
+
+## Errors
+
+- 401 → set/refresh `ZEVAI_KEY` (Dashboard → Keys)
+- 400 `Invalid model format` → check `model` exists in `/v1/models/<kind>`
+- 503 `All accounts unavailable` → wait `retry-after` or add another provider account

package/skills/zevai-chat/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: zevairouter-chat
+description: Chat / code generation via ZevaiRouter using OpenAI /v1/chat/completions or Anthropic /v1/messages format with streaming + auto-fallback combos. Use when the user wants to ask an LLM, generate code, summarize text, or run prompts through ZevaiRouter.
+---
+
+# ZevaiRouter — Chat
+
+Requires `ZEVAI_URL` (and `ZEVAI_KEY` if auth enabled). See https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai/SKILL.md for setup.
+
+## Endpoints
+
+- `POST $ZEVAI_URL/v1/chat/completions` — OpenAI format
+- `POST $ZEVAI_URL/v1/messages` — Anthropic format
+
+## Discover
+
+```bash
+curl $ZEVAI_URL/v1/models | jq '.data[].id'
+# Per-model metadata (contextWindow, params)
+curl "$ZEVAI_URL/v1/models/info?id=openai/gpt-4o"
+```
+
+Combos (e.g. `vip`, `mycodex`) auto-fallback through multiple providers.
+
+## OpenAI format
+
+```bash
+curl -X POST $ZEVAI_URL/v1/chat/completions \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/gpt-5","messages":[{"role":"user","content":"Hi"}],"stream":false}'
+```
+
+JS (OpenAI SDK):
+
+```js
+import OpenAI from "openai";
+const client = new OpenAI({ baseURL: `${process.env.ZEVAI_URL}/v1`, apiKey: process.env.ZEVAI_KEY });
+const res = await client.chat.completions.create({
+  model: "openai/gpt-5",
+  messages: [{ role: "user", content: "Hi" }],
+  stream: true,
+});
+for await (const chunk of res) process.stdout.write(chunk.choices[0]?.delta?.content || "");
+```
+
+## Anthropic format
+
+```bash
+curl -X POST $ZEVAI_URL/v1/messages \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"cc/claude-opus-4-7","max_tokens":1024,"messages":[{"role":"user","content":"Hi"}]}'
+```
+
+## Response shape
+
+OpenAI (`/v1/chat/completions`):
+```json
+{ "id": "chatcmpl-...", "object": "chat.completion", "model": "openai/gpt-5",
+  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello!" }, "finish_reason": "stop" }],
+  "usage": { "prompt_tokens": 8, "completion_tokens": 2, "total_tokens": 10 } }
+```
+
+Streaming (`stream:true`) emits SSE: `data: {choices:[{delta:{content:"..."}}]}\n\n` ... `data: [DONE]\n\n`.
+
+Anthropic (`/v1/messages`):
+```json
+{ "id": "msg_...", "type": "message", "role": "assistant", "model": "cc/claude-opus-4-7",
+  "content": [{ "type": "text", "text": "Hello!" }],
+  "stop_reason": "end_turn", "usage": { "input_tokens": 8, "output_tokens": 2 } }
+```

package/skills/zevai-embeddings/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: zevairouter-embeddings
+description: Generate vector embeddings via ZevaiRouter /v1/embeddings using OpenAI / Gemini / Mistral / Voyage / Nvidia / GitHub embedding models for RAG, semantic search, similarity. Use when the user wants embeddings, vectors, RAG, semantic search, or to embed text.
+---
+
+# ZevaiRouter — Embeddings
+
+Requires `ZEVAI_URL` (and `ZEVAI_KEY` if auth enabled). See https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $ZEVAI_URL/v1/models/embedding | jq '.data[].id'
+# Per-model dimensions
+curl "$ZEVAI_URL/v1/models/info?id=openai/text-embedding-3-small"
+```
+
+## Endpoint
+
+`POST $ZEVAI_URL/v1/embeddings`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | from `/v1/models/embedding` |
+| `input` | yes | string OR array of strings |
+| `encoding_format` | no | `float` (default) / `base64` |
+| `dimensions` | no | OpenAI v3 only |
+
+## Examples
+
+```bash
+curl -X POST $ZEVAI_URL/v1/embeddings \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/text-embedding-3-small","input":["hello","world"]}'
+```
+
+JS:
+
+```js
+const r = await fetch(`${process.env.ZEVAI_URL}/v1/embeddings`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.ZEVAI_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "gemini/text-embedding-004", input: "RAG chunk text" }),
+});
+const { data } = await r.json();
+console.log(data[0].embedding.length);  // dimension
+```
+
+## Response shape
+
+```json
+{ "object": "list", "model": "openai/text-embedding-3-small",
+  "data": [
+    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.045, ...] },
+    { "object": "embedding", "index": 1, "embedding": [...] }
+  ],
+  "usage": { "prompt_tokens": 5, "total_tokens": 5 } }
+```
+
+## Provider quirks
+
+| Provider | Notes |
+|---|---|
+| `openai`, `openrouter`, `mistral`, `voyage-ai`, `fireworks`, `together`, `nebius`, `github`, `nvidia`, `jina-ai` | Native OpenAI shape — `dimensions` works only on OpenAI v3 (`text-embedding-3-*`) |
+| `gemini`, `google_ai_studio` | Server auto-converts to `embedContent`/`batchEmbedContents` — send OpenAI shape |
+| `openai-compatible-*`, `custom-embedding-*` | Custom `baseUrl` from credentials |
+
+Batch (`input` as array) is faster; some providers cap batch size.

package/skills/zevai-image/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: zevairouter-image
+description: Generate images via ZevaiRouter /v1/images/generations using Google Flow Nano Banana, OpenAI / Gemini Imagen / DALL-E / FLUX / MiniMax / SDWebUI / ComfyUI / Codex models. Use when the user wants to create, generate, draw, or render an image, picture, or text-to-image (txt2img).
+---
+
+# ZevaiRouter — Image Generation
+
+Requires `ZEVAI_URL` (and `ZEVAI_KEY` if auth enabled). See https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $ZEVAI_URL/v1/models/image | jq '.data[].id'
+# Per-model params/options (size enum, quality enum, capabilities like edit)
+curl "$ZEVAI_URL/v1/models/info?id=openai/dall-e-3"
+```
+
+## Endpoint
+
+`POST $ZEVAI_URL/v1/images/generations`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | from `/v1/models/image` |
+| `prompt` | yes | image description |
+| `n` | no | count (provider-dependent) |
+| `size` | no | `1024x1024`, `1792x1024`, ... |
+| `quality` | no | `standard` / `hd` (OpenAI) |
+| `response_format` | no | `url` (default) or `b64_json` |
+
+Add query `?response_format=binary` to receive raw image bytes (handy for saving file).
+
+## Examples
+
+Save to file (binary):
+
+```bash
+curl -X POST "$ZEVAI_URL/v1/images/generations?response_format=binary" \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gemini/gemini-3-pro-image-preview","prompt":"watercolor mountains at sunrise","size":"1024x1024"}' \
+  --output out.png
+```
+
+Google Flow Nano Banana (portrait, returned as the source JPEG):
+
+```bash
+curl -X POST "$ZEVAI_URL/v1/images/generations?response_format=binary" \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"flow/nano2","prompt":"cinematic portrait at blue hour","size":"768x1376"}' \
+  --output out.jpg
+```
+
+Flow models: `flow/nano2` (default, fast), `flow/nano-pro` (best quality), `flow/nano2-lite`. If the user names a model, use it. `size` only picks the aspect ratio: `1024x1024` square, `1792x1024` 16:9, `768x1376` 9:16. A Flow image takes about 40 s and runs one at a time with other Flow jobs; HTTP 423 means Flow is busy, so wait a minute and retry. If the saved file is not an image, it holds a JSON error.
+
+JS (URL response):
+
+```js
+const r = await fetch(`${process.env.ZEVAI_URL}/v1/images/generations`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.ZEVAI_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "gemini/gemini-3-pro-image-preview", prompt: "neon city", size: "1024x1024" }),
+});
+const { data } = await r.json();
+console.log(data[0].url || data[0].b64_json.slice(0, 40));
+```
+
+## Response shape
+
+JSON (default `response_format=url`):
+```json
+{ "created": 1735000000, "data": [{ "url": "https://..." }] }
+```
+
+`response_format=b64_json`:
+```json
+{ "created": 1735000000, "data": [{ "b64_json": "iVBORw0KGgo..." }] }
+```
+
+Query `?response_format=binary` returns raw image bytes (Content-Type `image/png` or `image/jpeg`).
+
+## Provider quirks
+
+Common fields above work everywhere. These add/override:
+
+| Provider | Extra/changed fields | Notes |
+|---|---|---|
+| `openai`, `minimax`, `openrouter`, `recraft` | `quality`, `style`, `response_format` | Standard OpenAI shape |
+| `gemini` (nano-banana) | — | Only `prompt`; ignores `size`/`n` |
+| `codex` (gpt-5.4-image) | `image`, `images[]`, `image_detail`, `output_format`, `background` | SSE stream; **ChatGPT Plus/Pro required** |
+| `huggingface` | — | Only `prompt`; returns single image |
+| `nanobanana` | `image`, `images[]` (edit mode) | `size` → aspect ratio; async polling |
+| `fal-ai` | `image` (img2img) | `n` → `num_images`; `size` → ratio; async |
+| `stability-ai` | `style` (preset), `output_format` | `size` → `aspect_ratio` |
+| `black-forest-labs` (FLUX) | `image` (ref) | `size` → exact `width`/`height`; async |
+| `runwayml` | `image` (ref) | `size` → ratio; async; video models exist |
+| `sdwebui`, `comfyui` | — | Localhost noAuth (`:7860` / `:8188`) |
+| `flow` | `nano2`, `nano2-lite`, `nano-pro`; `size` is mapped to the nearest Flow aspect ratio | Requires a local authenticated gflow daemon. Images have not consumed Flow credits in live verification; Google may change plan behavior. |

package/skills/zevai-stt/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: zevairouter-stt
+description: Speech-to-text via ZevaiRouter /v1/audio/transcriptions using OpenAI Whisper / Groq / Gemini / Deepgram / AssemblyAI / NVIDIA / HuggingFace models. Use when the user wants to transcribe audio, convert speech to text, or get subtitles from audio files.
+---
+
+# ZevaiRouter — Speech-to-Text
+
+Requires `ZEVAI_URL` (and `ZEVAI_KEY` if auth enabled). See https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $ZEVAI_URL/v1/models/stt | jq '.data[].id'
+# Per-model params (language, response_format, prompt, temperature support)
+curl "$ZEVAI_URL/v1/models/info?id=openai/whisper-1"
+```
+
+`model` = STT model ID (e.g. `openai/whisper-1`, `groq/whisper-large-v3`, `deepgram/nova-3`, `gemini/gemini-2.5-flash`).
+
+## Endpoint
+
+`POST $ZEVAI_URL/v1/audio/transcriptions` (OpenAI Whisper compatible, `multipart/form-data`)
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | from `/v1/models/stt` |
+| `file` | yes | audio file (mp3, wav, m4a, webm, ogg, flac) |
+| `language` | no | ISO-639-1 (e.g. `en`, `vi`) |
+| `prompt` | no | hint text to guide transcription |
+| `response_format` | no | `json` (default) / `text` / `verbose_json` / `srt` / `vtt` |
+| `temperature` | no | 0–1 |
+
+## Examples
+
+```bash
+curl -X POST "$ZEVAI_URL/v1/audio/transcriptions" \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -F "model=openai/whisper-1" \
+  -F "file=@audio.mp3" \
+  -F "language=vi"
+```
+
+JS (Node):
+
+```js
+import { createReadStream } from "node:fs";
+const form = new FormData();
+form.append("model", "groq/whisper-large-v3-turbo");
+form.append("file", new Blob([await (await import("node:fs/promises")).readFile("audio.mp3")]), "audio.mp3");
+const r = await fetch(`${process.env.ZEVAI_URL}/v1/audio/transcriptions`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.ZEVAI_KEY}` },
+  body: form,
+});
+const { text } = await r.json();
+console.log(text);
+```
+
+## Response shape
+
+Default (`response_format=json`):
+```json
+{ "text": "Xin chào, đây là bản ghi âm." }
+```
+
+`verbose_json` adds `language`, `duration`, `segments[]` with timestamps.
+`srt` / `vtt` return subtitle text.
+
+## Provider quirks
+
+| Provider | `model` format | Notes |
+|---|---|---|
+| `openai` | `whisper-1`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` | Native OpenAI shape |
+| `groq` | `whisper-large-v3`, `whisper-large-v3-turbo`, `distil-whisper-large-v3-en` | Fastest; OpenAI shape |
+| `gemini` | `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-2.5-flash-lite` | Server converts to `generateContent` with audio inline |
+| `deepgram` | `nova-3`, `nova-2`, `whisper-large` | Token auth; server adapts response |
+| `assemblyai` | `universal-3-pro`, `universal-2` | Async upload+poll handled server-side |
+| `nvidia` | `nvidia/parakeet-ctc-1.1b-asr` | NIM endpoint |
+| `huggingface` | `openai/whisper-large-v3`, `openai/whisper-small` | HF Inference API |

package/skills/zevai-tts/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: zevairouter-tts
+description: Text-to-speech via ZevaiRouter /v1/audio/speech using OpenAI / ElevenLabs / Deepgram / Edge TTS / Google TTS / Hyperbolic / Inworld voices. Use when the user wants to convert text to speech, generate audio, voiceover, narrate, or read text aloud.
+---
+
+# ZevaiRouter — Text-to-Speech
+
+Requires `ZEVAI_URL` (and `ZEVAI_KEY` if auth enabled). See https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai/SKILL.md for setup.
+
+## Discover
+
+```bash
+# 1) List models
+curl $ZEVAI_URL/v1/models/tts | jq '.data[].id'
+# 2) Per-model metadata (params, voicesUrl if voice-by-id)
+curl "$ZEVAI_URL/v1/models/info?id=el/eleven_multilingual_v2"
+# 3) List voices (elevenlabs, edge-tts, deepgram, inworld, local-device). Optional ?lang=vi
+curl "$ZEVAI_URL/v1/audio/voices?provider=edge-tts&lang=vi" | jq '.data[].model'
+```
+
+`model` field in `/v1/audio/speech` = voice ID directly (e.g. `edge-tts/vi-VN-HoaiMyNeural`, `el/<voice_id>`, or `openai/tts-1` model+default voice).
+
+## Endpoint
+
+`POST $ZEVAI_URL/v1/audio/speech`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | voice ID from `/v1/models/tts` |
+| `input` | yes | text to speak |
+
+Query `?response_format=mp3` (default, raw bytes) or `?response_format=json` (`{audio: base64, format}`).
+
+## Examples
+
+Save MP3:
+
+```bash
+curl -X POST "$ZEVAI_URL/v1/audio/speech" \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/tts-1","input":"Hello world"}' \
+  --output speech.mp3
+```
+
+JS (save file):
+
+```js
+import { writeFile } from "node:fs/promises";
+const r = await fetch(`${process.env.ZEVAI_URL}/v1/audio/speech`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.ZEVAI_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "el/eleven_multilingual_v2", input: "Xin chào" }),
+});
+await writeFile("speech.mp3", Buffer.from(await r.arrayBuffer()));
+```
+
+## Response shape
+
+Default → raw audio bytes (Content-Type `audio/mp3`).
+
+`?response_format=json`:
+```json
+{ "audio": "SUQzBAAAA...", "format": "mp3" }
+```
+
+## Provider quirks (model format)
+
+| Provider | `model` format | Notes |
+|---|---|---|
+| `openai` | `tts-1/alloy` (model/voice) or just voice | Default model `gpt-4o-mini-tts` |
+| `elevenlabs` | `<model_id>/<voice_id>` or `<voice_id>` | Default model `eleven_flash_v2_5`; list voices in Dashboard |
+| `openrouter` | `openai/gpt-4o-mini-tts/alloy` | Streamed via chat-completions audio modality |
+| `edge-tts` | voice id e.g. `vi-VN-HoaiMyNeural` | **noAuth**; default `vi-VN-HoaiMyNeural` |
+| `google-tts` | language code e.g. `en`, `vi` | **noAuth** |
+| `local-device` | OS voice name (`say -v ?` / SAPI) | **noAuth**; needs `ffmpeg` |
+| `deepgram` | `aura-asteria-en` etc | Token auth |
+| `nvidia`, `inworld`, `cartesia`, `playht` | `model/voice` | Provider-specific auth header |
+| `coqui`, `tortoise` | speaker / voice id | Localhost noAuth |
+| `hyperbolic` | model id | Body = `{text}` only |

package/skills/zevai-video/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: zevairouter-video
+description: Generate videos via ZevaiRouter /v1/videos/generations using xAI Grok Imagine or Google Flow Veo / Omni Flash. The async flow submits a job, polls request_id until done, then downloads the MP4. Use for text-to-video, long video up to 60 seconds, image-to-video, video edits, or extensions.
+---
+
+# ZevaiRouter — Video Generation
+
+Requires `ZEVAI_URL` and, when API-key auth is enabled, `ZEVAI_KEY`. See the entry skill at https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai/SKILL.md
+
+Connect an xAI account or a local Google Flow/gflow profile in the ZevaiRouter dashboard. Video jobs are asynchronous: submit, poll `request_id` until `done` or `failed`, then download `video.url`. xAI jobs are account-bound and need the returned connection header while polling; router-owned Flow job IDs (`flow_...`) poll without it.
+
+## Choosing a model
+
+If the user names a model, use exactly that one. Otherwise, for Google Flow, default to `flow/omni-flash`, and use `flow/omni-flash-long` when the user asks for more than 10 seconds. Do not switch models on your own.
+
+| Model | Length | Flow credits | Notes |
+|---|---|---|---|
+| `flow/omni-flash` | 10 s | 15 | Default for Flow |
+| `flow/omni-flash-long` | 10, 20, 30, 40, 50 or 60 s | 15 per 10 s | Segments joined into one MP4 |
+| `flow/veo-lite` | 8 s | 10 | "veo" / "veo lite" |
+| `flow/veo-fast` | 8 s | 20 | "veo fast" |
+| `flow/veo-quality` | 8 s | 100 | "veo quality" |
+| `xai/grok-imagine-video` | provider-defined | — | xAI account |
+
+## Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /v1/videos/generations` | Text-to-video or image-to-video |
+| `POST /v1/videos/edits` | Edit an existing video |
+| `POST /v1/videos/extensions` | Extend an existing video |
+| `GET /v1/videos/{request_id}` | Poll job status |
+
+Common generation fields:
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` | yes | xAI: `xai/grok-imagine-video`. Flow: `flow/veo-lite`, `flow/veo-fast`, `flow/veo-quality`, `flow/omni-flash`, or `flow/omni-flash-long` |
+| `prompt` | yes for text-to-video | Video description |
+| `duration` | no | Flow Veo (8 s) and Omni (10 s) clips have a fixed length: send `duration` only with `flow/omni-flash-long` (exactly 10/20/30/40/50/60) |
+| `aspect_ratio` | no | Flow supports `16:9` or `9:16`; other providers may support more |
+| `resolution` | no | Provider-dependent |
+| `segment_prompts` | no | Flow long-video only: optional prompt per 10s segment |
+| `image` | no | Provider-dependent image-to-video input |
+| `video` | edits/extensions | Provider-dependent existing video input |
+
+## Submit and poll
+
+```bash
+curl -i -X POST "$ZEVAI_URL/v1/videos/generations" \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"xai/grok-imagine-video","prompt":"A cinematic tracking shot through a neon city at night","duration":8,"aspect_ratio":"16:9","resolution":"720p"}'
+```
+
+The JSON response includes a `request_id`. Save the response header `x-zevai-connection-id`; echo it back while polling so the same upstream account is used:
+
+```bash
+curl "$ZEVAI_URL/v1/videos/REQUEST_ID" \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "x-connection-id: CONNECTION_ID"
+```
+
+Continue polling until the response is `done` or `failed`. On success, download `video.url`.
+
+## Google Flow
+
+Always send an `Idempotency-Key`. Reuse the same key if you have to resubmit the same request, so the router returns the existing job instead of billing a second render.
+
+```bash
+curl -sS -X POST "$ZEVAI_URL/v1/videos/generations" \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: my-video-001" \
+  -d '{"model":"flow/omni-flash","prompt":"Handheld footage of waves rolling onto a beach at sunset","aspect_ratio":"16:9"}'
+# -> {"request_id":"flow_...","status":"pending"}
+```
+
+Poll every 15 s. A 10 s clip usually takes 1–3 minutes; a 60 s video can take 15+ minutes and may first wait in the queue:
+
+```bash
+curl -sS "$ZEVAI_URL/v1/videos/flow_..." -H "Authorization: Bearer $ZEVAI_KEY"
+# -> {"status":"done","video":{"url":"https://.../v1/videos/flow_.../content?token=...","duration":10}}
+```
+
+`video.url` carries its own token, so it downloads without the API key: `curl -o video.mp4 "$URL"`.
+
+Long video (10–60 s) with optional per-segment prompts:
+
+```bash
+curl -sS -X POST "$ZEVAI_URL/v1/videos/generations" \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: stable-story-key" \
+  -d '{"model":"flow/omni-flash-long","prompt":"One continuous dolly shot through a space station","duration":30,"aspect_ratio":"16:9",
+       "segment_prompts":["Opening: the camera drifts past docking ports","Middle: crew float through a corridor","End: a window reveals Earth"]}'
+```
+
+ZevaiRouter generates the first segment as text-to-video, extracts its last frame, generates every later segment as I2V, and joins the MP4 streams without re-encoding. It checks the account's credits before accepting the job. Long video needs `ffmpeg` and the connection's **I2V upload consent confirmed** setting.
+
+Prompting tips for Flow: write the shot as real camera footage (lens, light, camera movement) for realism. Describe products and people by their look instead of naming brands or celebrities, which Flow often refuses, and describe new designs in detail because the model may not know them.
+
+## Zevai CLI
+
+```bash
+zevai xai video \
+  --prompt "A cinematic tracking shot through a neon city at night" \
+  --output video.mp4
+```
+
+Useful options include `--model`, `--duration`, `--aspect-ratio`, `--resolution`, `--image`, `--timeout`, `--port`, and `--api-key`.
+
+## Safety and retry behavior
+
+- Flow runs one generation at a time across all accounts; submit one job and wait for it instead of submitting several in parallel.
+- On `failed`, report the error. Do not resubmit with a new `Idempotency-Key` unless the user asks: the clip may already have been billed.
+- HTTP 402: every Flow account is out of credits. HTTP 423: Flow is busy with another render; wait a minute and retry the same request.
+- ZevaiRouter rotates to another account only for failures that cannot have been billed (authentication, credits, Flow refusing the account).
+- xAI: poll using the connection ID returned when the job was created.
+- Video models are separate from chat model lists and chat combos.