zevairouter 1.1.37 → 1.1.39

package/cli/app/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/cli/app/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/cli/app/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/cli/app/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.

package/cli/app/skills/zevai-web-fetch/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: zevairouter-web-fetch
+description: Fetch URL → markdown / text / HTML via ZevaiRouter /v1/web/fetch using Firecrawl / Jina Reader / Tavily Extract / Exa Contents. Use when the user wants to scrape a webpage, extract URL content, read article, or convert a URL to markdown.
+---
+
+# ZevaiRouter — Web Fetch
+
+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/web | jq '.data[] | select(.kind=="webFetch") | .id'
+# Per-provider params
+curl "$ZEVAI_URL/v1/models/info?id=firecrawl/fetch"
+```
+
+IDs end in `/fetch` (e.g. `firecrawl/fetch`, `jina/fetch`). `fetch-combo` chains providers with auto-fallback.
+
+## Endpoint
+
+`POST $ZEVAI_URL/v1/web/fetch`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` (or `provider`) | yes | from `/v1/models/web` (e.g. `firecrawl` or `jina-reader`) |
+| `url` | yes | URL to extract |
+| `format` | no | `markdown` (default) / `text` / `html` |
+| `max_characters` | no | truncate output |
+
+## Examples
+
+### Jina Reader
+```bash
+curl -X POST $ZEVAI_URL/v1/web/fetch \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"jina-reader","url":"http://localhost:1997","format":"markdown"}'
+```
+
+### Exa
+```bash
+curl -X POST $ZEVAI_URL/v1/web/fetch \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"exa","url":"https://example.com","format":"markdown","max_characters":0}'
+```
+
+### Firecrawl
+```bash
+curl -X POST $ZEVAI_URL/v1/web/fetch \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"firecrawl","url":"https://example.com","format":"markdown","max_characters":0}'
+```
+
+### Tavily
+```bash
+curl -X POST $ZEVAI_URL/v1/web/fetch \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"tavily","url":"https://example.com","format":"markdown","max_characters":0}'
+```
+
+
+JS:
+
+```js
+const r = await fetch(`${process.env.ZEVAI_URL}/v1/web/fetch`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.ZEVAI_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "fetch-combo", url: "https://example.com", format: "markdown", max_characters: 5000 }),
+});
+const { data } = await r.json();
+console.log(data.title, data.content.length);
+```
+
+## Response shape
+
+```json
+{
+  "provider": "jina-reader",
+  "url": "...",
+  "title": "...",
+  "content": { "format": "markdown", "text": "...", "length": 1234 },
+  "metadata": { "author": null, "published_at": null, "language": null },
+  "usage": { "fetch_cost_usd": 0 },
+  "metrics": { "response_time_ms": 850, "upstream_latency_ms": 700 }
+}
+```
+
+## Provider quirks
+
+| Provider | Auth | Best for |
+|---|---|---|
+| `firecrawl` | Bearer | JS-rendered pages, `format=markdown/html` |
+| `jina-reader` | Bearer (optional) | Free tier (~1M chars/mo); fastest plain markdown |
+| `tavily` | Bearer | Bulk extract; returns `raw_content` |
+| `exa` | `x-api-key` | Pre-indexed pages; fast text extraction |

