@polderlabs/bizar 10.7.1 → 10.7.2

package/.claude/hooks/worker-suggest.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * .claude/hooks/worker-suggest.mjs
+ *
+ * Bizar Background Workers — UserPromptSubmit hook.
+ *
+ * Runs on every user prompt. Calls `dispatch()` from cli/worker-dispatcher.mjs
+ * to find Bizar skills/agents that should be suggested for the prompt text.
+ * Emits suggestions to stderr (stdout is reserved for Claude Code's hook
+ * protocol). Always exits 0 — this is a suggestion, not a gate.
+ *
+ * Claude Code stdin shape (UserPromptSubmit):
+ *   {
+ *     "session_id": "...",
+ *     "transcript_path": "...",
+ *     "cwd": "...",
+ *     "hook_event_name": "UserPromptSubmit",
+ *     "user_prompt": "raw prompt text"
+ *   }
+ *
+ * Claude Code stdout shape (hookSpecificOutput.additionalContext):
+ *   { "hookSpecificOutput": {
+ *       "hookEventName": "UserPromptSubmit",
+ *       "additionalContext": "Bizar workers suggest: …"
+ *   }}
+ *
+ * On any unexpected error: log to stderr, write a no-op hook output,
+ * exit 0. Never block the user.
+ */
+'use strict';
+
+import { dispatch } from '../../cli/worker-dispatcher.mjs';
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  let input = {};
+  try {
+    input = JSON.parse(raw || '{}');
+  } catch {
+    input = {};
+  }
+
+  const prompt = String(input.user_prompt || '').trim();
+
+  // Empty prompts get the silent treatment — the user has not yet
+  // committed any intent.
+  if (prompt.length === 0) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: '',
+      },
+    }) + '\n');
+    process.exit(0);
+    return;
+  }
+
+  let suggestions;
+  try {
+    suggestions = dispatch(prompt, { maxSuggestions: 3 });
+  } catch (err) {
+    process.stderr.write(
+      `[bizar.workers] WARN: dispatch failed: ${
+        err && err.message ? err.message : String(err)
+      }\n`,
+    );
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: '',
+      },
+    }) + '\n');
+    process.exit(0);
+    return;
+  }
+
+  // Emit one stderr line per suggestion (for operator visibility in logs).
+  for (const s of suggestions) {
+    const skill = s.skill ? `skill: ${s.skill}` : 'skill: (none)';
+    const agent = s.agent ? `, agent: ${s.agent}` : '';
+    process.stderr.write(
+      `[bizar.workers] suggested: ${s.workerId} (${skill}${agent}) via pattern "${s.matchedPattern}"\n`,
+    );
+  }
+
+  // Build additionalContext for the model so the next turn is primed.
+  let note;
+  if (suggestions.length === 0) {
+    note = '';
+  } else {
+    const lines = suggestions.map((s) => {
+      const skillPart = s.skill ? `, skill=${s.skill}` : '';
+      const agentPart = s.agent ? `, agent=${s.agent}` : '';
+      return `- ${s.workerId} (weight=${s.weight}${skillPart}${agentPart}) matched "${s.matchedPattern}"`;
+    });
+    note =
+      'Bizar workers suggest the following skills/agents for this prompt:\n' +
+      lines.join('\n');
+  }
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: note,
+    },
+  }) + '\n');
+  process.exit(0);
+});

package/.claude/settings.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "mcpServers": {
+    "bizar": {
+      "command": "npx",
+      "args": ["-y", "@polderlabs/bizar-sdk", "mcp"],
+      "env": {
+        "BIZAR_HOME": "${HOME}/.bizar_home",
+        "BIZAR_MEMORY_VAULT": "${HOME}/.bizar_home/memory"
+      }
+    },
+    "semble": {
+      "command": "semble",
+      "args": ["mcp"]
+    },
+    "kevin": {
+      "command": "kevin",
+      "args": ["mcp"]
+    }
+  },
+  "permissions": {
+    "allow": [
+      "mcp__bizar__memory_read",
+      "mcp__bizar__memory_list",
+      "mcp__bizar__memory_search",
+      "mcp__bizar__memory_write",
+      "mcp__bizar__plan_action",
+      "mcp__bizar__open_kb",
+      "mcp__bizar__loop_list",
+      "mcp__bizar__loop_status",
+      "mcp__bizar__loop_start",
+      "mcp__bizar__loop_stop",
+      "mcp__bizar__graph_query",
+      "mcp__bizar__graph_path",
+      "mcp__bizar__danger_check",
+      "Read(~/.bizar_memory/**)",
+      "mcp__semble__*",
+      "mcp__agent-browser__*"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./secrets/**)",
+      "Bash(rm -rf /)",
+      "Bash(sudo *)"
+    ]
+  },
+  "env": {
+    "BIZAR_HOME": "${HOME}/.bizar_home",
+    "BIZAR_MEMORY_VAULT": "${HOME}/.bizar_home/memory",
+    "BIZAR_LOOPS_DIR": "${HOME}/.bizar_loops",
+    "ANTHROPIC_BASE_URL": "http://localhost:20128/v1",
+    "BIZAR_MODEL_ROUTER_URL": "http://localhost:20128/v1"
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /home/drb0rk/projects/BizarHarness/.claude/hooks/pretooluse-editwrite.mjs",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /home/drb0rk/projects/BizarHarness/.claude/hooks/pretooluse-bash.mjs",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /home/drb0rk/projects/BizarHarness/.claude/hooks/posttooluse-editwrite.mjs",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash /home/drb0rk/projects/BizarHarness/.claude/hooks/auto-instinct.sh",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git push*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash /home/drb0rk/projects/BizarHarness/.claude/hooks/post-merge-audit.sh",
+            "timeout": 60
+          }
+        ]
+      },
+      {
+        "matcher": "EnterWorktree",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash /home/drb0rk/projects/BizarHarness/scripts/worktree-setup.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /home/drb0rk/projects/BizarHarness/.claude/hooks/worker-suggest.mjs",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /home/drb0rk/projects/BizarHarness/.claude/hooks/thinking-route.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /home/drb0rk/projects/BizarHarness/.claude/hooks/sessionstart-prime.mjs",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /home/drb0rk/projects/BizarHarness/.claude/hooks/sessionend-recall.mjs",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "node /home/drb0rk/projects/BizarHarness/.claude/hooks/learning-extract.mjs",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/9router/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: 9router
+description: Entry point for 9Router — local/remote AI gateway with OpenAI-compatible REST for chat, image, TTS, STT, embeddings, web search, web fetch. Use when the user mentions 9Router, NINEROUTER_URL, or wants AI without writing provider boilerplate. This skill covers setup + indexes capability skills; fetch the relevant capability SKILL.md from the URLs below when needed.
+---
+
+# 9Router
+
+Local/remote AI gateway exposing OpenAI-compatible REST. One key, many providers, auto-fallback.
+
+## Setup
+
+The Bizar harness expects 9Router at `http://localhost:20128` by default. Override with:
+
+```bash
+export NINEROUTER_URL="http://localhost:20128"      # or VPS / tunnel URL
+export NINEROUTER_KEY="sk-..."                      # from Dashboard → Keys (only if requireApiKey=true)
+```
+
+All requests: `${NINEROUTER_URL}/v1/...` with header `Authorization: Bearer ${NINEROUTER_KEY}` (omit if auth disabled).
+
+Verify: `curl $NINEROUTER_URL/api/health` → `{"ok":true}`
+
+## Discover models
+
+```bash
+curl $NINEROUTER_URL/v1/models                  # chat/LLM (default)
+curl $NINEROUTER_URL/v1/models/image            # image-gen
+curl $NINEROUTER_URL/v1/models/tts              # text-to-speech
+curl $NINEROUTER_URL/v1/models/embedding        # embeddings
+curl $NINEROUTER_URL/v1/models/web              # web search + fetch (entries have `kind` field)
+curl $NINEROUTER_URL/v1/models/stt              # speech-to-text
+curl $NINEROUTER_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/decolua/9router/refs/heads/master/skills/9router-chat/SKILL.md |
+| Image generation | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-image/SKILL.md |
+| Text-to-speech | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-tts/SKILL.md |
+| Speech-to-text | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-stt/SKILL.md |
+| Embeddings | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-embeddings/SKILL.md |
+| Web search | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-web-search/SKILL.md |
+| Web fetch (URL → markdown) | https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router-web-fetch/SKILL.md |
+
+## Bizar harness integration
+
+This skill is auto-installed by `bizar install` into `~/.claude/skills/9router/`. All
+Bizar agents that need chat or web capabilities should read these skill files
+before starting a task.
+
+**Quick-check command** (run from anywhere in a Bizar session):
+
+```bash
+curl -sS http://localhost:20128/api/health
+```
+
+If the response is not `{"ok":true}`, ask the user whether 9Router is running
+or whether `NINEROUTER_URL` should be re-pointed. Do NOT fall back to a
+non-routed provider silently — the whole point of 9Router is auto-fallback +
+single key rotation + observability.
+
+## Errors
+
+- 401 → set/refresh `NINEROUTER_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/.claude/skills/9router-chat/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: 9router-chat
+description: Chat / code generation via 9Router 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 9Router.
+---
+
+# 9Router — Chat
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Endpoints
+
+- `POST $NINEROUTER_URL/v1/chat/completions` — OpenAI format
+- `POST $NINEROUTER_URL/v1/messages` — Anthropic format
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models | jq '.data[].id'
+# Per-model metadata (contextWindow, params)
+curl "$NINEROUTER_URL/v1/models/info?id=openai/gpt-4o"
+```
+
+Combos (e.g. `vip`, `mycodex`) auto-fallback through multiple providers.
+
+## OpenAI format
+
+```bash
+curl -X POST $NINEROUTER_URL/v1/chat/completions \
+  -H "Authorization: Bearer $NINEROUTER_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.NINEROUTER_URL}/v1`, apiKey: process.env.NINEROUTER_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 $NINEROUTER_URL/v1/messages \
+  -H "Authorization: Bearer $NINEROUTER_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/.claude/skills/9router-embeddings/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: 9router-embeddings
+description: Generate vector embeddings via 9Router /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.
+---
+
+# 9Router — Embeddings
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models/embedding | jq '.data[].id'
+# Per-model dimensions
+curl "$NINEROUTER_URL/v1/models/info?id=openai/text-embedding-3-small"
+```
+
+## Endpoint
+
+`POST $NINEROUTER_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 $NINEROUTER_URL/v1/embeddings \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/text-embedding-3-small","input":["hello","world"]}'
+```
+
+JS:
+
+```js
+const r = await fetch(`${process.env.NINEROUTER_URL}/v1/embeddings`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_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/.claude/skills/9router-image/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: 9router-image
+description: Generate images via 9Router /v1/images/generations using 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).
+---
+
+# 9Router — Image Generation
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models/image | jq '.data[].id'
+# Per-model params/options (size enum, quality enum, capabilities like edit)
+curl "$NINEROUTER_URL/v1/models/info?id=openai/dall-e-3"
+```
+
+## Endpoint
+
+`POST $NINEROUTER_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 "$NINEROUTER_URL/v1/images/generations?response_format=binary" \
+  -H "Authorization: Bearer $NINEROUTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gemini/gemini-3-pro-image-preview","prompt":"watercolor mountains at sunrise","size":"1024x1024"}' \
+  --output out.png
+```
+
+JS (URL response):
+
+```js
+const r = await fetch(`${process.env.NINEROUTER_URL}/v1/images/generations`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_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`) |

package/.claude/skills/9router-stt/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: 9router-stt
+description: Speech-to-text via 9Router /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.
+---
+
+# 9Router — Speech-to-Text
+
+Requires `NINEROUTER_URL` (and `NINEROUTER_KEY` if auth enabled). See https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md for setup.
+
+## Discover
+
+```bash
+curl $NINEROUTER_URL/v1/models/stt | jq '.data[].id'
+# Per-model params (language, response_format, prompt, temperature support)
+curl "$NINEROUTER_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 $NINEROUTER_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 "$NINEROUTER_URL/v1/audio/transcriptions" \
+  -H "Authorization: Bearer $NINEROUTER_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.NINEROUTER_URL}/v1/audio/transcriptions`, {
+  method: "POST",
+  headers: { "Authorization": `Bearer ${process.env.NINEROUTER_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 |