package/cli/app/skills/zevai-web-search/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: zevairouter-web-search
+description: Web search via ZevaiRouter /v1/search using Tavily / Exa / Brave / Serper / SearXNG / Google PSE / Linkup / SearchAPI / You.com / Perplexity. Use when the user wants to search the web, look up information, find articles, or query a search engine.
+---
+
+# ZevaiRouter — Web Search
+
+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/web | jq '.data[] | select(.kind=="webSearch") | .id'
+# Per-provider params (searchTypes, maxResults, required options like cx for google-pse)
+curl "$ZEVAI_URL/v1/models/info?id=tavily/search"
+```
+
+IDs end in `/search` (e.g. `tavily/search`). Combos (`owned_by:"combo"`) chain providers with auto-fallback.
+
+## Endpoint
+
+`POST $ZEVAI_URL/v1/search`
+
+| Field | Required | Notes |
+|---|---|---|
+| `model` (or `provider`) | yes | from `/v1/models/web` (e.g. `tavily` or `brave`) |
+| `query` | yes | search query |
+| `max_results` | no | default 5 |
+| `search_type` | no | `web` (default) / `news` |
+| `country`, `language`, `time_range`, `domain_filter` | no | provider-dependent |
+
+## Examples
+
+```bash
+curl -X POST $ZEVAI_URL/v1/search \
+  -H "Authorization: Bearer $ZEVAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"tavily","query":"ZevaiRouter open source","max_results":5}'
+```
+
+JS:
+
+```js
+const r = await fetch(`${process.env.ZEVAI_URL}/v1/search`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.ZEVAI_KEY}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ model: "search-combo", query: "latest LLM benchmarks", max_results: 10 }),
+});
+console.log(await r.json());
+```
+
+## Response shape
+
+```json
+{
+  "provider": "tavily",
+  "query": "ZevaiRouter open source",
+  "results": [
+    {
+      "title": "...", "url": "https://...", "display_url": "github.com/...",
+      "snippet": "...", "position": 1, "score": 0.92,
+      "published_at": null, "favicon_url": null, "content": null,
+      "metadata": { "author": null, "language": null, "source_type": null, "image_url": null },
+      "citation": { "provider": "tavily", "retrieved_at": "2026-...", "rank": 1 }
+    }
+  ],
+  "answer": null,
+  "usage": { "queries_used": 1, "search_cost_usd": 0.008 },
+  "metrics": { "response_time_ms": 850, "upstream_latency_ms": 700, "total_results_available": 12 },
+  "errors": []
+}
+```
+
+## Provider quirks
+
+All accept `query` + `max_results`. Optional fields vary:
+
+| Provider | Supports | Required extras |
+|---|---|---|
+| `tavily` | country, domain_filter, news topic | — |
+| `exa` | domain_filter (incl/excl), news category | — |
+| `brave-search` | country, language | — |
+| `serper` | country, language, news endpoint | — |
+| `perplexity` | country, language, domain_filter | — |
+| `linkup` | domain_filter, time_range | `depth: fast/standard/deep` (option) |
+| `google-pse` | country, language, time_range, offset | **`cx` required** (providerOptions) |
+| `searchapi` | country, language, pagination | — |
+| `youcom` | country, language, time_range, domain_filter, full_page | — |
+| `searxng` | language, time_range | Self-hosted, **noAuth** |
+
+Provider IS the model — `"provider":"tavily" ≡ "model":"tavily"`.

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zevairouter-cli",
-  "version": "1.1.37",
+  "version": "1.1.39",
   "private": true,
   "description": "ZevaiRouter CLI - Start and manage ZevaiRouter server",
   "bin": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zevairouter",
-  "version": "1.1.37",
+  "version": "1.1.39",
   "description": "Self-hosted AI router: many providers, one OpenAI-compatible /v1 endpoint and dashboard",
   "bin": {
     "zevai": "cli/cli.js"
@@ -15,6 +15,7 @@
     "cli/LICENSE",
     "scripts/start-standalone.mjs",
     "scripts/gflow-reply-capture.py",
+    "skills/",
     "README.md",
     "README.zh-CN.md",
     "DOCKER.md",

package/skills/README.md

@@ -0,0 +1,43 @@
+# ZevaiRouter — Agent Skills
+
+Drop-in skills for any AI agent (Claude, Cursor, ChatGPT, custom SDK). Just **copy a link** below and paste it to your AI — it will fetch the skill and use ZevaiRouter for you.
+
+> Tip: start with the **zevairouter** entry skill — it covers setup and links to all capability skills.
+
+## Skills
+
+| Capability | Copy link below and paste to your AI |
+|---|---|
+| **Entry / Setup** (start here) | https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai/SKILL.md |
+| 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 |
+
+## How to use
+
+Paste to your AI (Claude, Cursor, ChatGPT, …):
+
+```
+Read this skill and use it: https://raw.githubusercontent.com/verifiedlabs/zevairouter/refs/heads/main/skills/zevai/SKILL.md
+```
+
+Then ask normally — *"generate an image of a cat"*, *"transcribe this URL"*, etc.
+
+## Configure your shell once
+
+```bash
+export ZEVAI_URL="http://localhost:1997"   # local default, or your VPS / tunnel URL
+export ZEVAI_KEY="sk-..."                   # from Dashboard → Keys (only if requireApiKey=true)
+```
+
+Verify: `curl $ZEVAI_URL/api/health` → `{"ok":true}`.
+
+## Links
+
+- Source: https://github.com/Verifiedlabs/zevairouter
+- Local dashboard: http://localhost:1997/dashboard