
openrouter
Skills for the OpenRouter platform
- GitHub stars
- 326
Install
/plugin install openrouter@openrouterRun it inside Claude Code after adding the marketplace with /plugin marketplace add OpenRouterTeam/skills.
Contents
Discovered from sourceSkills 18
Create Agent TUI
Scaffolds a complete agent TUI in TypeScript targeting OpenRouter. The generated project uses @openrouter/agent for the inner loop (model calls, tool execution, stop conditions) and provides the outer shell: a customizable terminal interface, configuration, session management, tool definitions, and an entry point.
Architecture draws from three production agent systems:
- pi-mono/coding-agent — three-layer separation, JSONL sessions, pluggable tool operations
- Claude Code — tool metadata (read-only, destructive, approval), system prompt composition
- Codex CLI — layered config, approval flow with session caching, structured logging
Prerequisites
- Node.js 18+
OPENROUTER_API_KEYfrom openrouter.ai/settings/keys- For full SDK reference, see the
openrouter-typescript-sdkskill
Decision Tree
| User wants to... | Action |
|---|---|
| Build a new agent from scratch | Present checklist below → follow Generation Workflow |
| Add tools to an existing harness | Read references/tools.md, present tool checklist only |
| Add a harness module | Read references/modules.md, generate the module |
| Add an API server entry point | Read references/server-entry-points.md |
Interactive Tool Checklist
Present this as a multi-select checklist. Items marked ON are pre-selected defaults.
OpenRouter Server Tools (server-side, zero implementation)
| Tool | Type string | Default | Config |
|---|---|---|---|
| Web Search | openrouter:web_search | ON | engine, max_results, domain filtering |
| Datetime | openrouter:datetime | ON | timezone |
| Image Generation | openrouter:image_generation | OFF | model, quality, size, format |
Server tools go in the tools array alongside user-defined tools. No client code needed — OpenRouter executes them.
User-Defined Tools (client-side, generated into src/tools/)
| Tool | Default | Description |
|---|---|---|
| File Read | ON | Read files with offset/limit, detect images |
| File Write | ON | Write/create files, auto-create directories |
| File Edit | ON | Search-and-replace with diff validation |
| Glob/Find | ON | File discovery by glob pattern |
| Grep/Search | ON | Content search by regex |
| Directory List | ON | List directory contents |
| Shell/Bash | ON | Execute commands with timeout and output capture; asks the user before each command |
| JS REPL | OFF | Persistent Node.js environment |
| Sub-agent Spawn | OFF | Delegate tasks to child agents |
| Plan/Todo | OFF | Track multi-step task progress |
| Request User Input | OFF | Structured multiple-choice questions |
| Web Fetch | OFF | Fetch and extract text from web pages |
| View Image | OFF | Read local images as base64 |
| Custom Tool Template | ON | Empty skeleton for domain-specific tools |
Harness Modules (architectural components)
| Module | Default | Description |
|---|---|---|
| Session Persistence | ON | JSONL append-only conversation log |
| ASCII Logo Banner | OFF | Custom ASCII art banner on startup — ask for project name |
| Context Compaction | OFF | Summarize older messages when context is long |
| System Prompt Composition | OFF | Assemble instructions from static + dynamic context |
| Tool Permissions / Approval | OFF | Gate other dangerous tools behind user confirmation (the shell tool always asks) |
| Structured Event Logging | OFF | Emit events for tool calls, API requests, errors |
@-file References | OFF | @filename to attach file content to next message |
! Shell Shortcut | OFF | !command to run shell and inject output into context |
| Multi-line Input | OFF | Shift+Enter for multi-line (requires raw terminal mode) |
Slash Commands (user-facing REPL commands)
| Command | Default | Description |
|---|---|---|
/model | ON | Switch model via OpenRouter API |
/new | ON | Start a fresh conversation |
/help | ON | List available commands |
/compact | OFF | Manually trigger context compaction |
/session | OFF | Show session metadata and token usage |
/export | OFF | Save conversation as Markdown |
When slash commands are enabled, generate src/commands.ts with a command registry. See references/slash-commands.md for specs.
Visual Customization (present as single-select for each)
Input style — how the prompt looks. See references/input-styles.md:
| Style | Default | Description |
|---|---|---|
block | ON | Full-width background box with › prompt, adapts to terminal theme |
bordered | Horizontal ─ lines above and below input | |
plain | Simple > readline prompt, no escape sequences | |
| Other | User describes what they want — implement a custom input style |
Tool display — how tool calls appear during execution. See references/tool-display.md:
| Style | Default | Description |
|---|---|---|
grouped | ON | Bold action labels with tree-branch output |
emoji | Per-call ⚡/✓ markers with args and timing | |
minimal | Aggregated one-liner summaries | |
hidden | No tool output | |
| Other | User describes what they want — implement a custom display |
Loader animation — shown while waiting for model response. See references/loader.md:
| Style | Default | Description |
|---|---|---|
spinner | ON | Braille dot spinner (⠋⠙⠹…) to the left of the text |
gradient | Scrolling color shimmer over the loader text | |
minimal | Trailing dots (Working···) | |
| Other | User describes what they want — implement a custom animation |
Also ask for the loader text (default: "Working").
Generation Workflow
After getting checklist selections, follow this workflow:
- [ ] Generate package.json with dependencies
- [ ] Generate src/config.ts (add showBanner field if ASCII Logo Banner is ON)
- [ ] Generate src/tools/index.ts wiring selected tools + server tools
- [ ] Generate selected tool files in src/tools/ (see Tool Pattern below, specs in references/tools.md)
- [ ] Generate src/agent.ts (core runner)
- [ ] Generate selected harness modules (specs in references/modules.md)
- [ ] Generate src/terminal-bg.ts (adaptive input background — see references/tui.md)
- [ ] Generate input style functions in src/cli.ts (block/bordered/plain — see references/input-styles.md)
- [ ] Generate src/renderer.ts (tool display — see references/tool-display.md)
- [ ] Generate src/loader.ts (loader animation — see references/loader.md)
- [ ] If slash commands selected: generate src/commands.ts (see references/slash-commands.md)
- [ ] If ASCII Logo Banner is ON: generate src/banner.ts (see ASCII Logo Banner section below)
- [ ] Generate src/cli.ts entry point (or src/server.ts — see references/server-entry-points.md)
- [ ] Generate .env.example with OPENROUTER_API_KEY=
- [ ] Verify: run npx tsc --noEmit to check types
Tool Pattern
All user-defined tools follow this pattern using @openrouter/agent/tool. Here is one complete example — all other tools in references/tools.md follow the same shape:
import { tool } from '@openrouter/agent/tool';
import { z } from 'zod';
import { readFile, stat } from 'fs/promises';
const DEFAULT_LINE_LIMIT = 2000;
const MAX_LINE_CHARS = 2000;
export const fileReadTool = tool({
name: 'file_read',
description:
'Read the contents of a file. Output is capped at 2000 lines by default (use offset/limit to paginate) and any line longer than 2000 characters is truncated. When the response is truncated, the hint field tells you how to continue.',
inputSchema: z.object({
path: z.string().describe('Absolute path to the file'),
offset: z.number().optional().describe('Start reading from this line (1-indexed)'),
limit: z.number().optional().describe(`Maximum lines to return (default ${DEFAULT_LINE_LIMIT})`),
}),
execute: async ({ path, offset, limit }) => {
try {
const content = await readFile(path, 'utf-8');
const lines = content.split('\n');
const start = offset ? offset - 1 : 0;
const end = Math.min(start + (limit ?? DEFAULT_LINE_LIMIT), lines.length);
let longLines = 0;
const slice = lines.slice(start, end).map((line) => {
if (line.length <= MAX_LINE_CHARS) return line;
longLines++;
return line.slice(0, MAX_LINE_CHARS) + `… [line truncated, ${line.length - MAX_LINE_CHARS} chars dropped]`;
});
const tailTruncated = end < lines.length;
const truncated = tailTruncated || longLines > 0;
const hintParts: string[] = [`Showing lines ${start + 1}-${end} of ${lines.length}.`];
if (tailTruncated) hintParts.push(`Use offset=${end + 1} to continue.`);
if (longLines > 0) hintParts.push(`${longLines} line(s) exceeded ${MAX_LINE_CHARS} chars and were per-line truncated; use grep to fetch content from those lines.`);
return {
content: slice.join('\n'),
totalLines: lines.length,
...(truncated && {
truncated: true,
...(tailTruncated && { nextOffset: end + 1 }),
hint: hintParts.join(' '),
}),
};
} catch (err: any) {
if (err.code === 'ENOENT') return { error: `File not found: ${path}` };
if (err.code === 'EACCES') return { error: `Permission denied: ${path}` };
return { error: err.message };
}
},
});
For specs of all other tools, see references/tools.md.
Core Files
These files are always generated. The agent adapts them based on checklist selections.
package.json
Initialize the project and install dependencies at their latest versions:
npm init -y
npm pkg set type=module
npm pkg set scripts.start="tsx src/cli.ts"
npm pkg set scripts.dev="tsx watch src/cli.ts"
npm install @openrouter/agent glob zod
npm install -D tsx typescript @types/node
tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "dist",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true
},
"include": ["src"]
}
src/config.ts
import { readFileSync, existsSync } from 'fs';
import { homedir } from 'os';
import { join, resolve } from 'path';
// Use the agent's package name, so each agent gets its own ~/.config/<name>/ directory.
const APP_NAME = 'my-agent';
function positiveNumber(name: string, raw: string | number): number {
const n = Number(raw);
if (!Number.isFinite(n) || n <= 0) {
throw new Error(`${name} must be a positive number, got: ${JSON.stringify(raw)}`);
}
return n;
}
export interface DisplayConfig {
toolDisplay: 'emoji' | 'grouped' | 'minimal' | 'hidden';
reasoning: boolean;
inputStyle: 'block' | 'bordered' | 'plain';
}
export interface AgentConfig {
apiKey: string;
model: string;
systemPrompt: string;
maxSteps: number;
maxCost: number;
sessionDir: string;
showBanner: boolean;
display: DisplayConfig;
slashCommands: boolean;
}
const DEFAULTS: AgentConfig = {
apiKey: '',
model: 'anthropic/claude-opus-4.7',
systemPrompt: [
'You are a coding assistant with access to tools for reading, writing, editing, and searching files, and running shell commands.',
'',
'Current working directory: {cwd}',
'',
'Guidelines:',
'- Use your tools proactively. Explore the codebase to find answers instead of asking the user.',
'- Keep working until the task is fully resolved before responding.',
'- Do not guess or make up information — use your tools to verify.',
'- Be concise and direct.',
'- Show file paths clearly when working with files.',
'- Prefer grep and glob tools over shell commands for file search.',
'- When editing code, make minimal targeted changes consistent with the existing style.',
].join('\n'),
maxSteps: 20,
maxCost: 1.0,
sessionDir: '.sessions',
showBanner: false,
display: { toolDisplay: 'grouped', reasoning: false, inputStyle: 'block' },
slashCommands: true,
};
type FieldType = 'string' | 'number' | 'boolean' | readonly string[];
// Fields a config file may set, and their types. apiKey is env-only so it never sits in a file.
const FILE_FIELDS: Record<string, FieldType> = {
model: 'string',
systemPrompt: 'string',
maxSteps: 'number',
maxCost: 'number',
sessionDir: 'string',
showBanner: 'boolean',
slashCommands: 'boolean',
};
const DISPLAY_FIELDS: Record<string, FieldType> = {
toolDisplay: ['emoji', 'grouped', 'minimal', 'hidden'],
reasoning: 'boolean',
inputStyle: ['block', 'bordered', 'plain'],
};
/**
* The config file is read from an explicit path (--config or AGENT_CONFIG) or the user's
* config directory, never from the working directory: a cloned repo could otherwise ship
* an agent.config.json that replaces the system prompt and lifts the cost and step limits.
*/
export function resolveConfigPath(explicit?: string): { path: string; required: boolean } {
const chosen = explicit || process.env.AGENT_CONFIG;
if (chosen) return { path: resolve(chosen), required: true };
const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
return { path: join(base, APP_NAME, 'agent.config.json'), required: false };
}
function isObject(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
function pick(where: string, raw: unknown, fields: Record<string, FieldType>): Record<string, unknown> {
if (!isObject(raw)) throw new Error(`${where} must be a JSON object`);
const out: Record<string, unknown> = {};
for (const [key, value] of Object.entries(raw)) {
const type = fields[key];
if (!type) throw new Error(`${where}: unsupported field "${key}"`);
if (Array.isArray(type)) {
if (!type.includes(value as string)) throw new Error(`${where}: "${key}" must be one of ${type.join(', ')}`);
} else if (typeof value !== type) {
throw new Error(`${where}: "${key}" must be a ${type}`);
}
out[key] = type === 'number' ? positiveNumber(`${where}: ${key}`, value as number) : value;
}
return out;
}
function readConfigFile(path: string, required: boolean): Record<string, any> {
if (!existsSync(path)) {
if (required) throw new Error(`Config file not found: ${path}`);
return {};
}
const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'));
if (!isObject(raw)) throw new Error(`${path} must contain a JSON object`);
const { display, ...rest } = raw;
const out: Record<string, any> = pick(path, rest, FILE_FIELDS);
if (display !== undefined) {
if (!isObject(display)) throw new Error(`${path}: "display" must be a JSON object`);
out.display = pick(`${path}: display`, display, DISPLAY_FIELDS);
}
return out;
}
export function loadConfig(
overrides: Partial<AgentConfig> = {},
opts?: { skipApiKey?: boolean; configPath?: string },
): AgentConfig {
let config = { ...DEFAULTS };
const { path, required } = resolveConfigPath(opts?.configPath);
const file = readConfigFile(path, required);
if (file.display) {
config.display = {
...config.display,
...file.display,
};
}
config = { ...config, ...file, display: config.display };
if (process.env.OPENROUTER_API_KEY) config.apiKey = process.env.OPENROUTER_API_KEY;
if (process.env.AGENT_MODEL) config.model = process.env.AGENT_MODEL;
if (process.env.AGENT_MAX_STEPS) config.maxSteps = positiveNumber('AGENT_MAX_STEPS', process.env.AGENT_MAX_STEPS);
if (process.env.AGENT_MAX_COST) config.maxCost = positiveNumber('AGENT_MAX_COST', process.env.AGENT_MAX_COST);
if (overrides.display) {
config.display = { ...config.display, ...overrides.display };
}
config = { ...config, ...overrides, display: config.display };
if (!config.apiKey && !opts?.skipApiKey) throw new Error('OPENROUTER_API_KEY is required.');
return config;
}
src/tools/index.ts
Adapt imports based on checklist selections. This example includes all default-ON tools:
import { serverTool } from '@openrouter/agent';
import { fileReadTool } from './file-read.js';
import { fileWriteTool } from './file-write.js';
import { fileEditTool } from './file-edit.js';
import { globTool } from './glob.js';
import { grepTool } from './grep.js';
import { listDirTool } from './list-dir.js';
import { shellTool } from './shell.js';
export const tools = [
// User-defined tools — executed client-side
fileReadTool,
fileWriteTool,
fileEditTool,
globTool,
grepTool,
listDirTool,
shellTool,
// Server tools — executed by OpenRouter, no client implementation needed
serverTool({ type: 'openrouter:web_search' }),
serverTool({ type: 'openrouter:datetime', parameters: { timezone: 'UTC' } }),
];
src/agent.ts
import { OpenRouter } from '@openrouter/agent';
import type { Item } from '@openrouter/agent';
import { stepCountIs, maxCost } from '@openrouter/agent/stop-conditions';
import type { AgentConfig } from './config.js';
import { tools } from './tools/index.js';
export type ChatMessage = { role: 'user' | 'assistant' | 'system'; content: string };
export type AgentEvent =
| { type: 'text'; delta: string }
| { type: 'tool_call'; name: string; callId: string; args: Record<string, unknown> }
| { type: 'tool_result'; name: string; callId: string; output: string }
| { type: 'reasoning'; delta: string };
export async function runAgent(
config: AgentConfig,
input: string | ChatMessage[],
options?: { onEvent?: (event: AgentEvent) => void; signal?: AbortSignal },
) {
const client = new OpenRouter({ apiKey: config.apiKey });
const result = client.callModel({
model: config.model,
instructions: config.systemPrompt.replace('{cwd}', process.cwd()),
input: input as string | Item[],
tools,
stopWhen: [stepCountIs(config.maxSteps), maxCost(config.maxCost)],
});
if (options?.onEvent) {
// Track text length PER message item by id. A multi-step agent emits
// multiple OutputMessage items over the course of a single run (one per
// assistant turn between tool calls), and each one grows from 0 to its
// final length. A single global cursor breaks on the second message:
// when its length is smaller than the cursor from the first, the slice
// cuts mid-string and drops the start of the new message's text.
const textByItem = new Map<string, number>();
const callNames = new Map<string, string>();
for await (const item of result.getItemsStream()) {
if (options?.signal?.aborted) break;
if (item.type === 'message') {
const text = item.content
?.filter((c): c is { type: 'output_text'; text: string } => 'text' in c)
.map((c) => c.text)
.join('') ?? '';
const prev = textByItem.get(item.id) ?? 0;
if (text.length > prev) {
options.onEvent({ type: 'text', delta: text.slice(prev) });
textByItem.set(item.id, text.length);
}
} else if (item.type === 'function_call') {
callNames.set(item.callId, item.name);
if (item.status === 'completed') {
const args = (() => { try { return item.arguments ? JSON.parse(item.arguments) : {}; } catch { return {}; } })();
options.onEvent({ type: 'tool_call', name: item.name, callId: item.callId, args });
}
} else if (item.type === 'function_call_output') {
const out = typeof item.output === 'string' ? item.output : JSON.stringify(item.output);
options.onEvent({
type: 'tool_result',
name: callNames.get(item.callId) ?? 'unknown',
callId: item.callId,
output: out.length > 200 ? out.slice(0, 200) + '…' : out,
});
} else if (item.type === 'reasoning') {
const text = item.summary?.map((s: { text: string }) => s.text).join('') ?? '';
if (text) options.onEvent({ type: 'reasoning', delta: text });
}
}
}
const response = await result.getResponse();
return { text: response.outputText ?? '', usage: response.usage, output: response.output };
}
export async function runAgentWithRetry(
config: AgentConfig,
input: string | ChatMessage[],
options?: { onEvent?: (event: AgentEvent) => void; signal?: AbortSignal; maxRetries?: number },
) {
for (let attempt = 0, max = options?.maxRetries ?? 3; attempt <= max; attempt++) {
try { return await runAgent(config, input, options); }
catch (err: any) {
const s = err?.status ?? err?.statusCode;
if (!(s === 429 || (s >= 500 && s < 600)) || attempt === max) throw err;
await new Promise((r) => setTimeout(r, Math.min(1000 * 2 ** attempt, 30000)));
}
}
throw new Error('Unreachable');
}
src/cli.ts
Three input styles are supported: block (background box), bordered (horizontal lines), and plain (simple caret). See references/input-styles.md for full implementations of styledReadLine(), borderedReadLine(), and the getInput() dispatcher.
import { createInterface } from 'readline';
import { loadConfig } from './config.js';
import { runAgentWithRetry, type AgentEvent } from './agent.js';
import { detectBg } from './terminal-bg.js';
import { setShellApprover } from './tools/shell.js';
// import { styledReadLine, borderedReadLine } from ... — see references/input-styles.md
const DIM = '\x1b[2m';
const RESET = '\x1b[0m';
const BOLD = '\x1b[1m';
const CYAN = '\x1b[36m';
const GREEN = '\x1b[32m';
const YELLOW = '\x1b[33m';
const GRAY = '\x1b[90m';
function formatTokens(n: number): string {
return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
}
function summarizeArgs(name: string, args: Record<string, unknown>): string {
const key = { shell: 'command', file_read: 'path', file_write: 'path',
file_edit: 'path', glob: 'pattern', grep: 'pattern', web_search: 'query',
}[name] ?? Object.keys(args)[0];
if (!key || !(key in args)) return '';
const val = String(args[key]);
return `${key}=${val.length > 40 ? val.slice(0, 40) + '…' : val}`;
}
async function main() {
const configFlag = process.argv.indexOf('--config');
const configPath = configFlag !== -1 ? process.argv[configFlag + 1] : undefined;
if (configFlag !== -1 && (!configPath || configPath.startsWith('--'))) throw new Error('--config requires a file path');
const config = loadConfig({}, { configPath });
const BG_INPUT = config.display.inputStyle === 'block' ? await detectBg() : '';
// Banner
const width = Math.min(process.stdout.columns || 60, 60);
const line = GRAY + '─'.repeat(width) + RESET;
console.log(`\n${line}`);
console.log(` ${BOLD}My Agent${RESET} ${DIM}v0.1.0${RESET}`);
console.log(` ${DIM}model${RESET} ${CYAN}${config.model}${RESET}`);
if (config.slashCommands) console.log(` ${DIM}/model to change${RESET}`);
console.log(`${line}\n`);
const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: `${GREEN}>${RESET} ` });
// Files and web results the agent reads can carry injected instructions, so
// the shell tool asks before every command (its default approver declines).
// Prompts are chained so parallel tool calls ask one at a time; no TTY declines.
let approving = false;
let approvalQueue: Promise<unknown> = Promise.resolve();
setShellApprover((command) => {
if (!process.stdin.isTTY) return Promise.resolve(false);
const ask = approvalQueue.then(async () => {
approving = true;
process.stdout.write('\r\x1b[K');
process.stdin.resume();
const answer = await new Promise<string>((r) =>
rl.question(`${YELLOW} Run shell command?${RESET}\n ${BOLD}$ ${command}${RESET}\n ${DIM}[y/N]${RESET} `, r));
approving = false;
return answer.trim().toLowerCase() === 'y';
});
approvalQueue = ask.catch(() => {});
return ask;
});
async function getInput(): Promise<string> {
switch (config.display.inputStyle) {
case 'block': return styledReadLine(BG_INPUT);
case 'bordered': return borderedReadLine();
case 'plain':
default:
return new Promise((r) => { rl.prompt(); rl.once('line', r); });
}
}
while (true) {
const input = await getInput();
const trimmed = input.trim();
if (!trimmed) continue;
if (config.display.inputStyle !== 'plain') {
const cwd = process.cwd().replace(process.env.HOME ?? '', '~');
process.stdout.write(`\x1b[K ${DIM}${cwd}${RESET}\n`);
}
if (trimmed.toLowerCase() === 'exit') { process.exit(0); }
console.log();
let streaming = false, started = false;
const toolStart = new Map<string, number>();
const dots = ['·', '··', '···'];
let di = 0;
const spin = setInterval(() => {
if (!started && !approving) process.stdout.write(`\r${DIM}${dots[di++ % 3]}${RESET}`);
}, 300);
const handleEvent = (event: AgentEvent) => {
if (!started) { started = true; process.stdout.write('\r\x1b[K'); }
if (event.type === 'text') { streaming = true; process.stdout.write(event.delta); }
else if (event.type === 'tool_call') {
if (streaming) { process.stdout.write('\n'); streaming = false; }
toolStart.set(event.callId, Date.now());
const args = summarizeArgs(event.name, event.args);
console.log(` ${YELLOW}⚡${RESET} ${DIM}${event.name}${args ? ' ' + args : ''}${RESET}`);
} else if (event.type === 'tool_result') {
const ms = Date.now() - (toolStart.get(event.callId) ?? Date.now());
console.log(` ${GREEN}✓${RESET} ${DIM}${event.name} (${(ms / 1000).toFixed(1)}s)${RESET}`);
started = false;
}
};
try {
const result = await runAgentWithRetry(config, trimmed, { onEvent: handleEvent });
clearInterval(spin);
if (streaming) process.stdout.write(RESET);
const inT = result.usage?.inputTokens ?? 0;
const outT = result.usage?.outputTokens ?? 0;
console.log(`\n${GRAY} ${formatTokens(inT)} in · ${formatTokens(outT)} out${RESET}\n`);
} catch (err: any) {
clearInterval(spin);
if (streaming) process.stdout.write(RESET);
console.log(`\n${YELLOW} Error: ${err.message}${RESET}\n`);
}
}
}
main();
ASCII Logo Banner
When ASCII Logo Banner is selected, ask the user for their project name, then generate src/banner.ts with ASCII art of that name. Use a block-letter style with the █ character for the art. The banner should fit in a 60-column terminal.
src/banner.ts
Generate ASCII art for the user's project name. Example for a project called "ACME":
const RESET = '\x1b[0m';
const BOLD = '\x1b[1m';
const DIM = '\x1b[2m';
const CYAN = '\x1b[36m';
const LOGO = `
█████╗ ██████╗███╗ ███╗███████╗
██╔══██╗██╔════╝████╗ ████║██╔════╝
███████║██║ ██╔████╔██║█████╗
██╔══██║██║ ██║╚██╔╝██║██╔══╝
██║ ██║╚██████╗██║ ╚═╝ ██║███████╗
╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚══════╝`;
export function printBanner(model: string): void {
console.log(CYAN + BOLD + LOGO + RESET);
console.log(` ${DIM}model ${RESET}${model}\n`);
}
Adapt the ASCII art to the user's actual project name. Keep it to one or two short words that fit in 60 columns.
Wire into src/cli.ts
Add at the top of main(), before the text banner, when showBanner is selected:
import { printBanner } from './banner.js';
// In main(), replace the text banner with:
if (config.showBanner) {
printBanner(config.model);
} else {
// fall back to the text banner from the cli.ts template above
}
Add showBanner: boolean to AgentConfig (default false). Enable via ~/.config/<agent-name>/agent.config.json (or the file passed with --config / AGENT_CONFIG) or loadConfig({ showBanner: true }).
Reference Files
For content beyond the core files:
- references/tools.md — Specs for all user-defined tools: file-read, file-write, file-edit, glob, grep, list-dir, shell, js-repl, sub-agent, plan, request-input, web-fetch, view-image, custom template
- references/modules.md — Harness modules: session persistence, context compaction, system prompt composition, tool approval, structured logging
- references/tui.md — Terminal background detection, adaptive input background
- references/tool-display.md — Tool display styles: emoji, grouped, minimal; TuiRenderer class, per-tool colors, formatters
- references/input-styles.md — Input styles: block (background box), bordered (horizontal lines), plain (simple caret)
- references/loader.md — Loader animations: gradient (scrolling shimmer), spinner (braille dots), minimal (trailing dots)
- references/slash-commands.md — Slash command registry: /model, /new, /help, /compact, /session, /export
- references/system-prompt.md — Default system prompt, buildSystemPrompt(), customization guide
- references/server-entry-points.md — Express/Hono API server entry point with SSE streaming, plus extension points (MCP, WebSocket, dynamic models)
Create Headless Agent
Scaffolds a headless agent in TypeScript targeting OpenRouter. The generated project uses @openrouter/agent for the inner loop (model calls, tool execution, stop conditions) and provides a clean programmatic shell: configuration, session management, tool definitions, and one or more entry points (CLI, HTTP server, MCP server, or library import). No terminal UI, no readline, no ANSI — just input in, result out.
Prerequisites
- Bun 1.1+
OPENROUTER_API_KEYfrom openrouter.ai/settings/keys- For full SDK reference, see the
openrouter-typescript-sdkskill
Decision Tree
| User wants to... | Action |
|---|---|
| Build a new headless agent | Present checklist below, follow Generation Workflow |
| Add tools to an existing agent | Read references/tools.md, present tool checklist only |
| Add a module | Read references/modules.md, generate the module |
| Add an entry point | Read references/entry-points.md, generate it |
Interactive Feature Checklist
Present this as a multi-select checklist. Items marked ON are pre-selected defaults.
Entry Points (pick one or more)
| Entry Point | Default | Description |
|---|---|---|
| CLI | ON | args/stdin to agent to stdout, --json for NDJSON |
| Library module | ON | import { runAgent } from './agent' |
| HTTP server | OFF | Bun.serve() with SSE streaming |
| MCP server | OFF | Expose as MCP tool via stdio |
OpenRouter Server Tools (server-side, zero implementation)
| Tool | Type string | Default |
|---|---|---|
| Web Search | openrouter:web_search | ON |
| Web Fetch | openrouter:web_fetch | ON |
| Datetime | openrouter:datetime | ON |
| Image Generation | openrouter:image_generation | OFF |
Server tools go in the tools array alongside user-defined tools. No client code needed — OpenRouter executes them. Docs: openrouter.ai/docs/guides/features/server-tools.
User-Defined Tools (client-side, generated into src/tools/)
| Tool | Default | Description |
|---|---|---|
| File Read | ON | Read files with offset/limit |
| File Write | ON | Write/create files inside the working directory, auto-create directories |
| File Edit | ON | Search-and-replace with diff validation, inside the working directory |
| Glob/Find | ON | File discovery by glob pattern |
| Grep/Search | ON | Content search by regex |
| Directory List | ON | List directory contents |
| Shell/Bash | ON | Execute commands with timeout and output capture; refuses unless run with --allow-shell, and is not confined to the working directory once allowed |
| Custom Tool Template | ON | Empty skeleton for domain-specific tools |
| JS/TS REPL | OFF | Persistent Bun REPL |
| Sub-agent Spawn | OFF | Delegate tasks to child agents |
| View Image | OFF | Read local images as base64 |
Agent Modules (architectural components)
| Module | Default | Description |
|---|---|---|
| Session Persistence | ON | JSONL conversation log, --no-session to disable |
| Retry with Backoff | ON | Built into agent.ts |
| Context Compaction | OFF | Summarize when context is long |
| Tool Result Offload | OFF | Persist oversized tool outputs to disk, keep preview in context |
| System Prompt Composition | OFF | Dynamic instructions from context files |
| Tool Approval Flow | OFF | Programmatic approve/reject |
| Structured Event Logging | OFF | JSON events to stderr |
| Output Schema Validation | OFF | Zod schema constraining response |
| Webhook Notifications | OFF | POST on completion |
CLI Output Mode (single-select, if CLI entry point is ON)
| Mode | Default | Description |
|---|---|---|
| Text | ON | Final response text to stdout |
| JSON | OFF | NDJSON event stream |
| Quiet | OFF | Exit code only |
Generation Workflow
Before generating, ask the user what to name their agent. This name is used as:
- the
"name"field inpackage.json - the
"bin"command (sobun linkmakes it a globally-invokable CLI) - the project directory name (if creating a new directory)
Suggested question: "What would you like to call your agent? (short kebab-case, e.g. research-bot or docs-helper)". Validate the answer is a valid npm package name (lowercase, kebab-case, no spaces). Default to my-agent if the user has no preference. Use the chosen name everywhere the workflow below shows <agent-name>.
After getting the name and checklist selections, follow this workflow:
- [ ] Generate package.json with name=<agent-name> and bin={"<agent-name>": "src/cli.ts"}
- [ ] Generate tsconfig.json (Bun-native)
- [ ] Generate src/config.ts
- [ ] Generate src/tools/index.ts wiring selected tools
- [ ] Generate selected tool files in src/tools/ (specs in references/tools.md)
- [ ] Generate src/agent.ts (core runner)
- [ ] If Session Persistence ON: generate src/session.ts (spec in references/modules.md)
- [ ] Generate selected modules (specs in references/modules.md)
- [ ] Generate src/cli.ts entry point with shebang `#!/usr/bin/env bun` (spec in references/entry-points.md)
- [ ] If HTTP server selected: generate src/server.ts (spec in references/entry-points.md)
- [ ] If MCP server selected: generate src/mcp-server.ts (spec in references/entry-points.md)
- [ ] Generate .env.example
- [ ] Generate test/agent.test.ts
- [ ] Run `bun install` to fetch dependencies
- [ ] Verify: run `bunx tsc --noEmit`
- [ ] Run `bun link` inside the project to register <agent-name> globally
- [ ] Verify the command is on PATH: `command -v <agent-name>` should print a path. If it fails, tell the user to add Bun's bin dir to their shell rc:
`export PATH="$HOME/.bun/bin:$PATH"` (for bash/zsh). `bun link` silently succeeds even when `~/.bun/bin` isn't on PATH, so without this check the user will be told the agent is globally available but `command not found` will greet them.
- [ ] Tell the user they can now invoke their agent from anywhere with `<agent-name> "<prompt>"`
- [ ] Optional: run `npx skills-ref validate .` to check SKILL.md frontmatter (if installed)
After generation, the user can run their agent from any directory:
<agent-name> "What's in this repo?"
echo "Summarize README.md" | <agent-name>
<agent-name> --json "List all TODOs" | jq .
To later rename the agent, update the name and bin keys in package.json, then run bun unlink && bun link.
Tool Pattern
All user-defined tools follow this pattern using @openrouter/agent/tool. Here is one complete example — all other tools in references/tools.md follow the same shape:
import { tool } from '@openrouter/agent/tool';
import { z } from 'zod';
const DEFAULT_LINE_LIMIT = 2000;
const MAX_LINE_CHARS = 2000;
export const fileReadTool = tool({
name: 'file_read',
description:
'Read the contents of a file. Output is capped at 2000 lines by default (use offset/limit to paginate) and any line longer than 2000 characters is truncated. When the response is truncated, the hint field tells you how to continue.',
inputSchema: z.object({
path: z.string().describe('Absolute path to the file'),
offset: z.number().optional().describe('Start reading from this line (1-indexed)'),
limit: z.number().optional().describe(`Maximum lines to return (default ${DEFAULT_LINE_LIMIT})`),
}),
execute: async ({ path, offset, limit }) => {
try {
const content = await Bun.file(path).text();
const lines = content.split('\n');
const start = offset ? offset - 1 : 0;
const end = Math.min(start + (limit ?? DEFAULT_LINE_LIMIT), lines.length);
let longLines = 0;
const slice = lines.slice(start, end).map((line) => {
if (line.length <= MAX_LINE_CHARS) return line;
longLines++;
return line.slice(0, MAX_LINE_CHARS) + `… [line truncated, ${line.length - MAX_LINE_CHARS} chars dropped]`;
});
const tailTruncated = end < lines.length;
const truncated = tailTruncated || longLines > 0;
const hintParts: string[] = [`Showing lines ${start + 1}-${end} of ${lines.length}.`];
if (tailTruncated) hintParts.push(`Use offset=${end + 1} to continue.`);
if (longLines > 0) hintParts.push(`${longLines} line(s) exceeded ${MAX_LINE_CHARS} chars and were per-line truncated; use grep to fetch content from those lines.`);
return {
content: slice.join('\n'),
totalLines: lines.length,
...(truncated && {
truncated: true,
...(tailTruncated && { nextOffset: end + 1 }),
hint: hintParts.join(' '),
}),
};
} catch (err: any) {
if (err.code === 'ENOENT') return { error: `File not found: ${path}` };
if (err.code === 'EACCES') return { error: `Permission denied: ${path}` };
return { error: err.message };
}
},
});
For specs of all other tools, see references/tools.md.
Core Files
These files are always generated. The agent adapts them based on checklist selections.
package.json
Initialize the project and install dependencies. Replace <agent-name> with the name the user chose:
bun init -y
# Then edit package.json:
{
"name": "<agent-name>",
"type": "module",
"bin": {
"<agent-name>": "src/cli.ts"
},
"scripts": {
"start": "bun run src/cli.ts",
"dev": "bun --watch src/cli.ts",
"build": "tsc --noEmit",
"test": "bun test"
},
"dependencies": {
"@openrouter/agent": "latest",
"zod": "latest"
},
"devDependencies": {
"@types/bun": "latest",
"typescript": "latest"
}
}
The bin entry is what makes the agent invokable by name after bun link. The target (src/cli.ts) must have a #!/usr/bin/env bun shebang on the first line.
tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"outDir": "dist",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"types": ["bun-types"]
},
"include": ["src", "test"]
}
src/config.ts
import { readFileSync, existsSync } from 'fs';
import { homedir } from 'os';
import { join, resolve } from 'path';
// The <agent-name> chosen above, so each agent gets its own ~/.config/<agent-name>/ directory.
const APP_NAME = '<agent-name>';
function positiveNumber(name: string, raw: string | number): number {
const n = Number(raw);
if (!Number.isFinite(n) || n <= 0) {
throw new Error(`${name} must be a positive number, got: ${JSON.stringify(raw)}`);
}
return n;
}
export interface AgentConfig {
apiKey: string;
model: string;
name: string;
systemPrompt: string;
maxSteps: number;
maxCost: number;
sessionDir: string;
sessionEnabled: boolean;
outputMode: 'text' | 'json' | 'quiet';
/** Let the model run shell commands without asking. Off by default. */
allowShell: boolean;
}
const DEFAULTS: AgentConfig = {
apiKey: '',
model: 'anthropic/claude-sonnet-4.6',
name: 'My Agent',
systemPrompt: [
'You are a coding assistant with access to tools for reading, writing, editing, and searching files, and running shell commands.',
'',
'Current working directory: {cwd}',
'',
'Guidelines:',
'- Use your tools proactively. Explore the codebase to find answers instead of asking the user.',
'- Keep working until the task is fully resolved before responding.',
'- Do not guess or make up information — use your tools to verify.',
'- Be concise and direct.',
'- Show file paths clearly when working with files.',
'- Prefer grep and glob tools over shell commands for file search.',
'- When editing code, make minimal targeted changes consistent with the existing style.',
].join('\n'),
maxSteps: 20,
maxCost: 1.0,
sessionDir: '.sessions',
sessionEnabled: true,
outputMode: 'text',
allowShell: false,
};
// Fields a config file may set, and their types. apiKey is env-only so it never sits in a file.
const FILE_FIELDS: Record<string, 'string' | 'number' | 'boolean'> = {
model: 'string',
name: 'string',
systemPrompt: 'string',
maxSteps: 'number',
maxCost: 'number',
sessionDir: 'string',
sessionEnabled: 'boolean',
};
/**
* The config file is read from an explicit path (--config or AGENT_CONFIG) or the user's
* config directory, never from the working directory: a cloned repo could otherwise ship
* an agent.config.json that replaces the system prompt and lifts the cost and step limits.
*/
export function resolveConfigPath(explicit?: string): { path: string; required: boolean } {
const chosen = explicit || process.env.AGENT_CONFIG;
if (chosen) return { path: resolve(chosen), required: true };
const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
return { path: join(base, APP_NAME, 'agent.config.json'), required: false };
}
function readConfigFile(path: string, required: boolean): Partial<AgentConfig> {
if (!existsSync(path)) {
if (required) throw new Error(`Config file not found: ${path}`);
return {};
}
const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'));
if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
throw new Error(`${path} must contain a JSON object`);
}
const out: Record<string, unknown> = {};
for (const [key, value] of Object.entries(raw)) {
const type = FILE_FIELDS[key];
if (!type) throw new Error(`${path}: unsupported field "${key}"`);
if (typeof value !== type) throw new Error(`${path}: "${key}" must be a ${type}`);
out[key] = type === 'number' ? positiveNumber(`${path}: ${key}`, value as number) : value;
}
return out as Partial<AgentConfig>;
}
export function loadConfig(
overrides: Partial<AgentConfig> = {},
opts?: { skipApiKey?: boolean; configPath?: string },
): AgentConfig {
const { path, required } = resolveConfigPath(opts?.configPath);
let config: AgentConfig = { ...DEFAULTS, ...readConfigFile(path, required) };
if (process.env.OPENROUTER_API_KEY) config.apiKey = process.env.OPENROUTER_API_KEY;
if (process.env.AGENT_MODEL) config.model = process.env.AGENT_MODEL;
if (process.env.AGENT_MAX_STEPS) config.maxSteps = positiveNumber('AGENT_MAX_STEPS', process.env.AGENT_MAX_STEPS);
if (process.env.AGENT_MAX_COST) config.maxCost = positiveNumber('AGENT_MAX_COST', process.env.AGENT_MAX_COST);
config = { ...config, ...overrides };
if (!config.apiKey && !opts?.skipApiKey) throw new Error('OPENROUTER_API_KEY is required.');
return config;
}
src/tools/index.ts
Adapt imports based on checklist selections. This example includes all default-ON tools:
import { serverTool } from '@openrouter/agent';
import { fileReadTool } from './file-read.js';
import { fileWriteTool } from './file-write.js';
import { fileEditTool } from './file-edit.js';
import { globTool } from './glob.js';
import { grepTool } from './grep.js';
import { listDirTool } from './list-dir.js';
import { shellTool } from './shell.js';
import { myCustomTool } from './custom.js';
// `as const` unlocks full type inference for tool calls downstream.
// See: https://openrouter.ai/docs/agent-sdk/call-model/tools
export const tools = [
// User-defined tools — executed client-side
fileReadTool,
fileWriteTool,
fileEditTool,
globTool,
grepTool,
listDirTool,
shellTool,
myCustomTool,
// Server tools — executed by OpenRouter, no client implementation needed
serverTool({ type: 'openrouter:web_search' }),
serverTool({ type: 'openrouter:web_fetch' }),
serverTool({ type: 'openrouter:datetime', parameters: { timezone: 'UTC' } }),
] as const;
src/agent.ts
import { OpenRouter } from '@openrouter/agent';
import type { Item } from '@openrouter/agent';
import { stepCountIs, maxCost } from '@openrouter/agent/stop-conditions';
import type { AgentConfig } from './config.js';
import { tools } from './tools/index.js';
export type ChatMessage = { role: 'user' | 'assistant' | 'system'; content: string };
export type AgentEvent =
| { type: 'text'; delta: string }
| { type: 'tool_call'; name: string; callId: string; args: Record<string, unknown> }
| { type: 'tool_result'; name: string; callId: string; output: string }
| { type: 'reasoning'; delta: string }
| { type: 'turn_end' }
| { type: 'done'; usage: { inputTokens?: number; outputTokens?: number; totalTokens?: number } | null | undefined; durationMs: number };
export async function runAgent(
config: AgentConfig,
input: string | ChatMessage[],
options?: { onEvent?: (event: AgentEvent) => void; signal?: AbortSignal },
) {
const startedAt = Date.now();
const client = new OpenRouter({ apiKey: config.apiKey });
const result = client.callModel({
model: config.model,
instructions: config.systemPrompt.replace('{cwd}', process.cwd()),
input: input as string | Item[],
tools,
stopWhen: [stepCountIs(config.maxSteps), maxCost(config.maxCost)],
});
// Wire AbortSignal → result.cancel() so the underlying network stream
// actually closes (not just the iterator we're about to walk). Also
// handle the pre-aborted case: addEventListener('abort') does not fire
// for signals already in the aborted state.
const onAbort = () => result.cancel();
options?.signal?.addEventListener('abort', onAbort);
if (options?.signal?.aborted) result.cancel();
// Draining getTextStream concurrently with getItemsStream reads the
// stream dry, so getResponse().outputText ends up empty. We accumulate
// text deltas here as a source of truth for the final text.
let accumulatedText = '';
try {
if (options?.onEvent) {
// Run two streams concurrently: getTextStream for text deltas (no
// bookkeeping required) and getItemsStream filtered to tool events.
// The SDK's ReusableReadableStream allows concurrent consumption.
const callNames = new Map<string, string>();
const streamText = async () => {
for await (const delta of result.getTextStream()) {
if (options?.signal?.aborted) break;
options.onEvent!({ type: 'text', delta });
accumulatedText += delta;
}
};
const streamTools = async () => {
for await (const item of result.getItemsStream()) {
if (options?.signal?.aborted) break;
if (item.type === 'function_call') {
callNames.set(item.callId, item.name);
if (item.status === 'completed') {
const args = (() => { try { return item.arguments ? JSON.parse(item.arguments) : {}; } catch { return {}; } })();
options.onEvent!({ type: 'tool_call', name: item.name, callId: item.callId, args });
}
} else if (item.type === 'function_call_output') {
const out = typeof item.output === 'string' ? item.output : JSON.stringify(item.output);
options.onEvent!({
type: 'tool_result',
name: callNames.get(item.callId) ?? 'unknown',
callId: item.callId,
output: out.length > 200 ? out.slice(0, 200) + '...' : out,
});
// Signal a turn boundary; consumers (e.g. CLI text mode) can
// render a separator. Keeps presentation out of agent.ts.
options.onEvent!({ type: 'turn_end' });
} else if (item.type === 'reasoning') {
const text = item.summary?.map((s: { text: string }) => s.text).join('') ?? '';
if (text) options.onEvent!({ type: 'reasoning', delta: text });
}
}
};
await Promise.all([streamText(), streamTools()]);
}
const response = await result.getResponse();
const durationMs = Date.now() - startedAt;
const text = accumulatedText || (response.outputText ?? '');
options?.onEvent?.({ type: 'done', usage: response.usage, durationMs });
return { text, usage: response.usage, output: response.output, durationMs };
} finally {
options?.signal?.removeEventListener('abort', onAbort);
}
}
/**
* Retry on 429/5xx — but ONLY if no tool calls have been executed yet.
* Once a mutating tool (file_write, shell, etc.) has run, replaying the
* whole agent from the initial prompt would double-execute side effects.
* For mid-run resilience, use a StateAccessor (see references/modules.md).
*/
export async function runAgentWithRetry(
config: AgentConfig,
input: string | ChatMessage[],
options?: { onEvent?: (event: AgentEvent) => void; signal?: AbortSignal; maxRetries?: number },
) {
for (let attempt = 0, max = options?.maxRetries ?? 3; attempt <= max; attempt++) {
let toolCallsMade = 0;
const wrappedOptions = {
...options,
onEvent: (event: AgentEvent) => {
if (event.type === 'tool_call') toolCallsMade++;
options?.onEvent?.(event);
},
};
try {
return await runAgent(config, input, wrappedOptions);
} catch (err: any) {
const s = err?.status ?? err?.statusCode;
const retryable = s === 429 || (s >= 500 && s < 600);
if (!retryable || attempt === max || toolCallsMade > 0) throw err;
await new Promise((r) => setTimeout(r, Math.min(1000 * 2 ** attempt, 30000)));
}
}
throw new Error('Unreachable');
}
src/cli.ts
Headless CLI entry point — parses args, reads stdin, dispatches to the agent, and exits. See references/entry-points.md for the complete implementation.
import { parseArgs } from 'util';
import { loadConfig } from './config.js';
import { runAgentWithRetry, type AgentEvent } from './agent.js';
import { initSessionDir, saveMessage, newSessionPath } from './session.js';
const { values, positionals } = parseArgs({
args: process.argv.slice(2),
options: {
prompt: { type: 'string', short: 'p' },
json: { type: 'boolean', short: 'j', default: false },
quiet: { type: 'boolean', short: 'q', default: false },
'no-session': { type: 'boolean', default: false },
model: { type: 'string', short: 'm' },
'max-steps': { type: 'string' },
'max-cost': { type: 'string' },
'allow-shell': { type: 'boolean', default: false },
config: { type: 'string' },
help: { type: 'boolean', short: 'h', default: false },
},
allowPositionals: true,
});
// ... resolve prompt from args, positional, or stdin
// ... call loadConfig(overrides, { configPath: values.config }) (allowShell: true only from --allow-shell)
// ... setShellApprover(async () => config.allowShell) so shell stays off by default
// ... call runAgentWithRetry with appropriate event handler
// ... exit with code 0 on success, 1 on error
See references/entry-points.md for the complete src/cli.ts, src/server.ts, and src/mcp-server.ts implementations.
Reference Files
For content beyond the core files:
- references/tools.md -- Specs for all user-defined tools: file-read, file-write, file-edit, glob, grep, list-dir, shell, web-fetch, js-repl, sub-agent, view-image, custom template
- references/modules.md -- Agent modules: session persistence, context compaction, system prompt composition, tool approval, structured logging, output schema validation, webhook notifications
- references/entry-points.md -- Entry point specs: CLI (full implementation), HTTP server with SSE, MCP server via stdio
Install and run Ori Harness
Use this recipe when the user wants to install Ori, run an existing coding agent through Ori, sign in to Ori, upgrade Ori, or select an OpenRouter model for a local agent. Do not use it for model evaluations, plain unit tests, or when the user only wants to run an already-installed agent directly without Ori.
1. Install Ori
Run the official installer:
curl -fsSL https://openrouter.ai/labs/ori/install.sh | bash
The installer puts the ori executable in the user's local install location.
Do not use sudo unless the user explicitly chooses a system-wide install
location.
2. Verify the CLI
Run:
ori --version
The command must print a version and exit successfully. If the shell cannot
find ori, inspect the installer's reported directory and ensure the user's
local binary directory is on PATH, then start a new shell or update PATH
before continuing.
3. Sign in with OpenRouter OAuth
Run:
ori login
Ori opens the user's browser for OAuth sign-in with their existing OpenRouter
account and stores the resulting credential for the CLI. The user does not
need to create, copy, or paste an API key. If a browser cannot open, use
ori login --no-browser and give the user the printed URL.
Do not ask the user to paste a key when OAuth is available. An explicitly
exported OPENROUTER_API_KEY can still be used by Ori when the user already
has one, but it is not required for this setup.
4. Run the user's existing agent CLI
Ori runs the agent CLI already installed on the user's PATH. It does not
replace the user's agent or make them learn a new agent workflow. Supported
launch commands today are:
ori claude
ori codex
ori opencode
ori hermes
If the selected agent is missing, Ori prints the recommended install command
and documentation link for that agent. Follow that instruction, then rerun the
same ori <harness> command.
Pass the user's normal agent arguments after the Ori flags. Everything Ori does not consume is forwarded to the agent unchanged. For example:
ori claude -p "Review the authentication changes"
ori codex --full-auto
ori opencode
5. Choose any OpenRouter model
Use --model with any valid OpenRouter model id:
ori claude --model claude-opus-latest
ori codex --model gpt-5.2
ori hermes --model gemini-3-pro
The model value is routed through OpenRouter. Keep the user's existing agent arguments after the Ori flags.
6. Upgrade Ori
Upgrade an installed release with:
ori update
Then verify the active version again:
ori --version
Do not use ori update from a source checkout as a substitute for installing
the released CLI.
7. Confirm the setup works
After sign-in, run the selected agent with a harmless prompt that proves the request reaches OpenRouter:
ori claude --model openrouter/auto -p "Reply with exactly: Ori is connected"
Use the equivalent ori codex, ori opencode, or ori hermes command if the
user chose another agent. Confirm that the agent starts, the prompt completes,
and the response is returned. If the agent is missing, authentication fails,
or the model id is rejected, report the exact command output and fix that
specific setup issue before claiming the install worked.
Migrating from @openrouter/sdk to @openrouter/agent
Agent functionality (callModel, tool(), stop conditions, format converters, streaming helpers) has moved from @openrouter/sdk to the standalone @openrouter/agent package. The @openrouter/agent package includes its own OpenRouter client class, so you do not need @openrouter/sdk for agent use cases.
When This Applies
Migrate if your code imports any of these from @openrouter/sdk:
callModelor usesclient.callModel()tool()factory function- Stop conditions:
stepCountIs,hasToolCall,maxCost,maxTokensUsed,finishReasonIs - Format converters:
fromClaudeMessages,toClaudeMessage,fromChatMessages,toChatMessage - Types:
Tool,ToolWithExecute,ToolWithGenerator,ManualTool,CallModelInput,ModelResult
Quick Migration
Step 1: Install
npm install @openrouter/agent
If you only use agent features, you can remove @openrouter/sdk:
npm uninstall @openrouter/sdk
npm install @openrouter/agent
If you also use non-agent SDK features (models list, chat completions, credits, OAuth, API keys), keep both packages installed.
Step 2: Update Imports
The OpenRouter client class and client.callModel() pattern work identically. Only the import source changes:
- import OpenRouter from '@openrouter/sdk';
+ import { OpenRouter } from '@openrouter/agent';
The rest of your code stays the same:
const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Hello!',
});
const text = await result.getText();
Complete Import Mapping
Client & callModel
| Old | New |
|---|---|
import OpenRouter from '@openrouter/sdk' | import { OpenRouter } from '@openrouter/agent' |
import OpenRouter, { tool, stepCountIs } from '@openrouter/sdk' | import { OpenRouter } from '@openrouter/agent'import { tool } from '@openrouter/agent/tool'import { stepCountIs } from '@openrouter/agent/stop-conditions' |
A standalone callModel function is also available for advanced use cases where a pre-existing OpenRouterCore instance is available:
import { callModel } from '@openrouter/agent/call-model';
// Requires an OpenRouterCore instance (from @openrouter/sdk/core)
const result = callModel(coreInstance, { model: 'openai/gpt-5-nano', input: 'Hello' });
For most use cases, prefer the client.callModel() method shown above.
Tool Creation
| Old | New |
|---|---|
import { tool } from '@openrouter/sdk' | import { tool } from '@openrouter/agent/tool' |
Stop Conditions
| Old | New |
|---|---|
import { stepCountIs, hasToolCall, maxCost } from '@openrouter/sdk' | import { stepCountIs, hasToolCall, maxCost } from '@openrouter/agent/stop-conditions' |
import { maxTokensUsed, finishReasonIs } from '@openrouter/sdk' | import { maxTokensUsed, finishReasonIs } from '@openrouter/agent/stop-conditions' |
Types
| Old | New |
|---|---|
import type { Tool, ToolWithExecute, ToolWithGenerator, ManualTool } from '@openrouter/sdk/lib/tool-types' | import type { Tool, ToolWithExecute, ToolWithGenerator, ManualTool } from '@openrouter/agent/tool-types' |
import type { CallModelInput } from '@openrouter/sdk/lib/async-params' | import type { CallModelInput } from '@openrouter/agent/async-params' |
import { ModelResult } from '@openrouter/sdk/lib/model-result' | import { ModelResult } from '@openrouter/agent/model-result' |
Format Converters
| Old | New |
|---|---|
import { fromClaudeMessages, toClaudeMessage } from '@openrouter/sdk' | import { fromClaudeMessages, toClaudeMessage } from '@openrouter/agent' |
import { fromChatMessages, toChatMessage } from '@openrouter/sdk' | import { fromChatMessages, toChatMessage } from '@openrouter/agent' |
Type Guards
| Old | New |
|---|---|
import { hasExecuteFunction, isGeneratorTool, isRegularExecuteTool } from '@openrouter/sdk' | import { hasExecuteFunction, isGeneratorTool, isRegularExecuteTool } from '@openrouter/agent/tool-types' |
Before & After Example
Before (using @openrouter/sdk)
import OpenRouter, { tool, stepCountIs, hasToolCall } from '@openrouter/sdk';
import { z } from 'zod';
const client = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY,
});
const searchTool = tool({
name: 'web_search',
description: 'Search the web',
inputSchema: z.object({ query: z.string() }),
outputSchema: z.object({ results: z.array(z.string()) }),
execute: async ({ query }) => {
return { results: ['Result 1', 'Result 2'] };
},
});
const finishTool = tool({
name: 'finish',
description: 'Complete the task',
inputSchema: z.object({ answer: z.string() }),
execute: async ({ answer }) => ({ answer }),
});
const result = client.callModel({
model: 'openai/gpt-5-nano',
instructions: 'You are a research assistant.',
input: 'What are the latest AI developments?',
tools: [searchTool, finishTool],
stopWhen: [stepCountIs(10), hasToolCall('finish')],
});
const text = await result.getText();
After (using @openrouter/agent)
import { OpenRouter } from '@openrouter/agent';
import { tool } from '@openrouter/agent/tool';
import { stepCountIs, hasToolCall } from '@openrouter/agent/stop-conditions';
import { z } from 'zod';
const client = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY,
});
const searchTool = tool({
name: 'web_search',
description: 'Search the web',
inputSchema: z.object({ query: z.string() }),
outputSchema: z.object({ results: z.array(z.string()) }),
execute: async ({ query }) => {
return { results: ['Result 1', 'Result 2'] };
},
});
const finishTool = tool({
name: 'finish',
description: 'Complete the task',
inputSchema: z.object({ answer: z.string() }),
execute: async ({ answer }) => ({ answer }),
});
const result = client.callModel({
model: 'openai/gpt-5-nano',
instructions: 'You are a research assistant.',
input: 'What are the latest AI developments?',
tools: [searchTool, finishTool],
stopWhen: [stepCountIs(10), hasToolCall('finish')],
});
const text = await result.getText();
The only changes are the three import lines at the top.
When to Keep @openrouter/sdk
Keep @openrouter/sdk installed if you use any of these non-agent features:
| Feature | Access |
|---|---|
| Model listing | client.models.list() |
| Chat completions | client.chat.send() |
| Legacy completions | client.completions.generate() |
| Usage analytics | client.analytics.getUserActivity() |
| Credit balance | client.credits.getCredits() |
| API key management | client.apiKeys.list(), .create(), etc. |
| OAuth PKCE flow | client.oAuth.createAuthCode(), .exchangeAuthCodeForAPIKey() |
For mixed projects, use @openrouter/sdk for these features and @openrouter/agent for agent features:
import OpenRouter from '@openrouter/sdk'; // SDK client for models, credits, etc.
import { OpenRouter as Agent } from '@openrouter/agent'; // Agent client for callModel
import { tool } from '@openrouter/agent/tool';
import { stepCountIs } from '@openrouter/agent/stop-conditions';
// Use SDK client for non-agent features
const sdkClient = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
const models = await sdkClient.models.list();
const credits = await sdkClient.credits.getCredits();
// Use Agent client for callModel
const agent = new Agent({ apiKey: process.env.OPENROUTER_API_KEY });
const result = agent.callModel({
model: 'openai/gpt-5-nano',
input: 'Hello!',
tools: [myTool],
stopWhen: stepCountIs(5),
});
New Features in @openrouter/agent
These features are only available in @openrouter/agent, not in @openrouter/sdk:
Shared Context Schema
Type-safe shared state across all tools in a conversation:
import { OpenRouter } from '@openrouter/agent';
import { z } from 'zod';
const client = new OpenRouter({ apiKey: '...' });
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Process this data',
sharedContextSchema: z.object({
userId: z.string(),
sessionData: z.record(z.unknown()),
}),
context: {
shared: { userId: '123', sessionData: {} },
},
tools: [myTool],
});
Tool Context
Tools can declare their own typed context and access shared context:
import { tool } from '@openrouter/agent/tool';
import { z } from 'zod';
const myTool = tool({
name: 'my_tool',
description: 'A tool with context',
inputSchema: z.object({ query: z.string() }),
contextSchema: z.object({ apiKey: z.string() }),
execute: async (params, context) => {
// context.local — this tool's own context
// context.shared — shared context across all tools
// context.setContext({ ... }) — update this tool's context
// context.setSharedContext({ ... }) — update shared context
return { result: 'done' };
},
});
Tool Approval Flow
Require user approval before tool execution:
const dangerousTool = tool({
name: 'delete_file',
description: 'Delete a file',
inputSchema: z.object({ path: z.string() }),
requireApproval: true, // or a function: (toolCall, context) => boolean
execute: async ({ path }) => { /* ... */ },
});
Turn Lifecycle Callbacks
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Complex task',
tools: [myTool],
onTurnStart: async (context) => {
console.log(`Starting turn ${context.numberOfTurns}`);
},
onTurnEnd: async (context, response) => {
console.log(`Turn ${context.numberOfTurns} complete`);
},
});
All Subpath Exports
@openrouter/agent provides granular subpath imports:
| Subpath | Exports |
|---|---|
@openrouter/agent | Barrel: all exports below |
@openrouter/agent/client | OpenRouter class |
@openrouter/agent/call-model | callModel standalone function |
@openrouter/agent/tool | tool() factory function |
@openrouter/agent/tool-types | Tool, ToolWithExecute, ToolWithGenerator, ManualTool, type guards |
@openrouter/agent/stop-conditions | stepCountIs, hasToolCall, maxCost, maxTokensUsed, finishReasonIs |
@openrouter/agent/model-result | ModelResult response wrapper |
@openrouter/agent/async-params | CallModelInput, hasAsyncFunctions, resolveAsyncFunctions |
@openrouter/agent/anthropic-compat | fromClaudeMessages, toClaudeMessage |
@openrouter/agent/chat-compat | fromChatMessages, toChatMessage |
@openrouter/agent/conversation-state | createInitialState, updateState, appendToMessages |
@openrouter/agent/next-turn-params | nextTurnParams utilities |
@openrouter/agent/stream-transformers | extractUnsupportedContent, getUnsupportedContentSummary |
@openrouter/agent/tool-context | buildToolExecuteContext, ToolContextStore |
@openrouter/agent/tool-event-broadcaster | ToolEventBroadcaster |
@openrouter/agent/turn-context | buildTurnContext |
OpenRouter Analytics Query Execution
Full reference for constructing and executing analytics queries against the OpenRouter API.
Prerequisites
OPENROUTER_API_KEYmust be set to a management key. Management keys are separate from regular API keys — get one at https://openrouter.ai/settings/management-keys
Query Endpoint
POST https://openrouter.ai/api/v1/analytics/query
Authorization: Bearer sk-or-v1-...
Content-Type: application/json
Or via the openrouter-analytics skill scripts:
cd <openrouter-analytics-skill-path>/scripts && npx tsx query-analytics.ts --metrics request_count
Source of truth (avoid drift): the metric/dimension names and the request schema below are illustrative. The live, authoritative list comes from the meta endpoint — call
GET /api/v1/analytics/meta(ordiscover-schema.ts) and treat its response as canonical. For agent-readable docs, OpenRouter publishesllms.txt. Prefer those over the inline examples in this file if they ever disagree.
Request Schema
{
"metrics": ["request_count", "total_usage"],
"dimensions": ["model"],
"granularity": "day",
"time_range": {
"start": "2026-05-01T00:00:00Z",
"end": "2026-05-20T00:00:00Z"
},
"filters": [
{ "field": "model", "operator": "eq", "value": "anthropic/claude-sonnet-4" }
],
"order_by": { "field": "total_usage", "direction": "desc" },
"limit": 100,
"group_limit": 20,
"classifier_dimensions": {
"classifier_id": "<uuid>",
"dimension_names": ["category"],
"include_nulls": false
},
"classifier_filters": {
"classifier_id": "<uuid>",
"filters": [
{ "field": "sentiment", "operator": "eq", "value": "positive" }
]
}
}
Required Fields
| Field | Type | Description |
|---|---|---|
metrics | string[] | At least one metric to compute. Call the meta endpoint to see available metrics. |
Optional Fields
| Field | Type | Default | Description |
|---|---|---|---|
dimensions | string[] | [] | Up to 2 dimensions to group by |
granularity | string | none | Time bucketing: minute, hour, day, week, month |
time_range | object | last 7 days | { start, end } as ISO 8601 UTC datetime strings. Seconds are required (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed) — minute-precision values such as 2026-05-01T00:00Z are rejected with 400. |
filters | object[] | [] | Up to 20 filter conditions |
order_by | object | time desc (if granularity set) | { field, direction } where field is a metric, dimension, or "date" (short-form alias — maps to date__day, date__hour, etc. based on granularity) |
limit | integer | 1000 | Maximum total rows to return (1–10,000). On time-series queries with dimensions and no explicit group_limit, the server may raise this to accommodate the expected number of time-bucket/dimension combinations. |
group_limit | integer | auto-computed | Maximum rows per distinct dimension combination (ClickHouse LIMIT n BY). When omitted on time-series queries (granularity + dimensions), auto-computed from the time range to guarantee full time-window coverage per group. Explicit values override the default. Ignored when no dimensions are specified. |
classifier_dimensions | object | none | Group by dynamic classifier-produced dimensions. See Classifier Dimensions below. |
classifier_filters | object | none | Filter on classifier-produced dimension values. See Classifier Filters below. |
Filter Object Shape
{ "field": "<dimension_name>", "operator": "<op>", "value": "<value>" }
- Scalar operators (
eq,neq,gt,gte,lt,lte):valueis a string or number - Array operators (
in,not_in):valueis an array of strings or numbers in/not_inaccept an optionalinclude_unset: true, which also matches rows where the dimension has no value. Supported only on dimensions with an unset bucket (api_key_id,app,user) — otherwise the request is rejected with 400.- Several dimensions are label-resolved in query results (returned as human-readable names), but filters must use the underlying ID:
api_key_id— numeric ID (from generation metadata) or 64-char SHA-256 hash (fromGET /api/v1/keys). Hashes are auto-resolved to numeric IDs before querying.user— Clerk user ID (e.g.user_abc123), not the display name/email shown in results.workspace— workspace UUID, not the workspace name shown in results.app— numeric app ID, not the app title shown in results.model— permaslug (e.g.openai/gpt-4o), not the display name.
- Other dimensions (
provider,origin,country,finish_reason,external_user, etc.) are not enriched — filter values match what's returned in results.
Order By
{ "field": "<metric_or_dimension_or_date>", "direction": "asc" | "desc" }
When granularity is set and no order_by is specified, results are ordered by time descending.
Classifier Dimensions
Classifier dimensions allow grouping by dynamic, user-defined classification labels (e.g., topic, sentiment, category) produced by a classifier attached to your account.
{
"classifier_dimensions": {
"classifier_id": "550e8400-e29b-41d4-a716-446655440000",
"dimension_names": ["category"],
"include_nulls": false
}
}
| Field | Type | Required | Description |
|---|---|---|---|
classifier_id | string (UUID) | Yes | ID of the classifier (must belong to the caller's account) |
dimension_names | string[] | No | Specific dimension names to group by (max 2). If omitted, all classifier dimensions are included. Names must be valid identifiers (letters, digits, underscores; max 64 chars). |
include_nulls | boolean | No | When true, unclassified rows are included in results. Default false (only classified rows). |
Constraints:
- Limits the query time range to 31 days
- Single dimension name → result column is aliased to that name (e.g.,
category) - Two dimension names → each becomes its own result column, cross-grouping results by both values
dimension_namesomitted → result uses genericclf_dimension_name/clf_dimension_valuecolumns (one row per dimension/value pair)
Classifier Filters
Classifier filters narrow results to generations matching specific classification values. They can be used independently or alongside classifier_dimensions.
{
"classifier_filters": {
"classifier_id": "550e8400-e29b-41d4-a716-446655440000",
"filters": [
{ "field": "category", "operator": "eq", "value": "billing" },
{ "field": "sentiment", "operator": "in", "value": ["positive", "neutral"] }
]
}
}
| Field | Type | Required | Description |
|---|---|---|---|
classifier_id | string (UUID) | Yes | ID of the classifier (must belong to the caller's account) |
filters | object[] | Yes | 1–10 filter conditions on classifier dimensions |
filters[].field | string | Yes | Classifier dimension name to filter on |
filters[].operator | string | Yes | One of: eq, neq, in, not_in (no gt/lt — values are strings) |
filters[].value | string | string[] | Yes | Scalar for eq/neq, array for in/not_in |
Constraints:
- Limits the query time range to 31 days
- Only equality/set operators supported (classification values are strings — ordered comparisons would be lexicographic)
- All filter field names must be configured dimensions on the classifier
Response Schema
{
"data": {
"data": [
{ "date__day": "2026-05-19", "model": "anthropic/claude-sonnet-4", "request_count": "1523", "total_usage": 4.27 },
{ "date__day": "2026-05-18", "model": "openai/gpt-4o", "request_count": "892", "total_usage": 2.15 }
],
"metadata": {
"query_time_ms": 142,
"row_count": 2,
"truncated": false
},
"cachedAt": 1747699200000,
"warnings": ["Could not resolve api_key_id hash: abc123..."]
}
}
Response Fields
| Field | Description |
|---|---|
data.data | Array of result rows. Each row has keys for requested metrics, dimensions, and date__<granularity> (when granularity is set). For classifier_dimensions queries with a single dimension_name, a column is aliased to that name (e.g., category). With two names, each name gets its own column and rows are cross-grouped by both. With dimension_names omitted, rows include clf_dimension_name and clf_dimension_value columns, one row per dimension/value pair. |
data.metadata.query_time_ms | Query execution time in milliseconds |
data.metadata.row_count | Number of rows returned |
data.metadata.truncated | true if results were truncated at the limit |
data.cachedAt | Unix timestamp (ms) when the result was cached. Present when the response was served from cache |
data.warnings | Optional array of non-fatal warnings (e.g., unresolvable api_key_id hashes). The query still executes normally; these inform the caller about filter resolution issues. |
Numeric types: Count metrics (
request_count,tokens_*, etc.) are returned as strings ("1523"). Cost and rate metrics (total_usage,cache_hit_rate, latency, throughput) are returned as numbers (4.27). Parse count values withNumber()orparseInt()before arithmetic.
Label resolution: Dimensions
api_key_id,app,user, andworkspacereturn human-readable labels in data rows (key names, app titles, user names, workspace names), not raw IDs. Sentinel buckets are labelled rather than returned raw:api_key_id-1→Chatroom,app-1→Unknown, and the max-UUIDworkspacesentinel →Unattributed.modelis never relabelled — it stays a permaslug.
CLI Reference
The query-analytics.ts script in the openrouter-analytics skill accepts these flags:
| Flag | Description | Example |
|---|---|---|
--api-key | API key (falls back to OPENROUTER_API_KEY env var) | --api-key sk-or-v1-... |
--metrics | Comma-separated metric names (required) | --metrics request_count,total_usage |
--dimensions | Comma-separated dimension names | --dimensions model,provider |
--granularity | Time bucket size | --granularity day |
--start | Time range start (ISO 8601 UTC, seconds required) | --start 2026-05-01T00:00:00Z |
--end | Time range end (ISO 8601 UTC, seconds required) | --end 2026-05-20T00:00:00Z |
--filter-field | Filter dimension name (first filter; see notes below) | --filter-field model |
--filter-op | Filter operator (first filter) | --filter-op eq |
--filter-value | Filter value (comma-separated for in/not_in) | --filter-value anthropic/claude-sonnet-4 |
--filter-field-N | Dimension name for the Nth additional filter (N = 1–19) | --filter-field-1 provider |
--filter-op-N | Operator for the Nth additional filter | --filter-op-1 eq |
--filter-value-N | Value for the Nth additional filter | --filter-value-1 anthropic |
--order-by | Field to sort by | --order-by total_usage |
--order-dir | Sort direction | --order-dir desc |
--limit | Max total rows (1–10000) | --limit 100 |
--group-limit | Max rows per dimension combination (1–10000). When omitted on time-series queries with dimensions, auto-computed server-side. | --group-limit 50 |
The CLI prints a single JSON object to stdout with two keys — data (the result rows) and metadata:
{
"data": [ { "model": "anthropic/claude-sonnet-4", "total_usage": 4.27 } ],
"metadata": { "query_time_ms": 142, "row_count": 2, "truncated": false }
}
A human-readable stats line (row count, query time, truncation/cache flags) is written to stderr for terminal use only.
When parsing output programmatically, always check
metadata.truncated. Iftrue, the result was capped at--limitand is a partial dataset — increase--limitor paginate before reporting totals/rankings. Dimensionsapi_key_id,user,app, andworkspaceare already resolved to human-readable names in the data rows.
Multi-filter queries: the CLI builds a multi-element filters array (ANDed together) from the unindexed base flag (--filter-field/--filter-op/--filter-value) plus the indexed --filter-field-N/--filter-op-N/--filter-value-N flags. Each filter must supply all three parts (field, op, value); a partial triplet is rejected. Up to 20 filters total (the base flag plus indices 1–19), matching the API cap. Indices may be sparse (e.g. base + -2 with -1 omitted is fine — gaps are skipped, not silently dropped). For a query like model = X AND provider = Y:
npx tsx query-analytics.ts --metrics request_count \
--filter-field model --filter-op eq --filter-value anthropic/claude-sonnet-4 \
--filter-field-1 provider --filter-op-1 eq --filter-value-1 anthropic
Flag-value caveat: the CLI's argument parser treats any token starting with -- as a new flag, so a filter value that begins with -- cannot be passed via the CLI flags. Dimension values (model IDs, provider names, etc.) do not start with --, so this is rarely an issue in practice — but if you need such a value, use the direct curl form below instead.
Direct API Usage (curl)
If you prefer calling the API directly instead of using the scripts:
curl -X POST https://openrouter.ai/api/v1/analytics/query \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"metrics": ["total_usage", "request_count"],
"dimensions": ["model"],
"granularity": "day",
"time_range": {
"start": "2026-05-13T00:00:00Z",
"end": "2026-05-20T00:00:00Z"
},
"order_by": { "field": "total_usage", "direction": "desc" },
"limit": 10,
"group_limit": 7
}'
Query Construction Guide
Aggregates (no time series)
Omit granularity to get a single aggregate row per dimension combination:
{
"metrics": ["total_usage", "request_count"],
"dimensions": ["model"],
"order_by": { "field": "total_usage", "direction": "desc" },
"limit": 10
}
Time Series (with granularity)
Add granularity to get one row per time bucket (and per dimension combination if dimensions are set):
{
"metrics": ["request_count"],
"granularity": "day",
"time_range": {
"start": "2026-05-01T00:00:00Z",
"end": "2026-05-20T00:00:00Z"
}
}
Filtered Queries
Narrow results with filters. Multiple filters are ANDed:
{
"metrics": ["total_usage", "avg_latency"],
"dimensions": ["provider"],
"filters": [
{ "field": "model", "operator": "eq", "value": "anthropic/claude-sonnet-4" }
]
}
Multi-Dimension Queries
Combine up to 2 dimensions for cross-tabulation:
{
"metrics": ["request_count"],
"dimensions": ["model", "provider"],
"order_by": { "field": "request_count", "direction": "desc" },
"limit": 20
}
Error Handling
| Status | Meaning | Action |
|---|---|---|
| 400 | Invalid query (malformed JSON body, bad metric name, too many dimensions, invalid time range) | Check the meta endpoint for valid values. Verify time range start < end and that both timestamps include seconds. Max 2 dimensions, 20 filters. Possible-cache metrics combined with an unsupported dimension, filter, classifier, or minute granularity also return 400. |
| 401 | Invalid or missing API key | Check OPENROUTER_API_KEY is set correctly |
| 403 | Not a management key | The key must be a provisioning/management key. Create one at openrouter.ai/settings/management-keys |
| 408 | Query timed out | Narrow the time range, reduce dimensions, or add filters to scan less data |
| 429 | Rate limited (64 RPM) | Wait and retry |
| 500 | Server error | Retry after a moment |
Time Range Behavior
start and end must be ISO 8601 UTC timestamps that include seconds (2026-05-01T00:00:00Z). Fractional seconds are accepted; minute-precision timestamps and non-UTC offsets are rejected before the query runs.
Some metric/dimension combinations support time ranges up to 367 days (with daily granularity), while others are limited to 31 days. The server resolves this automatically based on the requested metrics and dimensions.
Usage breakdown metrics follow the same pattern: credits_usage, usage_upstream, usage_cache, usage_data, usage_web, and usage_upstream_web support up to 367 days, while openrouter_usage, byok_fees, usage_file, usage_upstream_file, usage_web_fetch, and usage_upstream_web_fetch are limited to 31 days.
Possible-cache metrics (possible_cached_tokens, possible_cache_hit_rate, cache_capture_rate) always read an hourly rollup. They are limited to 31 days regardless of granularity, support only model and provider dimensions and filters, and are rejected with 400 when combined with minute granularity, classifier dimensions, or classifier filters.
hour granularity reads the minute materialized view, so it caps the range at 31 days even for metrics that otherwise allow 367.
Classifier dimensions and classifier filters always force the 31-day time range limit.
If a query times out, try:
- Narrowing the time range
- Removing latency/throughput metrics
- Removing per-generation dimensions (
provider,origin,country,finish_reason, etc.) - Removing classifier dimensions/filters (they are more expensive to compute)
OpenRouter Analytics Schema Discovery
Discover what analytics data is available for querying. The meta endpoint returns live, always-current definitions of metrics, dimensions, filter operators, and granularities.
Prerequisites
- An OpenRouter management key. Management keys are separate from regular API keys — get one at https://openrouter.ai/settings/management-keys
- Pass it via
--api-key <key>or set theOPENROUTER_API_KEYenvironment variable
Discovery Endpoint
GET https://openrouter.ai/api/v1/analytics/meta
Authorization: Bearer sk-or-v1-...
Or via the openrouter-analytics skill scripts:
cd <openrouter-analytics-skill-path>/scripts && npx tsx discover-schema.ts
Response Shape
{
"data": {
"metrics": [
{ "name": "request_count", "display_label": "Request Count", "is_rate": false, "display_format": "number" }
],
"dimensions": [
{ "name": "model", "display_label": "Model" }
],
"operators": [
{ "name": "eq", "value_type": "scalar" }
],
"granularities": [
{ "name": "day", "display_label": "Day" }
]
}
}
Understanding Metrics
Each metric has:
| Field | Meaning |
|---|---|
name | Identifier to use in query requests |
display_label | Human-readable label |
is_rate | Whether this is a ratio/rate (averaged, not summed) |
display_format | How the value should be formatted: number, currency, percent, latency, or throughput |
Time Range Limits
Most volume and cost metrics support time ranges up to 367 days with day or coarser granularity. Latency/throughput metrics, blended_cost_per_million_tokens, and generations-only dimensions (provider, origin, country, data_region, skin, finish_reason, external_user, context_length_bucket, generation_id, session_id, streamed) are limited to 31-day time ranges, as is hour granularity. Possible-cache metrics (possible_cached_tokens, possible_cache_hit_rate, cache_capture_rate) always read an hourly rollup, so they are capped at 31 days too and coarser granularity does not lift that cap.
Exceeding a cap returns 400 with the applicable maximum in the message, not a truncated result. If a query times out instead, try narrowing the time range or removing latency/throughput metrics and per-generation dimensions.
Metric Categories
Volume metrics (how much):
request_count— number of API requests (up to 367 days). Excludes server-tool rows (web search / file-parsing charges recorded alongside a request), so it counts model requests, not billed line itemstokens_total,tokens_prompt,tokens_completion— token counts (up to 367 days)reasoning_tokens— tokens used for extended thinking (up to 367 days)cached_tokens— tokens served from cache (up to 367 days)possible_cached_tokens— prompt tokens that were eligible for caching, whether or not they were cached (31-day limit, hourly rollup only)byok_request_count— number of BYOK requests (up to 367 days). Server-tool rows are excluded when the query reads raw generations (any latency/throughput metric or generations-only dimension in the same request) but still counted when served from the rollups, so the two paths can differ for BYOK traffic that uses server toolsguardrail_invoked_count— count of requests that triggered guardrails (31-day limit)response_cached_count— count of responses served from cache (31-day limit)
Cost metrics (how much money):
total_usage— total cost in USD, including BYOK inference cost (up to 367 days). Computed assum(usage) + sum(byok_usage_inference)so it reflects true spend for both credits and BYOK users.byok_usage— BYOK (bring your own key) inference cost in USD (up to 367 days)credits_usage— all charges billed to OpenRouter credits in USD, including BYOK platform fees (up to 367 days)openrouter_usage— non-BYOK inference spend in USD; excludes requests made with user-provided keys (31-day limit)byok_fees— BYOK platform fees in USD; the platform fee portion ofcredits_usagecharged on BYOK requests (31-day limit).credits_usageincludes both non-BYOK inference charges and these BYOK platform fees.usage_upstream— provider-side (upstream) cost in USD (up to 367 days)usage_cache— cache cost component in USD (up to 367 days)usage_data— data logging cost adjustment in USD; typically negative when a data logging discount applies (up to 367 days)usage_web— web search cost in USD (up to 367 days)usage_upstream_web— provider-side web search cost in USD (up to 367 days)usage_file— file processing cost in USD (31-day limit)usage_upstream_file— provider-side file processing cost in USD (31-day limit)usage_web_fetch— web fetch cost in USD (31-day limit)usage_upstream_web_fetch— provider-side web fetch cost in USD (31-day limit)blended_cost_per_million_tokens— average cost per 1M tokens (prompt + completion), including BYOK inference cost (31-day limit; always reads raw generations). Server-tool spend is excluded from the numerator. A rate metric:nullfor buckets with no tokens, so it cannot be summed across rows.
Performance metrics (how fast; all 31-day limit, milliseconds unless noted). Each family has avg_, p50_, p90_, p95_, and p99_ variants:
*_latency— provider-side time to first token (full response time for non-streamed requests)*_router_latency— time spent in OpenRouter routing before the provider request*_total_time_to_first_token—latency + router_latency, computed over streamed requests only*_generation_time— provider-side generation time*_inter_token_latency— average time between consecutive completion tokens,(generation_time - latency) / (native_tokens_completion - 1), computed over streamed requests with more than one completion token only*_throughput— completion tokens per second, derived fromnative_tokens_completion / generation_time;nullfor requests with no completion tokens
All performance metrics exclude server-tool rows (web search / file-parsing charges recorded alongside a request).
Efficiency metrics (how well):
cache_hit_rate— ratio of cached tokens to prompt tokens (0–1)possible_cache_hit_rate— ratio of cache-eligible prompt tokens to prompt tokens (0–1; 31-day limit, hourly rollup only)cache_capture_rate— ratio of cache-eligible prompt tokens that were actually served from cache (0–1 by construction; 31-day limit, hourly rollup only)guardrail_invoked_rate— ratio of requests that triggered guardrailsresponse_cached_rate— ratio of responses served from cache
Understanding Dimensions
Each dimension has:
| Field | Meaning |
|---|---|
name | Identifier to use in query requests |
display_label | Human-readable label |
Dimensions are what you break down by — "show me spend by model" means dimensions: ["model"].
You can combine up to 2 dimensions in a single query (e.g., ["model", "provider"]).
Label Resolution
Some dimensions have their raw IDs automatically resolved to human-readable labels in query results. Data rows contain the resolved display names directly:
| Dimension | Resolved to |
|---|---|
api_key_id | Key name/label |
app | App title or origin URL |
user | User name or email address |
workspace | Workspace name (deleted workspaces are still named) |
Sentinel buckets get named labels rather than raw values:
api_key_id-1→Chatroom(traffic with no API key, e.g. chatroom requests)app-1→Unknown(rows with no app attribution)workspacemax-UUID sentinel →Unattributed(no workspace could be resolved when the row was written)
All other dimensions (e.g., model, provider, country) are returned as-is without resolution.
Rows with an empty
uservalue represent traffic not attributed to a specific org member (e.g., API keys created at the org level).Rows written before workspace resolution existed carry an all-zero workspace UUID. Grouping folds them into the account's default workspace, and a filter on the default workspace UUID matches them too, so one logical workspace stays one group.
Dimension Categories
Available with all time ranges:
model— the OpenRouter model ID (permaslug)variant— model variant (e.g., standard, extended)api_key_id— which API key made the requestuser— the creator user ID (for org-level queries)workspace— workspace IDapp— application ID
Limited to 31-day time ranges:
generation_id— unique ID for each generation (use to drill down to individual requests, then inspect via theopenrouter-generationsskill)provider— upstream provider nameorigin— request origin/sourcecountry— request countrydata_region— data region the request was served from; empty values report asglobalskin— API skin (which API shape the request used, derived from the request path)finish_reason— why the generation ended (stop, length, etc.)external_user— custom user ID passed by the callercontext_length_bucket— bucketed context length (1K, 10K, 100K, etc.)session_id— session the request belonged to; sessionless requests group as the literalnonestreamed— whether the request was streamed; values are the stringstrueandfalse
Classifier Dimensions
Beyond the standard dimensions above, you can group by classifier dimensions — dynamic labels produced by a user-created classifier (e.g., topic, sentiment, category).
- Use the
classifier_dimensionsrequest field to group by classifier-produced values - At most 2 classifier dimension names per query; naming two cross-groups results by both
- Use the
classifier_filtersrequest field to filter on classifier values - The classifier must belong to your account (validated server-side)
- Classifier dimensions/filters limit the query time range to 31 days
- See the
openrouter-analytics-queryskill for the full request shape
Mapping Questions to Classifier Queries
| Question pattern | Request fields | Notes |
|---|---|---|
| "Spend by topic" | classifier_dimensions: { classifier_id, dimension_names: ["topic"] } + metrics: ["total_usage"] | Single dimension → column aliased to topic |
| "Only billing-related requests" | classifier_filters: { classifier_id, filters: [{ field: "category", operator: "eq", value: "billing" }] } | Filters support eq, neq, in, not_in only |
| "Sentiment breakdown including unclassified" | classifier_dimensions: { classifier_id, dimension_names: ["sentiment"], include_nulls: true } | Includes rows without classification |
Understanding Operators
Filter operators for the filters array in query requests:
| Operator | Value Type | Meaning |
|---|---|---|
eq | scalar | Equals |
neq | scalar | Not equals |
gt | scalar | Greater than |
gte | scalar | Greater than or equal |
lt | scalar | Less than |
lte | scalar | Less than or equal |
in | array | In list |
not_in | array | Not in list |
in and not_in accept an optional include_unset: true to also match rows where the dimension has no value. Only dimensions with an unset bucket support it (api_key_id, app, user); anything else is rejected with 400.
Understanding Granularities
Time bucketing for time-series queries:
| Granularity | Use when |
|---|---|
minute | Last few hours, real-time monitoring |
hour | Last 1–3 days |
day | Last week to 3 months |
week | Last 3–12 months |
month | Year-scale trends |
When no granularity is set, the query returns aggregate totals without time bucketing.
Mapping Questions to Queries
Use this guide to translate natural-language questions into the right metric/dimension/filter combination:
| Question pattern | Metrics | Dimensions | Notes |
|---|---|---|---|
| "How much did I spend?" | total_usage | — | Add granularity for trends |
| "Which models cost the most?" | total_usage | model | Order by total_usage desc |
| "How many requests?" | request_count | — | Add model or api_key_id for breakdown |
| "How many tokens?" | tokens_total | — | Use tokens_prompt / tokens_completion for split |
| "Which provider is fastest?" | avg_latency, p90_latency | provider | 31-day limit |
| "What's my cache hit rate?" | cache_hit_rate | model | Rate metric — shows per-model caching |
| "Which API key uses the most?" | request_count, total_usage | api_key_id | — |
| "Usage over time" | request_count or total_usage | — | Set granularity: "day" |
| "Latency trends" | p90_latency | — | Set granularity: "hour", 31d limit |
| "How smooth is streaming?" | p50_inter_token_latency, p95_inter_token_latency | model or provider | 31-day limit. Streamed requests with more than one completion token only |
| "Usage by country" | request_count | country | 31-day limit |
| "How can I save money?" | total_usage, cache_hit_rate, tokens_total | model | See cost optimization in openrouter-analytics skill |
| "Show me individual requests" | total_usage, tokens_total | generation_id | 31-day limit. Use returned IDs with openrouter-generations skill for full metadata and content |
| "How much BYOK spend?" | byok_usage | model | Up to 367 days |
| "BYOK vs credits split?" | byok_usage, credits_usage | — | Both up to 367 days |
| "BYOK platform fees?" | byok_fees | model | 31-day limit |
| "Non-BYOK inference spend?" | openrouter_usage | model | 31-day limit |
| "How many guardrail triggers?" | guardrail_invoked_count, guardrail_invoked_rate | model | 31-day limit |
| "How many cached responses?" | response_cached_count, response_cached_rate | model | 31-day limit |
| "Where does my spend go?" | usage_upstream, usage_cache, usage_data | — | Full cost breakdown (up to 367 days) |
| "Web search costs?" | usage_web, usage_upstream_web | model | Up to 367 days |
| "File processing costs?" | usage_file, usage_upstream_file | model | 31-day limit |
| "Web fetch costs?" | usage_web_fetch, usage_upstream_web_fetch | model | 31-day limit |
Filter Value Reference
Several dimensions are label-resolved in query results — the response shows human-readable names, but filters must use the underlying ID. Here's where to find each:
| Dimension | Filter value | Where to find it |
|---|---|---|
api_key_id | Numeric ID or 64-char SHA-256 hash | Numeric ID: generation metadata (api_key_id field). Hash: GET /api/v1/keys (key_hash field). Hashes are auto-resolved server-side. If a hash can't be resolved, a sentinel value returns zero rows (no error). |
user | Clerk user ID (e.g. user_abc123) | User settings or org member list — not the display name/email shown in results. |
workspace | Workspace UUID. Filtering on the default workspace UUID also matches legacy rows written before workspace resolution existed. | Workspace settings page or GET /api/v1/workspaces — not the workspace name shown in results. |
app | Numeric app ID | Generation metadata (app_id field) or app settings — not the app title shown in results. |
model | Permaslug (e.g. openai/gpt-4o) | Model page URL or GET /api/v1/models — not the display name. |
Other dimensions (provider, origin, country, finish_reason, external_user, etc.) are not enriched — filter values match what's returned in results.
Constraints
- Maximum 2 dimensions per query
- Maximum 20 filters per query
- Maximum 2 classifier dimension names per query
- Maximum 10 classifier filters per query
- Maximum 10,000 rows returned per query (default 1,000)
group_limit(1–10,000): controls max rows per dimension combination. Auto-computed on time-series queries with dimensions to guarantee full time-window coverage. Set explicitly to cap per-group rows (e.g., top N per model per day).- Most volume/cost metrics: up to 367 days with daily granularity
- Latency/throughput metrics,
blended_cost_per_million_tokens, and per-generation dimensions: up to 31 days - Classifier dimensions/filters: always limited to 31 days
- Minute granularity: only available when the time window is ≤ 3 hours
hourgranularity reads the minute materialized view: 31-day maximum- Possible-cache metrics (
possible_cached_tokens,possible_cache_hit_rate,cache_capture_rate): 31-day maximum,houror coarser granularity, and onlymodel/providerdimensions and filters — any other dimension, filter, classifier, orminutegranularity returns 400 - Rate-limited to 64 requests per minute
OpenRouter Analytics
Query your OpenRouter usage data programmatically. Answer questions like "What was my spend this month?", "Which models cost the most?", and "How can I reduce my bill?" using the Analytics API.
Prerequisites
- An OpenRouter management key (provisioning key). Regular API keys will get a 403.
- Get a management key at https://openrouter.ai/settings/management-keys (separate from the regular API keys page)
- Pass it via
--api-key <key>or set theOPENROUTER_API_KEYenvironment variable
First-Time Setup
cd <skill-path>/scripts && npm install
Decision Tree
| User wants to… | Do this |
|---|---|
| Know what data is available | Run discover-schema.ts to see metrics, dimensions, and filters |
| See spend / usage / volume | Run query-analytics.ts with appropriate metrics |
| Break down by model, provider, API key | Add --dimensions to the query |
| See trends over time | Add --granularity day (or hour, week, month) |
| Reduce costs | Run suggest-queries.ts, find the cost optimization template, execute it |
| Inspect individual generations | Add --dimensions generation_id, then use the openrouter-generations skill for details |
| Break down by classifier labels | Use classifier_dimensions in the request body (see openrouter-analytics-query skill) |
| Filter by classifier labels | Use classifier_filters in the request body (see openrouter-analytics-query skill) |
| Answer a specific question | Map the question → metrics + dimensions, then query |
Workflow
The recommended workflow for answering a user's analytics question:
- Discover — Call
discover-schema.tsto see available metrics and dimensions - Map — Translate the user's question into metrics, dimensions, filters, and time range
- Query — Execute via
query-analytics.ts - Interpret — Analyze the returned data and explain the results
For common questions, suggest-queries.ts provides ready-made query templates.
Discover Available Data
cd <skill-path>/scripts && npx tsx discover-schema.ts
Returns the full schema: metrics, dimensions, filter operators, and granularities.
Filter to a specific section:
npx tsx discover-schema.ts --section metrics
npx tsx discover-schema.ts --section dimensions
npx tsx discover-schema.ts --section operators
npx tsx discover-schema.ts --section granularities
See the openrouter-analytics-schema skill for detailed guidance on interpreting the schema response and mapping user questions to the right metrics and dimensions.
Query Analytics Data
cd <skill-path>/scripts && npx tsx query-analytics.ts --metrics request_count,total_usage
See the openrouter-analytics-query skill for the full parameter reference and query construction guide.
Quick Examples
Spend over the last 7 days, broken down by day:
npx tsx query-analytics.ts --metrics total_usage --granularity day
Top 10 models by cost:
npx tsx query-analytics.ts --metrics total_usage,request_count --dimensions model --order-by total_usage --limit 10
Usage by API key:
npx tsx query-analytics.ts --metrics request_count,tokens_total --dimensions api_key_id --order-by request_count --limit 10
Latency by provider (limited to 31-day range):
npx tsx query-analytics.ts --metrics avg_latency,p90_latency --dimensions provider --order-by p90_latency
Usage cost breakdown (credits, BYOK, upstream, cache, data logging, web search):
npx tsx query-analytics.ts --metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web --granularity day
Common Query Templates
cd <skill-path>/scripts && npx tsx suggest-queries.ts
Returns a list of pre-built query templates for common questions, each with:
- The natural-language question it answers
- The query parameters (metrics, dimensions, filters, time range)
- The CLI flags to pass to
query-analytics.ts - Interpretation guidance (where applicable)
Interpreting Results
The query endpoint returns an array of data rows. Each row is a flat object with keys matching the requested metrics and dimensions.
When interpreting results for the user:
- Spend metrics (
total_usage,credits_usage,openrouter_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_web,usage_upstream_web,usage_file,usage_upstream_file,usage_web_fetch,usage_upstream_web_fetch) are in USD.total_usageincludes BYOK inference cost.usage_datais typically negative (a data logging discount) - Token counts (
tokens_total,tokens_prompt,tokens_completion) are in native model tokens - Latency (
avg_latency,p50_latency, etc.) is in milliseconds.*_latencyis provider-side time to first token;*_router_latencyis OpenRouter routing time;*_total_time_to_first_tokenis their sum over streamed requests only;*_generation_timeis provider-side generation time;*_inter_token_latencyis the average gap between completion tokens over streamed requests with more than one completion token. Each family hasavg_,p50_,p90_,p95_,p99_variants and excludes server-tool rows - Rates (
cache_hit_rate,possible_cache_hit_rate,cache_capture_rate) are 0–1 ratios - Throughput (
avg_throughput,p50_/p90_/p95_/p99_throughput) is completion tokens per second - When
granularityis set, rows include adate__<granularity>field for the time bucket (e.g.,date__day,date__hour,date__month) - Label resolution: dimensions
api_key_id,app,user, andworkspacehave their raw IDs replaced with human-readable names (key name, app title, user name, workspace name) directly in the data rows;generation_idandsession_idreturn raw values; sentinel buckets are labelled (api_key_id-1→Chatroom,app-1→Unknown, the max-UUID workspace →Unattributed) - Truncation: when consuming output programmatically, check
metadata.truncated. Iftrue, the result was capped at--limitand is a partial dataset — raise--limitor paginate before reporting totals or rankings
Cost Optimization Guidance
When the user asks "How can I spend less?" or similar:
- Query top models by spend:
--metrics total_usage,tokens_total,cache_hit_rate,request_count --dimensions model --order-by total_usage --limit 10 - Query cost breakdown:
--metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web,usage_file --granularity dayto see where spend goes - Look for:
- Models with high spend but low
cache_hit_rate— prompt caching can help - Expensive models that could be replaced by cheaper alternatives for specific tasks
- High token counts with low request counts — may indicate oversized prompts
- Models where
reasoning_tokensare a large fraction of total — consider disabling extended thinking if not needed - High
usage_weborusage_filerelative tousage_upstream— web search and file processing add-on costs may be significant
- Models with high spend but low
Drilling Down to Individual Generations
To inspect specific generations or sessions from your analytics results, add generation_id or session_id as a dimension. Both are generations-only dimensions (31-day limit). generation_id returns the unique ID for each generation in the result set. session_id groups and filters sessionless requests as the literal none: the ClickHouse column defaults to an empty string, and the query builder coalesces it to none. Use neq 'none' to exclude sessionless requests; filtering on '' matches nothing.
npx tsx query-analytics.ts --metrics total_usage,tokens_total --dimensions generation_id --order-by total_usage --limit 10
Once you have a generation ID (e.g., gen-aBcDeFgHiJkLmNoPqRsT), use the openrouter-generations skill to get detailed information:
get-generation— Fetch full request metadata: cost breakdown, token counts, latency, provider routing chain, finish reason, and moreget-generation-content— Fetch the stored prompt and completion text (unless Zero Data Retention was enabled)
cd <openrouter-generations-skill-path>/scripts
npx tsx get-generation.ts gen-aBcDeFgHiJkLmNoPqRsT
npx tsx get-generation-content.ts gen-aBcDeFgHiJkLmNoPqRsT
This workflow is useful for identifying your most expensive or slowest requests via analytics, then inspecting the actual prompt/completion to understand why.
API Reference
Both endpoints require a management key via Authorization: Bearer sk-or-v1-....
| Endpoint | Method | Description |
|---|---|---|
/api/v1/analytics/meta | GET | Returns available metrics, dimensions, operators, granularities |
/api/v1/analytics/query | POST | Executes an analytics query and returns structured data |
Full documentation: https://openrouter.ai/docs/api/api-reference/analytics
OpenRouter Benchmarks
Use OpenRouter's unified benchmarks endpoint to answer benchmark-backed model ranking and model-selection questions. The endpoint aggregates Artificial Analysis and Design Arena data and returns citation metadata that should be preserved when reporting results.
Prerequisites
Set OPENROUTER_API_KEY to any valid OpenRouter API key. Benchmarks do not require a management key.
export OPENROUTER_API_KEY=sk-or-v1-...
Decision Tree
| User wants to... | Action |
|---|---|
| See benchmark-ranked models across sources | Call GET /api/v1/benchmarks and preserve source/citation metadata |
| Choose a model for an app/use case | Check whether Artificial Analysis or Design Arena contains a relevant signal; say when no direct benchmark exists |
| Find best coding, intelligence, or agentic models | Use task_type=coding, task_type=intelligence, or task_type=agentic |
| Query Artificial Analysis only | Use source=artificial-analysis |
| Query Design Arena only | Use source=design-arena, plus arena and category when relevant |
| Get raw API-shaped data for integration work | Return the raw data/meta shape from the endpoint |
| Understand all response fields or direct curl usage | Read references/benchmarks-api.md |
Use openrouter-models instead when the user needs pricing, context length, supported parameters, modalities, or provider endpoint performance without asking for benchmark rankings.
For creative writing, storytelling, or editorial apps, this endpoint currently has no direct writing-quality benchmark. Treat Artificial Analysis intelligence_index as a weak general-capability signal, and use agentic_index only if the app performs multi-step planning/revision. Do not imply that Design Arena visual/code categories measure prose quality.
Availability Gate
Do not recommend a benchmark-ranked model until it passes an availability check through the models/endpoints API. Benchmark rows can contain dated or benchmark-specific model_permaslug values that are useful for attribution but are not always the exact routable OpenRouter model ID.
Before recommending a benchmark candidate:
- Check
GET /api/v1/modelsfor an exactidmatch to the benchmarkmodel_permaslug. - If there is no exact
idmatch but a model hascanonical_slugequal to the benchmarkmodel_permaslug, treat the benchmark row as evidence for that model family, not as a directly recommendable ID. Use the model's actualidonly after verifying availability. - Check
GET /api/v1/models/{author}/{slug}/endpointsor useopenrouter-modelsget-endpoints.tsfor provider status. - Prefer candidates with at least one clearly usable endpoint. If all endpoints are degraded, have
uptime_last_30m: 0, or the OpenRouter model page/API indicates the model is unavailable, exclude it from primary recommendations and explain that the benchmark result is not currently actionable. - When availability is ambiguous, say so and recommend a verified available alternative instead of presenting the benchmark leader as the default choice.
Do not rely on endpoint status: 0 alone. Model-level availability signals such as routing error messages, warning messages, zero request limits, empty endpoint lists, or provider-specific access restrictions can make a benchmark leader non-actionable even when one endpoint appears operational. If availability signals disagree, explain the ambiguity and avoid making that model the primary recommendation.
API Usage
Query parameters:
| Flag | Values | Notes |
|---|---|---|
source | artificial-analysis, design-arena | Omitting it returns all sources. |
task_type | coding, intelligence, agentic | Maps to source-specific indices/categories. |
arena | models, builders, agents | Design Arena only; defaults server-side to models. |
category | codecategories, uicomponent, gamedev, 3d, dataviz, image, video, svg, etc. | Design Arena only. |
max_results | positive integer | Maximum number of rows returned by the API. |
Always preserve meta.citation, meta.source_url, and meta.as_of; include attribution when republishing benchmark data.
When results include both sources, do not present them as a single absolute leaderboard: Artificial Analysis indices and Design Arena ELO use different scales. Compare within each source, or rerun with source=artificial-analysis or source=design-arena for a source-specific ranking.
Interpreting Results
- Artificial Analysis rows include
intelligence_index,coding_index, andagentic_index; higher is better. - Design Arena rows include
elo,win_rate,avg_generation_time_ms,arena,category, andtournament_stats; higherelo/win_rateis better, lower generation time is faster. pricing.promptandpricing.completionare USD per token as decimal strings. Multiply by 1,000,000 for per-million-token costs.model_permaslugidentifies the benchmarked model entry. Verify it againstGET /api/v1/modelsbefore using it as a chat/completions model ID.meta.model_countcounts unique models in the response, which can differ fromdata.lengthwhen multiple Design Arena categories are returned.
Direct API Call
curl 'https://openrouter.ai/api/v1/benchmarks?source=artificial-analysis&task_type=coding&max_results=10' \
-H "Authorization: Bearer $OPENROUTER_API_KEY"
Read references/benchmarks-api.md when implementing against the raw API or handling source-specific response shapes.
OpenRouter Decisions
A decision model reads application state and answers typed questions with probabilities, never text. The model judges, code computes. Code owns the workflow and every deterministic step, and the model fills in the judgments code cannot make. It is not a chat model, a coding agent, or a replacement for the LLM that drives one.
Every decision model on OpenRouter speaks the same Decisions API (also served as the TypeSafe-SDK-compatible System One API) and the same primitives, evaluated independently and in parallel within one request.
| Need | Primitive | Returns |
|---|---|---|
| One option from a defined set | choice | choice, probabilities per option, confidence |
| Whether a condition holds | noul | noul, the probability of yes |
| Degree along ordered levels | score | score (probability-weighted position), probabilities per level, confidence |
| Where something is in an image (Jev 1.14 only) | box | box edges as fractions of the image, confidence |
Read references/decisions-api.md when writing a request or reading a response, sending images, or calling through the System One API or TypeSafe SDK. Read references/question-design.md when designing the truth table, state, wording, and criteria, when an answer looks wrong, and for cookbook patterns. Read references/models.md when picking between the decision models the live catalog returns. Read references/decision-model-limits.md whenever a question involves quantities, dates, negation, indirection, or untrusted text, since those are the things a decision model does not do.
Steps
-
Split judgment from computation. A step fits a decision model when its answer is bounded, needs judgment rather than computation, and a probability lets code act, defer, or escalate; a step that must produce text, values, or code, or whose answer already sits in a field code can read, stays as it is. Arithmetic, counting, date ordering, lookups, threshold comparisons, and string or pattern matching that extracts a fact (a path, an ID format, an amount) stay in code, and a value code already holds is never re-asked of the model. A keyword, regex, token-overlap, or similarity heuristic that stands in for a judgment (does this text mean X, is this the same request, is this relevant) is the judgment itself: the decision model replaces it, and its rules move into the question's inclusion and exclusion criteria rather than staying as a pre-filter. When code-side facts settle the action for an input (a path rule, a hard policy, an amount over a cap, an empty input), code returns that action and skips the model for that input. When code parses a value out of free text before comparing it, write the parser against the formats in real inputs and treat a parse miss as its own outcome. Generation goes to a generative model, and a decision model can then pick among its candidates. Done when every remaining item is a judgment that fits one primitive.
-
Pick the primitive per judgment. Mutually exclusive alternatives are a
choice, which is relative and settles which option. An independently testable condition is anoul, which is absolute and can be low for every label, so labels that can co-occur are onenouleach. A degree along one dimension is ascorewhose levels each describe a situation that stands alone. One unordered label from a written rubric is onechoicewhose criteria restate the labels, not severalnouls recombined in code. Ordered levels (a 1 to 5 rating, low to critical) are ascorewhose criteria restate the levels in order, even if code stores the result as a label. Split intonouls only when code combines them with facts of its own or reuses them elsewhere. Comparable per-itemscores ranked in code give graded ranking. Locating a target in an image is abox. Done when each judgment has a primitive and a reason. -
Build the state. Send only what the questions read. Source text, identities, relationships, policies, and current facts, each in a named JSON field, filtered and retrieved in code first. Anything only code uses stays out (flags, counts, computed booleans, and any field that feeds a code-side rule such as a plan tier that caps a score), and code applies that rule to the returned answer. Unrelated material costs accuracy. Done when every field in
stateis read by at least one question and nothing a question needs is missing. -
Write the questions.
instructionsstates the judgment and carries the task's own inclusion and exclusion rules (what counts, what looks similar but does not).criteriadefines the possible answers and reads as an extension of the instructions, asked one way with no double negatives. Ask about the fact, not the text. "Is this change breaking" holds where "Does the description mention breaking changes" and "Does the report state that" both fail, so phrase each question as a property of the thing judged ("Is this review promotional") and let the model infer from the state. Point at a nested field with a backticked path such as`ticket.messages[0].text`. Achoicelists every viable option. When nothing may fit, pair thechoice(or abox) with anoulin the same request that asks whether anything fits, which works better on Jev 1.14 than anoneoption; probe both on other models. When the options are runtime candidates, key the state by option name and name the option in its criterion, never an array index. Question keys are for code and are not sent to the model, so each question carries its full meaning. Independent questions over the same state go in one request. A second request is needed only when an answer decides what state to fetch or which options to offer next. Done when a careful person could answer every question given onlystate,instructions, andcriteria. -
Pick a model and call the Decisions API. The set of decision models changes, so never pick from memory. List what OpenRouter serves right now with
scripts/models.ts(orGET /api/v1/models?output_modalities=decisions) and shortlist by the criteria in references/models.md: the context length holds your real state with room to spare, the price fits the call volume, and the provider footprint fits your availability needs. The catalog cannot tell you how a model answers your questions, so when more than one candidate remains, run the step 7 probe set through every candidate withdecide.ts --compareand pick on the observed answers, latency, and cost. Pin the chosencanonical_slug(or the versionedid) in one config value and never an alias, since an alias can shift probabilities under you. Swapping models later is that config change plus a rerun of step 7. Keep the API key server-side. For request types, validation, and the HTTP and SDK calls, import or copyparseRequestanddecidefrom scripts/lib.ts instead of rewriting them. Done when a request returns one typed answer per question key and the responsemodelstring is logged with the answer. -
Gate in code. Thresholds and business rules live in code as named constants next to the raw
noulandprobabilities. Before probing, anoulgate is>= 0.5(or yes above 0.7, no below 0.3, and the band between routed to the fallback when there is one) and achoiceis itschoicefield, and every stricter number waits for step 7. Achoiceorboxpaired with a presencenoulis read only in thatnoul's yes branch; the no branch takes the no-match outcome, the uncertain band (when there is one) takes the named fallback, and the truth table names all three actions. Compare in the direction the question asks, sois_breaking.noul >= Tmeans breaking and "safe" is theelse. A single gate fits only when the code path has two outcomes. When it already has a fallback (a review queue, a default, a bigger model), keep it as the outcome for probabilities near the gate and set that band's width in step 7. Useconfidenceonly when such a fallback is cheaper than a wrong answer. It measures how concentrated the distribution is, not whether the answer is correct or the action is authorized. Anoulnear 0.5 means yes and no are similarly likely, not medium intensity. A threshold does not carry from anoulto achoiceor from one model to another, andP(yes)from one question plusP(not yes)from another need not sum to 1. Done when every threshold is a named constant with the consequence of each mistake written next to it. -
Probe before you trust. Run the real questions over representative inputs with the bundled script and read the raw probabilities. Cover the clear cases, an ambiguous case, a no-match case, an empty or off-topic input, a negated statement, and adversarial text that argues for its own classification. Set thresholds from those numbers, not from cookbook defaults, and repeat when the model changes. Done when each edge case produces the routing you want and every threshold traces to an observed number.
cd <skill-path>/scripts && npm install
npx tsx models.ts request.json # live catalog with context, price, providers, and fit for this request
npx tsx decide.ts request.json --model <model-id> # raw HTTP to one model
npx tsx decide.ts request.json --sdk # through @openrouter/sdk
npx tsx decide.ts request.json --compare # same request to every pinned model in the catalog
request.json holds { "state", "questions" } and optionally "model". --model overrides the request's model, then DECISION_MODEL from the environment fills in when neither is set. The scripts print the answers, resolved model version, latency, and cost, and --compare prints one entry per model with the error inline when a model fails.
openrouter-generations
Retrieve detailed metadata and stored content for individual OpenRouter generations. Use this skill when you need to inspect a specific request — its cost, latency, token usage, provider routing, or the actual prompt/completion text.
Prerequisites
- Any valid OpenRouter API key (regular or management key). Get one at openrouter.ai/settings/keys.
- Pass it via
--api-key <key>or set theOPENROUTER_API_KEYenvironment variable - Generation IDs look like
gen-1234567890orgen-aBcDeFgHiJkLmNoPqRsT.
First-Time Setup
cd <skill-path>/scripts && npm install
Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/generation | GET | Request metadata and usage (tokens, cost, latency, model, provider) |
/api/v1/generation/content | GET | Stored prompt and completion text |
Both take a single query parameter: id (the generation ID).
Full API reference: openrouter.ai/docs/api/api-reference/generations/get-generation
Workflow
1. Get generation metadata
Retrieves everything about a generation except the actual prompt/completion text:
cd <skill-path>/scripts && npx tsx get-generation.ts gen-1234567890
npx tsx get-generation.ts --id gen-1234567890 --json
What you get back:
- Model & routing:
model,provider_name,router,service_tier - Tokens:
tokens_prompt,tokens_completion,native_tokens_reasoning,native_tokens_cached - Cost:
total_cost,usage,upstream_inference_cost,cache_discount - Performance:
latency,generation_time,moderation_latency - Status:
finish_reason,streamed,cancelled,is_byok - Context:
created_at,app_id,external_user,session_id,request_id - Provider chain:
provider_responsesarray showing fallback attempts with per-provider latency and status
2. Get generation content
Retrieves the stored prompt and completion:
cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-1234567890
npx tsx get-generation-content.ts --id gen-1234567890 --json
What you get back:
- Input:
prompt(raw text) and/ormessages(array of{role, content}) - Output:
completion(the model's response) andreasoning(chain-of-thought, if applicable)
Note: Content is only available if the generation was not made with Zero Data Retention (ZDR) enabled. If ZDR was on, this endpoint returns empty/null content.
Direct API Usage (curl)
Get metadata
curl -G https://openrouter.ai/api/v1/generation \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-d id=gen-1234567890
Get content
curl -G https://openrouter.ai/api/v1/generation/content \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-d id=gen-1234567890
Response Schemas
Metadata response (/api/v1/generation)
{
"data": {
"id": "gen-3bhGkxlo4XFrqiabUM7NDtwDzWwG",
"api_type": "completions",
"model": "openai/gpt-4o",
"provider_name": "OpenAI",
"created_at": "2024-07-15T23:33:19.433273+00:00",
"tokens_prompt": 10,
"tokens_completion": 25,
"native_tokens_reasoning": 5,
"native_tokens_cached": 3,
"total_cost": 0.0015,
"usage": 0.0015,
"upstream_inference_cost": 0.0012,
"latency": 1250,
"generation_time": 1200,
"finish_reason": "stop",
"streamed": true,
"is_byok": false,
"cancelled": false,
"router": "openrouter/auto",
"service_tier": "priority",
"provider_responses": [
{
"provider_name": "OpenAI",
"model_permaslug": "openai/gpt-4o",
"status": 200,
"latency": 1200,
"is_byok": false
}
]
}
}
Content response (/api/v1/generation/content)
{
"data": {
"input": {
"prompt": "What is the meaning of life?",
"messages": [
{
"content": "What is the meaning of life?",
"role": "user"
}
]
},
"output": {
"completion": "The meaning of life is a philosophical question...",
"reasoning": null
}
}
}
Common Use Cases
Debug a failed generation
# Check what happened — look at finish_reason, provider_responses, and cancelled
cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123 --json
Look for:
finish_reason="length"means the model hit max tokensfinish_reason="content_filter"means content was filteredcancelled=truemeans the request was cancelled by the clientprovider_responseswith multiple entries means fallbacks occurred
Check cost of a specific request
cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123
Check total_cost (what you were charged) vs upstream_inference_cost (what the provider charged OpenRouter).
Review what was actually sent/received
cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-abc123
Useful for debugging unexpected outputs — verify the actual prompt sent and completion received.
Trace a multi-generation session
If you have a request_id or session_id from one generation, you can find related generations via the analytics query endpoint (see openrouter-analytics skill).
Error Handling
| Status | Meaning |
|---|---|
| 401 | Invalid or missing API key |
| 403 | You don't have access to this generation (belongs to another user) |
| 404 | Generation ID not found |
| 429 | Rate limited — wait and retry |
| 500 | Server error — retry |
| 502 | Upstream failure — retry |
Key Fields Reference
Metadata fields
| Field | Type | Description |
|---|---|---|
id | string | Generation ID (gen-...) |
model | string | Model permaslug (e.g., openai/gpt-4o) |
provider_name | string|null | Provider that served the request |
api_type | string | One of: completions, embeddings, rerank, tts, stt, video |
tokens_prompt | int|null | Prompt token count |
tokens_completion | int|null | Completion token count |
native_tokens_reasoning | int|null | Reasoning/thinking tokens |
native_tokens_cached | int|null | Cached input tokens |
total_cost | number | Total cost in USD |
usage | number | Usage amount in USD |
upstream_inference_cost | number|null | Provider's cost in USD |
cache_discount | number|null | Discount from caching |
latency | number|null | Total latency in ms |
generation_time | number|null | Model generation time in ms |
moderation_latency | number|null | Moderation check time in ms |
finish_reason | string|null | Why generation stopped (stop, length, content_filter, etc.) |
native_finish_reason | string|null | Raw finish reason from provider |
streamed | bool|null | Whether response was streamed |
is_byok | bool | Whether user's own provider key was used |
cancelled | bool|null | Whether request was cancelled |
app_id | int|null | OAuth app ID |
external_user | string|null | External user identifier (X-External-User header) |
session_id | string|null | Session grouping ID |
request_id | string|null | Request grouping ID (all gens from one API call) |
router | string|null | Router used (e.g., openrouter/auto) |
service_tier | string|null | Provider service tier |
web_search_engine | string|null | Search engine used (e.g., exa, firecrawl) |
num_search_results | int|null | Number of search results included |
provider_responses | array|null | Provider attempt chain with per-provider latency/status |
Content fields
| Field | Type | Description |
|---|---|---|
data.input.prompt | string|null | Raw prompt text |
data.input.messages | array|null | Messages array ([{role, content}]) |
data.output.completion | string|null | Model's completion text |
data.output.reasoning | string|null | Chain-of-thought reasoning |
OpenRouter Images
Generate images from text prompts and edit existing images via OpenRouter's dedicated Image API (POST /api/v1/images). The skill also discovers which models exist and which parameters each one accepts, so you pick a valid model and options instead of guessing.
Prerequisites
The OPENROUTER_API_KEY environment variable must be set. Get a key at https://openrouter.ai/keys
Discovery (discover.ts) is public and works without a key; generation and editing require one.
First-Time Setup
cd <skill-path>/scripts && npm install
Decision Tree
Pick the right script based on what the user is asking:
| User wants to... | Script | Example |
|---|---|---|
| See which image models exist and what they support | discover.ts | "What image models can I use?" |
| Check the exact params a specific model accepts | discover.ts <model> | "Does seedream support 4K?" |
| Generate an image from a text description | generate.ts "prompt" | "Create an image of a sunset over mountains" |
| Generate with specific options | generate.ts "prompt" --aspect-ratio 16:9 | "Make a wide landscape image of a forest" |
| Generate with a different model | generate.ts "prompt" --model <id> | "Generate using gemini 3.1 flash lite image" |
| Edit or modify an existing image | edit.ts path "prompt" | "Make the sky purple in photo.png" |
| Transform an image with instructions | edit.ts path "prompt" | "Add a party hat to the animal in this image" |
Discover Capabilities First
Different models accept different parameters. Rather than hardcoding flags and hitting 400s, discover what's available before generating.
List every image model with a compact capability summary:
cd <skill-path>/scripts && npx tsx discover.ts
Each entry reports the model id, input_modalities / output_modalities (image input means it supports editing / image-to-image), supports_streaming, and a supported_parameters map — the union of what any endpoint of that model accepts.
Inspect one model's definitive per-endpoint capabilities:
cd <skill-path>/scripts && npx tsx discover.ts bytedance-seed/seedream-4.5
This calls GET /api/v1/images/models/{author}/{slug}/endpoints and returns, per provider endpoint:
| Field | Meaning |
|---|---|
provider_name / provider_slug | The serving provider. Use provider_slug as the key in --provider-options. |
supported_parameters | The exact parameters this endpoint accepts, with allowed values. |
allowed_passthrough_parameters | Provider-specific keys you can pass under --provider-options (e.g. steps, guidance). |
supports_streaming | Whether this endpoint streams. |
pricing | Per-image / per-token pricing lines. |
Capability values print as readable strings: an enum shows as 1K | 2K | 4K, a range as 0–100, a boolean as supported. A parameter that's absent is unsupported — don't send it.
Generate Image
Create a new image from a text prompt:
cd <skill-path>/scripts && npx tsx generate.ts "a red panda wearing sunglasses"
cd <skill-path>/scripts && npx tsx generate.ts "a futuristic cityscape at night" --aspect-ratio 16:9
cd <skill-path>/scripts && npx tsx generate.ts "pixel art of a dragon" --output dragon.png
cd <skill-path>/scripts && npx tsx generate.ts "a watercolor painting" --model google/gemini-3.1-flash-lite-image --resolution 1K
Edit Image
Modify an existing image with a text prompt. The source image is sent as an image-to-image reference (input_references), so use a model whose input_modalities include image — check with discover.ts <model>.
cd <skill-path>/scripts && npx tsx edit.ts photo.png "make the sky purple"
cd <skill-path>/scripts && npx tsx edit.ts avatar.jpg "add a party hat" --output avatar-hat.png
cd <skill-path>/scripts && npx tsx edit.ts scene.png "convert to watercolor style" --model google/gemini-3.1-flash-lite-image
Supported input formats: .png, .jpg, .jpeg, .webp, .gif
Options
Both generate.ts and edit.ts accept the same flags. Only pass parameters the target model supports — verify with discover.ts <model>.
| Flag | Description | Default |
|---|---|---|
--model <id> | OpenRouter model ID | google/gemini-3.1-flash-image-preview |
--output <path> | Output file path | image-YYYYMMDD-HHmmss.png |
--aspect-ratio <r> | Aspect ratio (e.g. 16:9, 1:1, 4:3) | Model default |
--resolution <t> | Resolution tier (512, 1K, 2K, 4K) | Model default |
--size <s> | Shorthand: a tier (2K) or explicit pixels (2048x2048) | Model default |
--quality <q> | auto, low, medium, or high | Model default |
--output-format <f> | png, jpeg, webp, or svg (vector models) | Model default |
--background <b> | auto, transparent, or opaque | Model default |
--output-compression <n> | Compression 0–100 for webp/jpeg | Model default |
--n <count> | Number of images to generate (1–10, provider permitting) | 1 |
--seed <int> | Seed for deterministic generation (where supported) | Random |
--provider-options <json> | Provider-specific passthrough, keyed by provider_slug | None |
--provider-options takes a JSON object keyed by provider slug, using keys from that endpoint's allowed_passthrough_parameters:
cd <skill-path>/scripts && npx tsx generate.ts "a dramatic portrait" \
--model black-forest-labs/flux.2-pro \
--provider-options '{"black-forest-labs": {"steps": 40, "guidance": 3}}'
Output Format
generate.ts
{
"model": "google/gemini-3.1-flash-image-preview",
"prompt": "a red panda wearing sunglasses",
"images_saved": ["/absolute/path/to/image-20260305-143022.png"],
"count": 1
}
edit.ts
{
"model": "google/gemini-3.1-flash-image-preview",
"source_image": "photo.png",
"prompt": "make the sky purple",
"images_saved": ["/absolute/path/to/image-20260305-143055.png"],
"count": 1
}
The generation cost (USD) is printed to stderr when the API reports it. When --n requests multiple images, each is saved with a -1, -2, … suffix.
API Response Shapes
Generation uses POST /api/v1/images. See the Image Generation guide for full request/response details.
Images come back base64-encoded in a data array. For raster PNG output, media_type is omitted; vector outputs (e.g. SVG) include it, and the saved file extension follows it:
{
"created": 1748372400,
"data": [{ "b64_json": "<base64-encoded image data>" }],
"usage": { "prompt_tokens": 0, "completion_tokens": 4175, "total_tokens": 4175, "cost": 0.04 }
}
Using a Different Model
The default model is google/gemini-3.1-flash-image-preview (Nano Banana 2). To use another, pass --model <id> with any image model ID (e.g. google/gemini-3.1-flash-lite-image). Run discover.ts to browse image models and discover.ts <model> to confirm which parameters and providers it supports before generating.
Presenting Results
- After generating or editing, display the saved image to the user
- Include the model used and, when reported, the generation cost (printed to stderr)
- If multiple images are returned, show all of them
- When the user doesn't specify an output path, tell them where the file was saved
- For edit operations, mention the source image that was modified
OpenRouter Models
Discover, search, and compare the 300+ AI models available on OpenRouter. Query live data including pricing, context lengths, per-provider latency and uptime, throughput, supported modalities, and supported parameters.
Prerequisites
The OPENROUTER_API_KEY environment variable is optional for most scripts. It is only required for get-endpoints.ts (provider performance data). Get a key at https://openrouter.ai/keys
First-Time Setup
cd <skill-path>/scripts && npm install
Decision Tree
Pick the right script based on what the user is asking:
| User wants to... | Script | Example |
|---|---|---|
| See all available models | list-models.ts | "What models does OpenRouter have?" |
| Find recently added models | list-models.ts --sort newest | "What are the newest models?" |
| Find cheapest models | list-models.ts --sort price | "What's the cheapest model?" |
| Find highest throughput models | list-models.ts --sort throughput | "Which models have the most output capacity?" |
| Find models in a category | list-models.ts --category X | "Best programming models?" |
| Search by name | search-models.ts "query" | "Do they have Claude?" |
| Resolve an informal model name | resolve-model.ts "query" | "Use the nano banana 2.0 model" |
| Find image-capable models | search-models.ts --modality image | "Which models accept images?" |
| Compare specific models | compare-models.ts A B | "Compare Claude vs GPT-4o" |
| Compare by throughput | compare-models.ts A B --sort throughput | "Which has higher throughput, Claude or GPT-4o?" |
| Check provider performance | get-endpoints.ts "model-id" | "Which provider is fastest for Claude?" |
| Find fastest provider | get-endpoints.ts "model-id" --sort throughput | "Fastest provider for Claude Sonnet?" |
| Find lowest-latency provider | get-endpoints.ts "model-id" --sort latency | "Lowest latency provider for GPT-4o?" |
| Check model availability | get-endpoints.ts "model-id" | "Is Claude Sonnet 4 up right now?" |
Resolve Model
Resolve an informal or vague model name to an exact OpenRouter model ID using fuzzy matching:
cd <skill-path>/scripts && npx tsx resolve-model.ts "claude sonnet"
cd <skill-path>/scripts && npx tsx resolve-model.ts "gpt 4o mini"
cd <skill-path>/scripts && npx tsx resolve-model.ts "llama 3.1"
Results include a confidence level and score:
| Confidence | Score | Action |
|---|---|---|
high (≥0.85) | Use the model directly — the match is unambiguous | |
medium (≥0.55) | Confirm with the user before proceeding | |
low (≥0.30) | Suggest the matches and ask the user to clarify |
Two-step workflow: First resolve the informal name with resolve-model.ts, then feed the resolved id into other scripts (compare-models.ts, get-endpoints.ts, etc.).
List Models
cd <skill-path>/scripts && npx tsx list-models.ts
Filter by Category
Server-side category filtering:
cd <skill-path>/scripts && npx tsx list-models.ts --category programming
Categories: programming, roleplay, marketing, marketing/seo, technology, science, translation, legal, finance, health, trivia, academia
Sort Results
cd <skill-path>/scripts && npx tsx list-models.ts --sort newest # Recently added first
cd <skill-path>/scripts && npx tsx list-models.ts --sort price # Cheapest first
cd <skill-path>/scripts && npx tsx list-models.ts --sort context # Largest context first
cd <skill-path>/scripts && npx tsx list-models.ts --sort throughput # Most output tokens first
Models with upcoming expiration_date values trigger a stderr warning.
Search Models
cd <skill-path>/scripts && npx tsx search-models.ts "claude"
cd <skill-path>/scripts && npx tsx search-models.ts --modality image
cd <skill-path>/scripts && npx tsx search-models.ts "gpt" --modality text
Modalities: text, image, audio, file
Compare Models
Compare two or more models side-by-side with pricing in per-million-tokens format. Uses exact ID matching — openai/gpt-4o matches only that model, not variants like gpt-4o-mini.
cd <skill-path>/scripts && npx tsx compare-models.ts "anthropic/claude-sonnet-4" "openai/gpt-4o"
cd <skill-path>/scripts && npx tsx compare-models.ts "anthropic/claude-sonnet-4" "openai/gpt-4o" "google/gemini-2.5-pro" --sort price
Sort options: price (cheapest first), context (largest first), speed/throughput (most output tokens first)
Provider Performance (Endpoints)
Get per-provider latency, uptime, and throughput for any model:
cd <skill-path>/scripts && npx tsx get-endpoints.ts "anthropic/claude-sonnet-4"
cd <skill-path>/scripts && npx tsx get-endpoints.ts "anthropic/claude-sonnet-4" --sort throughput
cd <skill-path>/scripts && npx tsx get-endpoints.ts "openai/gpt-4o" --sort latency
Sort options: throughput (fastest tokens/sec first), latency (lowest p50 ms first), uptime (most reliable first), price (cheapest first)
Returns for each provider:
- Latency (p50/p75/p90/p99 in ms) — median to worst-case response times
- Throughput (p50/p75/p90/p99 tokens/sec) — generation speed
- Uptime — percentage over the last 30 minutes
- Status —
operationalordegraded - Provider-specific pricing — some providers offer discounts
- Supported parameters — varies by provider (some don't support all features)
API Response Shapes
GET /api/v1/models returns { data: Model[] }. For full field reference, see the Models reference.
Query parameters (all optional):
| Parameter | Example | Effect |
|---|---|---|
category | ?category=programming | Server-side category filter |
supported_parameters | ?supported_parameters=tools | Only models supporting this parameter |
Tips for working with the response:
- To check if a model supports a feature, use
model.supported_parameters(e.g..includes("tools")), or filter server-side with?supported_parameters=tools. - To check modalities, use
model.architecture.input_modalities/model.architecture.output_modalities. - Pricing values are per-token in USD as strings — multiply by 1,000,000 for per-million-token pricing.
knowledge_cutoffandexpiration_dateare date strings or null.links.detailspoints to the per-provider endpoints API for that model.GET /api/v1/models/{author}/{slug}/endpointsreturns{ data: { id, name, endpoints: Endpoint[] } }.- Endpoint
status:0= operational, non-zero = degraded. - Endpoint
latency_last_30m/throughput_last_30m: percentile objects withp50,p75,p90,p99.
Script Output Formats
The scripts below reformat the raw API data. When calling the API directly (e.g. via fetch), refer to the OpenAPI spec for field names.
list-models.ts / search-models.ts
A subset of the raw API fields — the scripts run formatModel() which drops canonical_slug, hugging_face_id, default_parameters, knowledge_cutoff, and links. If you need those fields, call the API directly.
compare-models.ts
{
"id": "anthropic/claude-sonnet-4",
"name": "Anthropic: Claude Sonnet 4",
"context_length": 1000000,
"max_completion_tokens": 64000,
"per_request_limits": null,
"pricing_per_million_tokens": {
"prompt": "$3.00",
"completion": "$15.00",
"cached_input": "$0.30"
},
"modalities": { "input": ["text", "image"], "output": ["text"] },
"supported_parameters": ["max_tokens", "temperature", "..."],
"is_moderated": false
}
get-endpoints.ts
{
"model_id": "anthropic/claude-sonnet-4",
"model_name": "Anthropic: Claude Sonnet 4",
"total_providers": 5,
"endpoints": [
{
"provider": "Anthropic",
"tag": "anthropic",
"status": "operational",
"uptime_30m": "100.00%",
"latency_30m_ms": { "p50": 800, "p75": 1200, "p90": 2000, "p99": 5000 },
"throughput_30m_tokens_per_sec": { "p50": 45, "p75": 55, "p90": 65, "p99": 90 },
"context_length": 1000000,
"max_completion_tokens": 64000,
"pricing_per_million_tokens": { "prompt": "$3.00", "completion": "$15.00", "cached_input": "$0.30" },
"supports_implicit_caching": true,
"supported_parameters": ["max_tokens", "temperature", "tools", "..."]
}
]
}
Key Fields
| Field | Meaning |
|---|---|
pricing.prompt / pricing.completion | Cost per token in USD. Multiply by 1,000,000 for per-million-token pricing |
context_length | Max total tokens (input + output) |
top_provider.max_completion_tokens | Max output tokens from the best provider |
top_provider.is_moderated | Whether content moderation is applied |
per_request_limits | Per-request token limits (when non-null) |
supported_parameters | API parameters the model accepts (e.g., tools, structured_outputs, reasoning, web_search_options) |
created | Unix timestamp — use for sorting by recency |
expiration_date | Non-null means the model is being deprecated |
latency_30m_ms.p50 | Median response latency over last 30 min |
throughput_30m_tokens_per_sec.p50 | Median generation speed over last 30 min |
uptime_30m | Provider availability percentage over last 30 min |
Presenting Results
- When a user mentions a model by informal name, use
resolve-model.tsfirst, then feed the resolvedidinto other scripts - Convert pricing to per-million-tokens format for readability
- When comparing, use a markdown table with models as columns
- For provider endpoints, highlight the fastest (lowest p50 latency) and most reliable (highest uptime) providers
- Call out notable supported parameters:
tools,structured_outputs,reasoning,web_search_options - Note cache pricing when available — it can cut input costs 90%+
- Flag models with
expiration_dateas deprecated - When a model has multiple providers at different prices, mention the cheapest option
Sign In with OpenRouter
Add OAuth login to any web app. Users authorize on OpenRouter and your app receives an API key — no client registration, no backend, no secrets. Works with any framework.
Live demo: openrouterteam.github.io/sign-in-with-openrouter
Decision Tree
| User wants to… | Do this |
|---|---|
| Add sign-in / login to a web app | Follow the full PKCE flow + button guidance below |
| Get an API key programmatically (no UI) | Just implement the PKCE flow — skip the button section |
| Use the OpenRouter SDK after auth | Do PKCE here for the key, then see openrouter-typescript-sdk skill for callModel/streaming |
OAuth PKCE Flow
No client ID or secret — the PKCE challenge is the only proof of identity.
Step 1: Generate verifier and challenge
code_verifier = base64url(32 random bytes)
code_challenge = base64url(SHA-256(code_verifier))
- Use
crypto.getRandomValues(new Uint8Array(32))for the random bytes - base64url encoding: standard base64, then replace
+→-,/→_, strip trailing= - Store
code_verifierinsessionStorage(notlocalStorage) — so the verifier doesn't persist after the tab closes or leak to other tabs (security: the verifier is a one-time secret)
Step 2: Redirect to OpenRouter
https://openrouter.ai/auth?callback_url={url}&code_challenge={challenge}&code_challenge_method=S256
| Param | Value |
|---|---|
callback_url | Your app's URL (where the user returns after auth) |
code_challenge | The S256 challenge from Step 1 |
code_challenge_method | Always S256 |
Step 3: Handle the redirect back
User returns to your callback_url with ?code= appended. Extract the code query parameter.
Important: Before processing ?code=, check that a code_verifier exists in sessionStorage. Other routes or third-party code might use ?code= query params for unrelated purposes — a hasOAuthCallbackPending() guard ensures you only consume codes that belong to your OAuth flow.
Step 4: Exchange code for API key
POST https://openrouter.ai/api/v1/auth/keys
Content-Type: application/json
{
"code": "<code from query param>",
"code_verifier": "<verifier from sessionStorage>",
"code_challenge_method": "S256"
}
→ { "key": "sk-or-..." }
Remove the verifier from sessionStorage before or after the exchange.
Step 5: Store the key and clean up
- Store
keyinlocalStorage - Clean the URL:
history.replaceState({}, "", location.pathname)to remove?code= - Cross-tab sync: Listen for
storageevents on the API key'slocalStorageentry so other tabs update when the user signs in or out
Auth Module Reference
Drop-in module implementing the full PKCE flow. Reduces risk of getting base64url encoding, sessionStorage handling, or the key exchange wrong.
// lib/openrouter-auth.ts
const STORAGE_KEY = "openrouter_api_key";
const VERIFIER_KEY = "openrouter_code_verifier";
type AuthListener = () => void;
const listeners = new Set<AuthListener>();
export const onAuthChange = (fn: AuthListener) => { listeners.add(fn); return () => listeners.delete(fn); };
const notify = () => listeners.forEach((fn) => fn());
// Cross-tab sync: other tabs update when user signs in/out
if (typeof window !== "undefined") {
window.addEventListener("storage", (e) => { if (e.key === STORAGE_KEY) notify(); });
}
export const getApiKey = (): string | null =>
typeof window !== "undefined" ? localStorage.getItem(STORAGE_KEY) : null;
export const setApiKey = (key: string) => { localStorage.setItem(STORAGE_KEY, key); notify(); };
export const clearApiKey = () => { localStorage.removeItem(STORAGE_KEY); notify(); };
// Guard: only process ?code= if we initiated an OAuth flow in this tab
export const hasOAuthCallbackPending = (): boolean =>
typeof window !== "undefined" && sessionStorage.getItem(VERIFIER_KEY) !== null;
function generateCodeVerifier(): string {
const bytes = new Uint8Array(32);
crypto.getRandomValues(bytes);
return btoa(String.fromCharCode(...bytes))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}
async function computeS256Challenge(verifier: string): Promise<string> {
const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
return btoa(String.fromCharCode(...new Uint8Array(digest)))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}
export async function initiateOAuth(callbackUrl?: string): Promise<void> {
const verifier = generateCodeVerifier();
sessionStorage.setItem(VERIFIER_KEY, verifier);
const challenge = await computeS256Challenge(verifier);
const url = callbackUrl ?? window.location.origin + window.location.pathname;
window.location.href = `https://openrouter.ai/auth?${new URLSearchParams({
callback_url: url, code_challenge: challenge, code_challenge_method: "S256",
})}`;
}
export async function handleOAuthCallback(code: string): Promise<void> {
const verifier = sessionStorage.getItem(VERIFIER_KEY);
if (!verifier) throw new Error("Missing code verifier");
sessionStorage.removeItem(VERIFIER_KEY);
const res = await fetch("https://openrouter.ai/api/v1/auth/keys", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ code, code_verifier: verifier, code_challenge_method: "S256" }),
});
if (!res.ok) throw new Error(`Key exchange failed (${res.status})`);
const { key } = await res.json();
setApiKey(key);
}
Sign-in Button
Build a button component that calls initiateOAuth() on click. Include the OpenRouter logo and provide multiple visual variants.
OpenRouter Logo SVG
<svg viewBox="0 0 401.4 293.7" fill="currentColor">
<path d="M303.9475,17.19926c42.79734,0,77.48933,34.69327,77.48933,77.48933s-34.69199,77.48933-77.48933,77.48933l76.86166,76.86244c9.76367,9.76313,2.84903,26.45667-10.95697,26.45667h-220.88335c-71.32686,0-129.14889-57.82202-129.14889-129.14889S77.64197,17.19926,148.96884,17.19926h154.97866ZM148.96884,68.85881c-42.79607,0-77.48933,34.69327-77.48933,77.48933s34.69327,77.48933,77.48933,77.48933,77.48933-34.69327,77.48933-77.48933-34.69327-77.48933-77.48933-77.48933Z"/>
</svg>
fill="currentColor" inherits the button's text color. To use the official brand colors instead, apply the light-mode purple and dark-mode lime:
<svg viewBox="0 0 401.4 293.7" class="fill-[#7624F4] dark:fill-[#C8FF00]">...</svg>
| Mode | Fill |
|---|---|
| Light backgrounds | #7624F4 |
| Dark backgrounds | #C8FF00 |
Variants (Tailwind)
Recommended classes for visual consistency with the reference implementation:
| Variant | Classes |
|---|---|
default | rounded-lg border border-neutral-300 bg-white text-neutral-900 shadow-sm hover:bg-neutral-50 |
minimal | text-neutral-700 underline-offset-4 hover:underline |
branded | rounded-lg bg-neutral-900 text-white shadow hover:bg-neutral-800 |
icon | Same as default + aspect-square (logo only, no text) |
cta | rounded-xl bg-neutral-900 text-white shadow-lg hover:bg-neutral-800 hover:scale-[1.02] active:scale-[0.98] |
Sizes
| Size | Classes |
|---|---|
sm | h-8 px-3 text-xs |
default | h-10 px-5 text-sm |
lg | h-12 px-8 text-base |
xl | h-14 px-10 text-lg |
All variants use: inline-flex items-center justify-center gap-2 font-medium transition-all cursor-pointer disabled:opacity-50
Show a loading indicator while the key exchange is in progress. Default label: "Sign in with OpenRouter".
Dark mode
For dark mode support, add dark variants: swap light backgrounds to dark (dark:bg-neutral-900 dark:text-white) and vice versa for branded/cta (dark:bg-white dark:text-neutral-900).
Using the API Key
const response = await fetch("https://openrouter.ai/api/v1/responses", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "openai/gpt-4o-mini",
input: [{ type: "message", role: "user", content: "Hello!" }],
}),
});
For the type-safe SDK approach (callModel, streaming, tool use), see the openrouter-typescript-sdk skill.
Resources
- OAuth PKCE guide — full parameter reference and key management
- Authentication guide — API key usage and Bearer token setup
- Live demo — interactive button playground
- OpenRouter TypeScript SDK —
callModelpattern for completions and streaming
OpenRouter Speech-to-Text
Transcribe audio via POST /api/v1/audio/transcriptions using curl. Requires OPENROUTER_API_KEY (get one at https://openrouter.ai/keys). If unset, stop and ask.
This endpoint is not OpenAI-compatible. The body is JSON with base64 audio under input_audio: { data, format } — not multipart/form-data with a file field the way OpenAI's /v1/audio/transcriptions works. Do not point the OpenAI SDK at this endpoint; it will send the wrong shape. Use curl, fetch, or requests directly.
One call, JSON back
Both request and response are JSON. The response body carries:
text— the transcript.usage— always includescost. Providers additionally report eithersecondsof audio billed or a token breakdown (total_tokens,input_tokens,output_tokens), depending on how they price the request. Don't assume both are present.
Sample response (duration-priced provider, e.g. google/chirp-3):
{
"text": "I used to rule the world.",
"usage": {
"seconds": 20,
"cost": 0.005333
}
}
Sample response (token-priced provider):
{
"text": "Hello, this is a test of speech-to-text transcription.",
"usage": {
"total_tokens": 113,
"input_tokens": 83,
"output_tokens": 30,
"cost": 0.000508
}
}
Drop-in workflow
#!/usr/bin/env bash
set -euo pipefail
MODEL="google/chirp-3"
FORMAT="wav" # wav, mp3, flac, m4a, ogg, webm, aac
AUDIO="audio.wav"
BODY=$(mktemp)
PAYLOAD=$(mktemp)
audio_b64=$(base64 < "$AUDIO" | tr -d '\n')
jq -n --arg model "$MODEL" --arg data "$audio_b64" --arg fmt "$FORMAT" \
'{model: $model, input_audio: {data: $data, format: $fmt}}' > "$PAYLOAD"
# --data-binary @file keeps the base64 payload off argv (avoids E2BIG / ARG_MAX).
http_code=$(curl -sS -X POST https://openrouter.ai/api/v1/audio/transcriptions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
--output "$BODY" \
-w '%{http_code}' \
--data-binary @"$PAYLOAD")
if [[ "$http_code" != "200" ]]; then
echo "STT failed (HTTP $http_code):" >&2
cat "$BODY" >&2
rm -f "$BODY" "$PAYLOAD"
exit 1
fi
jq -r '.text' "$BODY"
rm -f "$BODY" "$PAYLOAD"
Discovering STT models
Filter the models endpoint by output modality to list transcription models.
curl -sS "https://openrouter.ai/api/v1/models?output_modalities=transcription" \
| jq '.data[] | {id, name, pricing}'
Models are provider-namespaced — use the full slug (google/chirp-3, openai/whisper-1, openai/whisper-large-v3), not the short name.
Parameters
| Field | Required | Notes |
|---|---|---|
model | yes | Full model slug from /api/v1/models?output_modalities=transcription. |
input_audio.data | yes | Base64-encoded raw audio bytes. Not a data URI — just the base64 payload, no data:audio/...;base64, prefix. |
input_audio.format | yes | wav, mp3, flac, m4a, ogg, webm, or aac. Must match the actual bytes. Support varies by provider. |
language | no | ISO-639-1 code (en, ja, fr). Auto-detected if omitted. |
temperature | no | 0–1. Lower is more deterministic. |
provider | no | Provider passthrough — see below. |
Picking an audio format
wav/flac— uncompressed or lossless. Highest quality; largest uploads.mp3/m4a/aac— compressed. Smaller payloads, which matters because base64 inflates bytes by ~33% on top of whatever the file already weighs.webm/ogg— typical for browser recordings (MediaRecorder).
The format field must match the actual container/codec of the bytes. A file saved as .wav that is actually mp3 will be rejected or mis-decoded. When in doubt, confirm with ffprobe <file>.
Provider-specific options
Provider passthrough goes under provider.options.<slug> and is only forwarded when that provider handles the request. Example — Groq's prompt for vocabulary hinting:
{
"model": "openai/whisper-large-v3",
"input_audio": { "data": "UklGRiQA...", "format": "wav" },
"provider": {
"options": {
"groq": {
"prompt": "Expected vocabulary: OpenRouter, API, transcription"
}
}
}
}
Options keyed by provider slug are forwarded only when that provider matches; other keys are ignored. Check each provider's upstream docs for available passthrough keys.
TypeScript (fetch)
import fs from "fs";
const audio = await fs.promises.readFile("audio.wav");
const data = audio.toString("base64");
const res = await fetch("https://openrouter.ai/api/v1/audio/transcriptions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "google/chirp-3",
input_audio: { data, format: "wav" },
}),
});
if (!res.ok) {
throw new Error(`STT failed (HTTP ${res.status}): ${await res.text()}`);
}
const result = await res.json();
console.log(result.text);
Python (requests)
import base64
import os
import requests
with open("audio.wav", "rb") as f:
data = base64.b64encode(f.read()).decode("utf-8")
res = requests.post(
"https://openrouter.ai/api/v1/audio/transcriptions",
headers={
"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "google/chirp-3",
"input_audio": {"data": data, "format": "wav"},
},
)
if not res.ok:
raise RuntimeError(f"STT failed (HTTP {res.status_code}): {res.text}")
print(res.json()["text"])
Troubleshooting
Garbled or empty text — the format field probably doesn't match the actual bytes, or the audio is silent/corrupted. Confirm with ffprobe audio.wav.
400 with "Invalid base64" or silent failure — data must be just base64, not a data URI (data:audio/wav;base64,...). Strip the prefix if you copied it from a browser FileReader.
400 with a ZodError — a required field is missing or the wrong type. The body looks like {"success":false,"error":{"name":"ZodError","message":"[...]"}} — the nested message JSON string names the bad path (commonly input_audio.data or input_audio.format).
413 / request too large — base64 inflates bytes by ~33%, so a large raw file becomes an even larger JSON payload. Use a smaller source file (compressed format, lower sample rate, or trimmed clip).
Model not found — use the full slug from /api/v1/models?output_modalities=transcription (google/chirp-3, not chirp-3).
References
OpenRouter Text-to-Speech
Synthesize speech via POST /api/v1/audio/speech using curl. The endpoint is OpenAI-compatible, so the OpenAI SDKs work by pointing them at https://openrouter.ai/api/v1. Requires OPENROUTER_API_KEY (get one at https://openrouter.ai/keys). If unset, stop and ask.
One call, raw bytes back
The response body is the audio bytes — write them to a file with the extension matching response_format. It is not JSON; error responses are, so only try to parse JSON when the status is non-200.
Two response headers are worth keeping:
Content-Type—audio/mpegfor mp3; for pcm it includes the sample rate and channel count, e.g.audio/pcm;rate=24000;channels=1. Parse these parameters if you need to wrap the raw bytes into a WAV container.X-Generation-Id— the generation ID (formatgen-tts-<timestamp>-<suffix>), useful for tracking, debugging, and cost lookups.
Drop-in workflow
#!/usr/bin/env bash
set -euo pipefail
MODEL="openai/gpt-4o-mini-tts-2025-12-15"
VOICE="alloy"
FORMAT="mp3" # mp3 or pcm
INPUT="Hello! This is a text-to-speech test."
OUTPUT="speech-$(date +%Y%m%d-%H%M%S).${FORMAT}"
HEADERS=$(mktemp)
payload=$(jq -n --arg model "$MODEL" --arg input "$INPUT" \
--arg voice "$VOICE" --arg fmt "$FORMAT" \
'{model: $model, input: $input, voice: $voice, response_format: $fmt}')
http_code=$(curl -sS -X POST https://openrouter.ai/api/v1/audio/speech \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-D "$HEADERS" \
--output "$OUTPUT" \
-w '%{http_code}' \
-d "$payload")
if [[ "$http_code" != "200" ]]; then
echo "TTS failed (HTTP $http_code):" >&2
cat "$OUTPUT" >&2 # error body is JSON, not audio
rm -f "$OUTPUT" "$HEADERS"
exit 1
fi
gen_id=$(grep -i '^x-generation-id:' "$HEADERS" | awk '{print $2}' | tr -d '\r')
rm -f "$HEADERS"
echo "Saved $(realpath "$OUTPUT") (generation_id=${gen_id:-unknown})"
Discovering TTS models and voices
Filter the models endpoint by output modality to list speech models. Each model carries a supported_voices array with the exact voice IDs that provider accepts.
# Models + voices in one shot
curl -sS "https://openrouter.ai/api/v1/models?output_modalities=speech" \
| jq '.data[] | {id, name, supported_voices, pricing}'
# Just the voices for a specific model
curl -sS "https://openrouter.ai/api/v1/models?output_modalities=speech" \
| jq -r '.data[] | select(.id=="openai/gpt-4o-mini-tts-2025-12-15") | .supported_voices[]'
Voices are provider-namespaced: OpenAI uses short names (alloy, nova), Voxtral encodes language + persona + emotion (en_paul_happy), Kokoro prefixes with language/gender (af_bella = American female Bella).
Parameters
| Field | Required | Notes |
|---|---|---|
model | yes | TTS model slug (e.g. openai/gpt-4o-mini-tts-2025-12-15, mistralai/voxtral-mini-tts-2603). |
input | yes | The text to synthesize. |
voice | yes | Voice identifier. Look up the exact set for your model in supported_voices on the models endpoint (see the discovery section above). Voices are provider-namespaced — e.g. alloy is an OpenAI voice and will not work on Voxtral or Kokoro. |
response_format | no | mp3 or pcm. Default is pcm. Set this explicitly — the default is usually not what a user wants to save. |
speed | no | Playback multiplier (e.g. 1.25). Honored by OpenAI TTS. Other providers may accept and ignore it, or reject unknown fields — check the provider's behavior if it matters. |
provider | no | Provider passthrough — see below. |
Picking a format
mp3(audio/mpeg) — compressed, ready to play in any audio app. Default choice for files the user will listen to or share.pcm(audio/pcm;rate=<rate>;channels=<n>) — uncompressed raw samples. The responseContent-Typecarries the sample rate and channel count (e.g.rate=24000;channels=1for OpenAI TTS), which you'll need if you wrap the bytes into a WAV container. Lower latency for real-time streaming pipelines, but not directly playable on its own. Pick this only when the user explicitly wants raw audio or is piping into a streaming system.
Match the file extension to the format — saving pcm bytes as .mp3 produces a file no player will open, and this is the most common cause of "empty/corrupted audio" reports.
Provider-specific options
Provider passthrough goes under provider.options.<slug> and is only forwarded when that provider handles the request. The most useful one is OpenAI's instructions, which steers tone, accent, pacing, or emotion without retraining:
{
"model": "openai/gpt-4o-mini-tts-2025-12-15",
"input": "Welcome to the show.",
"voice": "alloy",
"response_format": "mp3",
"provider": {
"options": {
"openai": {
"instructions": "Speak in a warm, friendly tone with a slow pace."
}
}
}
}
For other providers, check each provider's upstream docs for available passthrough keys — naming conventions vary (camelCase for OpenAI/Google, snake_case for most others).
OpenAI SDK compatibility
Because the endpoint mirrors OpenAI's /audio/speech, both OpenAI SDKs work by swapping the base URL. Prefer this when the user is already in a Python/TypeScript project and doesn't want to shell out.
# Python — streaming write to file
import os
from openai import OpenAI
client = OpenAI(base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"])
with client.audio.speech.with_streaming_response.create(
model="openai/gpt-4o-mini-tts-2025-12-15",
input="The quick brown fox jumps over the lazy dog.",
voice="nova",
response_format="mp3",
) as response:
response.stream_to_file("output.mp3")
// TypeScript — collect bytes, write once
import OpenAI from "openai";
import fs from "fs";
const client = new OpenAI({
baseURL: "https://openrouter.ai/api/v1",
apiKey: process.env.OPENROUTER_API_KEY!,
});
const response = await client.audio.speech.create({
model: "openai/gpt-4o-mini-tts-2025-12-15",
input: "The quick brown fox jumps over the lazy dog.",
voice: "nova",
response_format: "mp3",
});
await fs.promises.writeFile(
"output.mp3",
Buffer.from(await response.arrayBuffer()),
);
Long inputs
TTS models have per-request character limits (usually a few thousand characters) and are priced per character of input, so there's no penalty to splitting. For anything long (chapters, articles, scripts):
- Split the text at sentence or paragraph boundaries — never mid-word.
- Synthesize each chunk with the same
model+voiceso prosody stays consistent. - Concatenate the resulting audio files. For mp3,
ffmpeg -i "concat:part1.mp3|part2.mp3" -c copy out.mp3works for simple cases; for mixed bitrates or tight seams, re-encode viaffmpeg -f concat -safe 0 -i list.txt output.mp3.
Splitting also improves time-to-first-audio if you stream chunks to a user as they're generated.
Troubleshooting
"Empty" or unplayable audio file — almost always a format/extension mismatch. Check Content-Type in the response headers: audio/pcm saved as .mp3 will not play. Either re-request with response_format: "mp3" or save with the matching extension.
400 with "Model X does not exist" — the slug is wrong. Use the full dated slug from the models endpoint (openai/gpt-4o-mini-tts-2025-12-15, not gpt-4o-mini-tts).
400 with a ZodError — a required field is missing or the wrong type. The body looks like {"success":false,"error":{"name":"ZodError","message":"[...]"}} — the nested message JSON string names the bad path (e.g. "path":["voice"]).
speed has no effect — the provider probably doesn't support it. OpenAI TTS honors it; for other providers, check upstream docs before relying on it.
References
OpenRouter TypeScript SDK
A comprehensive TypeScript SDK for interacting with OpenRouter's unified API, providing access to 300+ AI models through a single, type-safe interface. This skill enables AI agents to leverage the callModel pattern for text generation, tool usage, streaming, and multi-turn conversations.
The SDK is split into two packages:
@openrouter/agent— Agent features:callModel,tool(), stop conditions, streaming, format converters@openrouter/sdk— Platform features: model listing, chat completions, credits, OAuth, API key management
Installation
# For agent features (callModel, tools, stop conditions)
npm install @openrouter/agent
# For platform features (models, credits, OAuth, API keys)
npm install @openrouter/sdk
Setup
Get your API key from openrouter.ai/settings/keys, then initialize:
import { OpenRouter } from '@openrouter/agent';
const client = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY
});
Authentication
The SDK supports two authentication methods: API keys for server-side applications and OAuth PKCE flow for user-facing applications.
API Key Authentication
The primary authentication method uses API keys from your OpenRouter account.
Obtaining an API Key
- Visit openrouter.ai/settings/keys
- Create a new API key
- Store securely in an environment variable
Environment Setup
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
Client Initialization
import { OpenRouter } from '@openrouter/agent';
const client = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY
});
The client automatically uses this key for all subsequent requests:
// API key is automatically included
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Hello!'
});
Get Current Key Metadata
Retrieve information about the currently configured API key (requires @openrouter/sdk):
import OpenRouter from '@openrouter/sdk';
const sdkClient = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
const keyInfo = await sdkClient.apiKeys.getCurrentKeyMetadata();
console.log('Key name:', keyInfo.name);
console.log('Created:', keyInfo.createdAt);
API Key Management
Programmatically manage API keys:
// List all keys
const keys = await client.apiKeys.list();
// Create a new key
const newKey = await client.apiKeys.create({
name: 'Production API Key'
});
// Get a specific key by hash
const key = await client.apiKeys.get({
hash: 'sk-or-v1-...'
});
// Update a key
await client.apiKeys.update({
hash: 'sk-or-v1-...',
requestBody: {
name: 'Updated Key Name'
}
});
// Delete a key
await client.apiKeys.delete({
hash: 'sk-or-v1-...'
});
OAuth Authentication (PKCE Flow)
For user-facing applications where users should control their own API keys, OpenRouter supports OAuth with PKCE (Proof Key for Code Exchange). This flow allows users to generate API keys through a browser authorization flow without your application handling their credentials.
createAuthCode
Generate an authorization code and URL to start the OAuth flow:
const authResponse = await client.oAuth.createAuthCode({
callbackUrl: 'https://myapp.com/auth/callback'
});
// authResponse contains:
// - authorizationUrl: URL to redirect the user to
// - code: The authorization code for later exchange
console.log('Redirect user to:', authResponse.authorizationUrl);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
callbackUrl | string | Yes | Your application's callback URL after user authorization |
Browser Redirect:
// In a browser environment
window.location.href = authResponse.authorizationUrl;
// Or in a server-rendered app, return a redirect response
res.redirect(authResponse.authorizationUrl);
exchangeAuthCodeForAPIKey
After the user authorizes your application, they are redirected back to your callback URL with an authorization code. Exchange this code for an API key:
// In your callback handler
const code = req.query.code; // From the redirect URL
const apiKeyResponse = await client.oAuth.exchangeAuthCodeForAPIKey({
code: code
});
// apiKeyResponse contains:
// - key: The user's API key
// - Additional metadata about the key
const userApiKey = apiKeyResponse.key;
// Store securely for this user's future requests
await saveUserApiKey(userId, userApiKey);
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The authorization code from the OAuth redirect |
Complete OAuth Flow Example
import OpenRouter from '@openrouter/sdk';
import { OpenRouter as Agent } from '@openrouter/agent';
import express from 'express';
const app = express();
// SDK client for OAuth and API key management
const client = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY
});
// Step 1: Initiate OAuth flow
app.get('/auth/start', async (req, res) => {
const authResponse = await client.oAuth.createAuthCode({
callbackUrl: 'https://myapp.com/auth/callback'
});
// Store any state needed for the callback
req.session.oauthState = { /* ... */ };
// Redirect user to OpenRouter authorization page
res.redirect(authResponse.authorizationUrl);
});
// Step 2: Handle callback and exchange code
app.get('/auth/callback', async (req, res) => {
const { code } = req.query;
if (!code) {
return res.status(400).send('Authorization code missing');
}
try {
const apiKeyResponse = await client.oAuth.exchangeAuthCodeForAPIKey({
code: code as string
});
// Store the user's API key securely
await saveUserApiKey(req.session.userId, apiKeyResponse.key);
res.redirect('/dashboard?auth=success');
} catch (error) {
console.error('OAuth exchange failed:', error);
res.redirect('/auth/error');
}
});
// Step 3: Use the user's API key for their requests
app.post('/api/chat', async (req, res) => {
const userApiKey = await getUserApiKey(req.session.userId);
// Create an agent client with the user's key
const userAgent = new Agent({
apiKey: userApiKey
});
const result = userAgent.callModel({
model: 'openai/gpt-5-nano',
input: req.body.message
});
const text = await result.getText();
res.json({ response: text });
});
Security Best Practices
- Environment Variables: Store API keys in environment variables, never in code
- Key Rotation: Rotate keys periodically using the key management API
- Environment Separation: Use different keys for development, staging, and production
- OAuth for Users: Use the OAuth PKCE flow for user-facing apps to avoid handling user credentials
- Secure Storage: Store user API keys encrypted in your database
- Minimal Scope: Create keys with only the permissions needed
Core Concepts: callModel
The callModel function is the primary interface for text generation. It provides a unified, type-safe way to interact with any supported model.
Basic Usage
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Explain quantum computing in one sentence.',
});
const text = await result.getText();
Key Benefits
- Type-safe parameters with full IDE autocomplete
- Auto-generated from OpenAPI specs - automatically updates with new models
- Multiple consumption patterns - text, streaming, structured data
- Automatic tool execution with multi-turn support
Input Formats
The SDK accepts flexible input types for the input parameter:
String Input
A simple string becomes a user message:
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Hello, how are you?'
});
Message Arrays
For multi-turn conversations:
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: [
{ role: 'user', content: 'What is the capital of France?' },
{ role: 'assistant', content: 'The capital of France is Paris.' },
{ role: 'user', content: 'What is its population?' }
]
});
Multimodal Content
Including images and text:
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: [
{
role: 'user',
content: [
{ type: 'text', text: 'What is in this image?' },
{ type: 'image_url', image_url: { url: 'https://example.com/image.png' } }
]
}
]
});
System Instructions
Use the instructions parameter for system-level guidance:
const result = client.callModel({
model: 'openai/gpt-5-nano',
instructions: 'You are a helpful coding assistant. Be concise.',
input: 'How do I reverse a string in Python?'
});
Response Methods
The result object provides multiple methods for consuming the response:
| Method | Purpose |
|---|---|
getText() | Get complete text after all tools complete |
getResponse() | Full response object with token usage |
getTextStream() | Stream text deltas as they arrive |
getReasoningStream() | Stream reasoning tokens (for o1/reasoning models) |
getToolCallsStream() | Stream tool calls as they complete |
getText()
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Write a haiku about coding'
});
const text = await result.getText();
console.log(text);
getResponse()
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Hello!'
});
const response = await result.getResponse();
console.log('Text:', response.text);
console.log('Token usage:', response.usage);
getTextStream()
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Write a short story'
});
for await (const delta of result.getTextStream()) {
process.stdout.write(delta);
}
Tool System
Create strongly-typed tools using Zod schemas for automatic validation and type inference.
Defining Tools
import { tool } from '@openrouter/agent/tool';
import { z } from 'zod';
const weatherTool = tool({
name: 'get_weather',
description: 'Get current weather for a location',
inputSchema: z.object({
location: z.string().describe('City name'),
units: z.enum(['celsius', 'fahrenheit']).optional().default('celsius')
}),
outputSchema: z.object({
temperature: z.number(),
conditions: z.string(),
humidity: z.number()
}),
execute: async (params) => {
// Implement weather fetching logic
return {
temperature: 22,
conditions: 'Sunny',
humidity: 45
};
}
});
Using Tools with callModel
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'What is the weather in Paris?',
tools: [weatherTool]
});
const text = await result.getText();
// The SDK automatically executes the tool and continues the conversation
Tool Types
Regular Tools
Standard execute functions that return a result:
const calculatorTool = tool({
name: 'calculate',
description: 'Perform mathematical calculations',
inputSchema: z.object({
expression: z.string()
}),
execute: async ({ expression }) => {
return { result: eval(expression) };
}
});
Generator Tools
Yield progress events using eventSchema:
const searchTool = tool({
name: 'web_search',
description: 'Search the web',
inputSchema: z.object({ query: z.string() }),
eventSchema: z.object({
type: z.literal('progress'),
message: z.string()
}),
outputSchema: z.object({ results: z.array(z.string()) }),
execute: async function* ({ query }) {
yield { type: 'progress', message: 'Searching...' };
yield { type: 'progress', message: 'Processing results...' };
return { results: ['Result 1', 'Result 2'] };
}
});
Manual Tools
Set execute: false to handle tool calls yourself:
const manualTool = tool({
name: 'user_confirmation',
description: 'Request user confirmation',
inputSchema: z.object({ message: z.string() }),
execute: false
});
Multi-Turn Conversations with Stop Conditions
Control automatic tool execution with stop conditions:
import { stepCountIs, maxCost, hasToolCall } from '@openrouter/agent/stop-conditions';
const result = client.callModel({
model: 'openai/gpt-5.2',
input: 'Research this topic thoroughly',
tools: [searchTool, analyzeTool],
stopWhen: [
stepCountIs(10), // Stop after 10 turns
maxCost(1.00), // Stop if cost exceeds $1.00
hasToolCall('finish') // Stop when 'finish' tool is called
]
});
Available Stop Conditions
| Condition | Description |
|---|---|
stepCountIs(n) | Stop after n turns |
maxCost(amount) | Stop when cost exceeds amount |
hasToolCall(name) | Stop when specific tool is called |
Custom Stop Conditions
const customStop = (context) => {
return context.messages.length > 20;
};
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Complex task',
tools: [myTool],
stopWhen: customStop
});
Dynamic Parameters
Compute parameters based on conversation context:
const result = client.callModel({
model: (ctx) => ctx.numberOfTurns > 3 ? 'openai/gpt-4' : 'openai/gpt-4o-mini',
temperature: (ctx) => ctx.numberOfTurns > 1 ? 0.3 : 0.7,
input: 'Hello!'
});
Context Object Properties
| Property | Type | Description |
|---|---|---|
numberOfTurns | number | Current turn count |
messages | array | All messages so far |
instructions | string | Current system instructions |
totalCost | number | Accumulated cost |
nextTurnParams: Context Injection
Tools can modify parameters for subsequent turns, enabling skills and context-aware behavior:
const skillTool = tool({
name: 'load_skill',
description: 'Load a specialized skill',
inputSchema: z.object({
skill: z.string().describe('Name of the skill to load')
}),
nextTurnParams: {
instructions: (params, context) => {
const skillInstructions = loadSkillInstructions(params.skill);
return `${context.instructions}\n\n${skillInstructions}`;
}
},
execute: async ({ skill }) => {
return { loaded: skill };
}
});
Use Cases for nextTurnParams
- Skill Systems: Dynamically load specialized capabilities
- Context Accumulation: Build up context over multiple turns
- Mode Switching: Change model behavior mid-conversation
- Memory Injection: Add retrieved context to instructions
Generation Parameters
Control model behavior with these parameters:
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Write a creative story',
temperature: 0.7, // Creativity (0-2, default varies by model)
maxOutputTokens: 1000, // Maximum tokens to generate
topP: 0.9, // Nucleus sampling parameter
frequencyPenalty: 0.5, // Reduce repetition
presencePenalty: 0.5, // Encourage new topics
stop: ['\n\n'] // Stop sequences
});
Streaming
All streaming methods support concurrent consumers from a single result object:
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Write a detailed explanation'
});
// Consumer 1: Stream text to console
const textPromise = (async () => {
for await (const delta of result.getTextStream()) {
process.stdout.write(delta);
}
})();
// Consumer 2: Get full response simultaneously
const responsePromise = result.getResponse();
// Both run concurrently
const [, response] = await Promise.all([textPromise, responsePromise]);
console.log('\n\nTotal tokens:', response.usage.totalTokens);
Streaming Tool Calls
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Search for information about TypeScript',
tools: [searchTool]
});
for await (const toolCall of result.getToolCallsStream()) {
console.log(`Tool called: ${toolCall.name}`);
console.log(`Arguments: ${JSON.stringify(toolCall.arguments)}`);
console.log(`Result: ${JSON.stringify(toolCall.result)}`);
}
Format Conversion
Convert between ecosystem formats for interoperability:
OpenAI Format
import { fromChatMessages, toChatMessage } from '@openrouter/agent';
// OpenAI messages → OpenRouter format
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: fromChatMessages(openaiMessages)
});
// Response → OpenAI chat message format
const response = await result.getResponse();
const chatMsg = toChatMessage(response);
Claude Format
import { fromClaudeMessages, toClaudeMessage } from '@openrouter/agent';
// Claude messages → OpenRouter format
const result = client.callModel({
model: 'anthropic/claude-3-opus',
input: fromClaudeMessages(claudeMessages)
});
// Response → Claude message format
const response = await result.getResponse();
const claudeMsg = toClaudeMessage(response);
Responses API Message Shapes
The SDK uses the OpenResponses format for messages. Understanding these shapes is essential for building robust agents.
Message Roles
Messages contain a role property that determines the message type:
| Role | Description |
|---|---|
user | User-provided input |
assistant | Model-generated responses |
system | System instructions |
developer | Developer-level directives |
tool | Tool execution results |
Text Message
Simple text content from user or assistant:
interface TextMessage {
role: 'user' | 'assistant';
content: string;
}
Multimodal Message (Array Content)
Messages with mixed content types:
interface MultimodalMessage {
role: 'user';
content: Array<
| { type: 'input_text'; text: string }
| { type: 'input_image'; imageUrl: string; detail?: 'auto' | 'low' | 'high' }
| {
type: 'image';
source: {
type: 'url' | 'base64';
url?: string;
media_type?: string;
data?: string
}
}
>;
}
Tool Function Call Message
When the model requests a tool execution:
interface ToolCallMessage {
role: 'assistant';
content?: null;
tool_calls?: Array<{
id: string;
type: 'function';
function: {
name: string;
arguments: string; // JSON-encoded arguments
};
}>;
}
Tool Result Message
Result returned after tool execution:
interface ToolResultMessage {
role: 'tool';
tool_call_id: string;
content: string; // JSON-encoded result
}
Non-Streaming Response Structure
The complete response object from getResponse():
interface OpenResponsesNonStreamingResponse {
output: Array<ResponseMessage>;
usage?: {
inputTokens: number;
outputTokens: number;
cachedTokens?: number;
};
finishReason?: string;
warnings?: Array<{
type: string;
message: string
}>;
experimental_providerMetadata?: Record<string, unknown>;
}
Response Message Types
Output messages in the response array:
// Text/content message
interface ResponseOutputMessage {
type: 'message';
role: 'assistant';
content: string | Array<ContentPart>;
reasoning?: string; // For reasoning models (o1, etc.)
}
// Tool result in output
interface FunctionCallOutputMessage {
type: 'function_call_output';
call_id: string;
output: string;
}
Parsed Tool Call
When tool calls are parsed from the response:
interface ParsedToolCall {
id: string;
name: string;
arguments: unknown; // Validated against inputSchema
}
Tool Execution Result
After a tool completes execution:
interface ToolExecutionResult {
toolCallId: string;
toolName: string;
result: unknown; // Validated against outputSchema
preliminaryResults?: unknown[]; // From generator tools
error?: Error;
}
Step Result (for Stop Conditions)
Available in custom stop condition callbacks:
interface StepResult {
stepType: 'initial' | 'continue';
text: string;
toolCalls: ParsedToolCall[];
toolResults: ToolExecutionResult[];
response: OpenResponsesNonStreamingResponse;
usage?: {
inputTokens: number;
outputTokens: number;
cachedTokens?: number;
};
finishReason?: string;
warnings?: Array<{ type: string; message: string }>;
experimental_providerMetadata?: Record<string, unknown>;
}
TurnContext
Available to tools and dynamic parameter functions:
interface TurnContext {
numberOfTurns: number; // Turn count (1-indexed)
turnRequest?: OpenResponsesRequest; // Current request being made
toolCall?: OpenResponsesFunctionToolCall; // Current tool call (in tool context)
}
Event Shapes
The SDK provides multiple streaming methods that yield different event types.
Response Stream Events
The getFullResponsesStream() method yields these event types:
type EnhancedResponseStreamEvent =
| ResponseCreatedEvent
| ResponseInProgressEvent
| OutputTextDeltaEvent
| OutputTextDoneEvent
| ReasoningDeltaEvent
| ReasoningDoneEvent
| FunctionCallArgumentsDeltaEvent
| FunctionCallArgumentsDoneEvent
| ResponseCompletedEvent
| ToolPreliminaryResultEvent;
Event Type Reference
| Event Type | Description | Payload |
|---|---|---|
response.created | Response object initialized | { response: ResponseObject } |
response.in_progress | Generation has started | {} |
response.output_text.delta | Text chunk received | { delta: string } |
response.output_text.done | Text generation complete | { text: string } |
response.reasoning.delta | Reasoning chunk (o1 models) | { delta: string } |
response.reasoning.done | Reasoning complete | { reasoning: string } |
response.function_call_arguments.delta | Tool argument chunk | { delta: string } |
response.function_call_arguments.done | Tool arguments complete | { arguments: string } |
response.completed | Full response complete | { response: ResponseObject } |
tool.preliminary_result | Generator tool progress | { toolCallId: string; result: unknown } |
Text Delta Event
interface OutputTextDeltaEvent {
type: 'response.output_text.delta';
delta: string;
}
Reasoning Delta Event
For reasoning models (o1, etc.):
interface ReasoningDeltaEvent {
type: 'response.reasoning.delta';
delta: string;
}
Function Call Arguments Delta Event
interface FunctionCallArgumentsDeltaEvent {
type: 'response.function_call_arguments.delta';
delta: string;
}
Tool Preliminary Result Event
From generator tools that yield progress:
interface ToolPreliminaryResultEvent {
type: 'tool.preliminary_result';
toolCallId: string;
result: unknown; // Matches the tool's eventSchema
}
Response Completed Event
interface ResponseCompletedEvent {
type: 'response.completed';
response: OpenResponsesNonStreamingResponse;
}
Tool Stream Events
The getToolStream() method yields:
type ToolStreamEvent =
| { type: 'delta'; content: string }
| { type: 'preliminary_result'; toolCallId: string; result: unknown };
Example: Processing Stream Events
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Analyze this data',
tools: [analysisTool]
});
for await (const event of result.getFullResponsesStream()) {
switch (event.type) {
case 'response.output_text.delta':
process.stdout.write(event.delta);
break;
case 'response.reasoning.delta':
console.log('[Reasoning]', event.delta);
break;
case 'response.function_call_arguments.delta':
console.log('[Tool Args]', event.delta);
break;
case 'tool.preliminary_result':
console.log(`[Progress: ${event.toolCallId}]`, event.result);
break;
case 'response.completed':
console.log('\n[Complete]', event.response.usage);
break;
}
}
Message Stream Events
The getNewMessagesStream() yields OpenResponses format updates:
type MessageStreamUpdate =
| ResponsesOutputMessage // Text/content updates
| OpenResponsesFunctionCallOutput; // Tool results
Example: Tracking New Messages
const result = client.callModel({
model: 'openai/gpt-5-nano',
input: 'Research this topic',
tools: [searchTool]
});
const allMessages: MessageStreamUpdate[] = [];
for await (const message of result.getNewMessagesStream()) {
allMessages.push(message);
if (message.type === 'message') {
console.log('Assistant:', message.content);
} else if (message.type === 'function_call_output') {
console.log('Tool result:', message.output);
}
}
API Reference
Client Methods
Beyond callModel, the SDK client (@openrouter/sdk) provides access to platform API endpoints:
import OpenRouter from '@openrouter/sdk';
const sdkClient = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY
});
// List available models
const models = await sdkClient.models.list();
// Chat completions (alternative to callModel)
const completion = await sdkClient.chat.send({
model: 'openai/gpt-5-nano',
messages: [{ role: 'user', content: 'Hello!' }]
});
// Legacy completions format
const legacyCompletion = await sdkClient.completions.generate({
model: 'openai/gpt-5-nano',
prompt: 'Once upon a time'
});
// Usage analytics
const activity = await sdkClient.analytics.getUserActivity();
// Credit balance
const credits = await sdkClient.credits.getCredits();
// API key management
const keys = await sdkClient.apiKeys.list();
Error Handling
The SDK provides specific error types with actionable messages:
try {
const result = await client.callModel({
model: 'openai/gpt-5-nano',
input: 'Hello!'
});
const text = await result.getText();
} catch (error) {
if (error.statusCode === 401) {
console.error('Invalid API key - check your OPENROUTER_API_KEY');
} else if (error.statusCode === 402) {
console.error('Insufficient credits - add credits at openrouter.ai');
} else if (error.statusCode === 429) {
console.error('Rate limited - implement backoff retry');
} else if (error.statusCode === 503) {
console.error('Model temporarily unavailable - try again or use fallback');
} else {
console.error('Unexpected error:', error.message);
}
}
Error Status Codes
| Code | Meaning | Action |
|---|---|---|
| 400 | Bad request | Check request parameters |
| 401 | Unauthorized | Verify API key |
| 402 | Payment required | Add credits |
| 429 | Rate limited | Implement exponential backoff |
| 500 | Server error | Retry with backoff |
| 503 | Service unavailable | Try alternative model |
Complete Example: Agent with Tools
import { OpenRouter } from '@openrouter/agent';
import { tool } from '@openrouter/agent/tool';
import { stepCountIs, hasToolCall } from '@openrouter/agent/stop-conditions';
import { z } from 'zod';
const client = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY
});
// Define tools
const searchTool = tool({
name: 'web_search',
description: 'Search the web for information',
inputSchema: z.object({
query: z.string().describe('Search query')
}),
outputSchema: z.object({
results: z.array(z.object({
title: z.string(),
snippet: z.string(),
url: z.string()
}))
}),
execute: async ({ query }) => {
// Implement actual search
return {
results: [
{ title: 'Example', snippet: 'Example result', url: 'https://example.com' }
]
};
}
});
const finishTool = tool({
name: 'finish',
description: 'Complete the task with final answer',
inputSchema: z.object({
answer: z.string().describe('The final answer')
}),
execute: async ({ answer }) => ({ answer })
});
// Run agent
async function runAgent(task: string) {
const result = client.callModel({
model: 'openai/gpt-5-nano',
instructions: 'You are a helpful research assistant. Use web_search to find information, then use finish to provide your final answer.',
input: task,
tools: [searchTool, finishTool],
stopWhen: [
stepCountIs(10),
hasToolCall('finish')
]
});
// Stream progress
for await (const toolCall of result.getToolCallsStream()) {
console.log(`[${toolCall.name}] ${JSON.stringify(toolCall.arguments)}`);
}
return await result.getText();
}
// Usage
const answer = await runAgent('What are the latest developments in quantum computing?');
console.log('Final answer:', answer);
Best Practices
1. Prefer callModel Over Direct API Calls
The callModel pattern provides automatic tool execution, type safety, and multi-turn handling.
2. Use Zod for Tool Schemas
Zod provides runtime validation and excellent TypeScript inference:
import { z } from 'zod';
const schema = z.object({
name: z.string().min(1),
age: z.number().int().positive()
});
3. Implement Stop Conditions
Always set reasonable limits to prevent runaway costs:
stopWhen: [stepCountIs(20), maxCost(5.00)]
4. Handle Errors Gracefully
Implement retry logic for transient failures:
async function callWithRetry(params, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await client.callModel(params).getText();
} catch (error) {
if (error.statusCode === 429 || error.statusCode >= 500) {
await sleep(Math.pow(2, i) * 1000);
continue;
}
throw error;
}
}
}
5. Use Streaming for Long Responses
Streaming provides better UX and allows early termination:
for await (const delta of result.getTextStream()) {
// Process incrementally
}
Additional Resources
- API Keys: openrouter.ai/settings/keys
- Model List: openrouter.ai/models
- Agent SDK: github.com/OpenRouterTeam/typescript-agent
- SDK Issues: github.com/OpenRouterTeam/typescript-sdk/issues
SDK Status: Beta - Report issues on GitHub
OpenRouter Video
Generate videos via OpenRouter's async POST /api/v1/videos using curl + jq. Requires OPENROUTER_API_KEY (get one at https://openrouter.ai/keys). If unset, stop and ask.
The three steps
Video generation is async: submit → poll → download. A single request can't return the video because generation takes 30s–a few minutes. Tell the user the job was submitted so they know the delay is expected.
POST /api/v1/videos→{ id, polling_url, status: "pending" }GET <polling_url>every ~30s untilstatusiscompleted(terminal failures:failed,cancelled,expired— surface theerrorfield verbatim)GET /api/v1/videos/{id}/content?index=0with the auth header → MP4 bytes
Pick parameters from the models endpoint, don't guess
resolution, aspect_ratio, duration, and frame_images[].frame_type are per-model. Before the first submit for a new model (or whenever the user asks for something specific), fetch the model's capabilities and only send values from the returned sets:
curl -sS https://openrouter.ai/api/v1/videos/models \
| jq '.data[] | select(.id == "MODEL_ID")'
Fields on each model worth knowing: supported_resolutions, supported_aspect_ratios, supported_sizes, supported_durations (often discrete like [4,6,8], not a range), supported_frame_images (which frame_type values are accepted), generate_audio and seed (capability bools), pricing_skus, and allowed_passthrough_parameters. An out-of-set value returns a 400, so validate client-side.
Full workflow (drop-in)
#!/usr/bin/env bash
set -euo pipefail
PROMPT="a golden retriever playing fetch on a sunny beach"
MODEL="google/veo-3.1"
OUTPUT="video-$(date +%Y%m%d-%H%M%S).mp4"
# Build payload — extend with resolution/aspect_ratio/duration/etc. as needed.
payload=$(jq -n --arg model "$MODEL" --arg prompt "$PROMPT" \
'{model: $model, prompt: $prompt}')
submit=$(curl -sS -X POST https://openrouter.ai/api/v1/videos \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d "$payload")
poll_url=$(echo "$submit" | jq -r '.polling_url')
echo "Submitted $(echo "$submit" | jq -r '.id')" >&2
while :; do
sleep 30
resp=$(curl -sS "$poll_url" -H "Authorization: Bearer $OPENROUTER_API_KEY")
# Avoid the name `status` — zsh treats it as read-only.
st=$(echo "$resp" | jq -r '.status')
echo "Status: $st" >&2
case "$st" in
completed) break ;;
failed|cancelled|expired)
echo "Generation $st: $(echo "$resp" | jq -r '.error // "unknown"')" >&2
exit 1 ;;
esac
done
curl -sS -L "$(echo "$resp" | jq -r '.unsigned_urls[0]')" \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
--output "$OUTPUT"
echo "$resp" | jq --arg out "$(realpath "$OUTPUT")" \
'{job_id: .id, generation_id, video_saved: $out, usage}'
Parameters
Required: model, prompt. Common optional fields:
duration(int) — must be one of the model'ssupported_durations.resolution(string) /aspect_ratio(string) /size(string,"WxH") —sizeis interchangeable with resolution + aspect_ratio.generate_audio(bool) — only meaningful if the model'sgenerate_audiocapability is true.seed(int) — honored only if the model'sseedcapability is true.callback_url(HTTPS) — webhook instead of polling.frame_images[]— image-to-video; each entry is{ type: "image_url", image_url: { url }, frame_type: "first_frame" | "last_frame" }.input_references[]— reference-to-video (style guidance); same entry shape, noframe_type. If both arrays are present,frame_imageswins.provider.options.<slug>.parameters.<key>— provider passthrough, see below.
Image url can be a public https:// URL or a local-file data URL: MIME=image/png; B64=$(base64 < file.png | tr -d '\n'); url="data:${MIME};base64,${B64}".
Provider passthrough
Provider-specific params go under provider.options.<slug>.parameters. The allowed keys for a given model are listed (flat) in allowed_passthrough_parameters on the models endpoint — but the meaning, value range, and required combinations come from the upstream provider's API docs (Google Vertex, Alibaba Dashscope, Kwai, ByteDance Volc Engine, MiniMax, OpenAI, etc.). Read the upstream docs before using an unfamiliar key; casing conventions differ between providers (Google/OpenAI use camelCase, most others use snake_case).
Example:
{
"model": "google/veo-3.1",
"prompt": "a time-lapse of a flower blooming",
"provider": {
"options": {
"google-vertex": {
"parameters": {
"personGeneration": "allow",
"negativePrompt": "blurry, low quality"
}
}
}
}
}
Webhooks (optional)
Pass callback_url (HTTPS) in the submit body. On terminal state, OpenRouter POSTs a video.generation.{completed,failed,cancelled,expired} event. Each delivery carries X-OpenRouter-Idempotency-Key: <job_id>-<status>. If a signing secret is configured on the workspace, verify X-OpenRouter-Signature: t=<ts>,v1=<hmac> — HMAC-SHA256 of <ts>,<raw_body> with the secret, reject timestamps older than ~5 minutes.
References
Video generation is not ZDR-eligible because the provider must temporarily retain the output for the async download step.
Spawn Ori Eval
Ori writes and grades the eval on a pinned harness and model, so the bench is identical for every coding agent. You run Ori, keep the user informed, and relay the result. An eval you write yourself is not reproducible, and a score change must come from the user's agent, not from the environment.
Pins
This section gives the two models. The other sections use the names <RUN_MODEL> and <JUDGE_MODEL>. Replace each name with the model that this section gives. To change a model, change only the two lines that follow.
RUN_MODELisopenai/gpt-5.6-terra. The run uses this model.JUDGE_MODELisopenai/gpt-5.6-terra. The eval judge uses this model.
Steps
Do these in order. One line, one action. Appendix letters point to the detail and run in step order, except the troubleshooting table, which is a lookup and comes last.
- Create the run directory and derive its path from the repo root (appendix A).
- Tell the user where the run directory is.
- Read whatever is already in the directory without changing it, and tell the user what is there and how old it is (appendix A).
- Ask the user what to do with it, then reuse the existing
steps.txtand jump to the first step after 4 that is not done, or archive the files and write a freshsteps.txtcovering step 5 onward, or stop and leave everything untouched. Write the fresh tracker without asking only when the directory holds no run files of its own (appendix A). - Run the lookup or install for the
oribinary yourself (appendix B). - If it is still missing, run the
~/.local/bin/orifallback yourself, and stop if that fails too. - Run
ori authyourself, read its output, and branch on the exit status and message: continue when access resolves, stop with login instructions when no credential resolves, and stop with instructions to use 0.3.0 or newer when the command is unknown because the installed Ori predates the headless run support this skill requires (appendix B). - Check for
bunyourself, and stop if it is missing. - Read the eval surface yourself, continuing even if the commands error (appendix B).
- Tell the user where the binary landed, if you installed it.
- Tell the user what the run will do, from what you read in step 9.
- Tell the user it takes 10 to 30 minutes and can spend more than the credit on their key.
- Tell the user they get a scored table and that a question can restart the run.
- Write the task prompt file (appendix C).
- Start one run from the repo root and capture its answer and error files (appendix D).
- Wait for the run to exit, then read the answer file (appendix E).
- Show the user Ori's narration lines from the answer file in plain language.
- If the completed answer contains a tagged question anywhere or its assistant text, above the summary line, ends on an untagged question, continue to step 19; relay only the first question, report a broken one-question contract if another appears, and report an untagged question as a violation while still relaying it (appendix E).
- Print Ori's full context for the first question in an ordinary message, including any table. Do nothing else in this step (appendix E).
- Update
steps.txthere, between the context message and the question, recording what was actually printed: quote the table header row that was printed when the answer carried a table, or record that it carried no table (appendix E). - Ask the user with your own question UI, preserving the three short options and free-text
Other. Keep the question to one short sentence and do not restate or summarize the context table (appendix E). - Append the question and the user's own reply to the task prompt file, or, when the reply does not answer the question, append nothing, ask the same question again through the question UI, and do this step again on the next reply (appendix E).
- Restart over the whole prompt file with the next attempt number and return to step 16, but only when step 22 appended an answer (appendix E).
- Relay the result table, the ship or no-ship decision, and the quoted failures.
- Relay Ori's cost and timing table in full (appendix F).
- Add each attempt's own duration and cost from the summary line at the end of its answer file (appendix F).
- Add one line on the cheaper cost of a re-run.
- Tell the user where Ori left the temporary workspace and that it is throwaway.
- Say they can move the eval into their repo if the numbers made them want to keep it.
Rules
These hold for the whole run.
- Never write the eval yourself and never delegate it to your own subagent. Ori's
create-evalskill runs automatically inside the run. - Always pass
--model <RUN_MODEL>and never pass--harness. The pin is what makes every coding agent run the same bench. Never substitute another slug and never leave the flag off, because either one hands the run to whatever default the user's install happens to carry. - Always pass
--prompt-file. The-pflag works but never use it here, because a one-time string cannot carry state across a restart, and a bare positional prompt is rejected outright. - Run every command in steps 5 to 9 yourself. Installing the binary when it is missing is expected. The credential check is the only setup handoff.
- Never resume and never clear a previous run on your own judgement. The skill is loaded and run inside one session, so anything already in the directory came from a different one, and it is the only record of work the user paid for. Every path out of step 4 needs their answer first, apart from the fresh start on a directory that holds no run files of its own.
- Update
steps.txtas you go: mark a step current before you do it and done before you start the next, and reread the file to decide what comes next instead of trusting memory. A restart replays the prompt file from the top, so this is the only record of how far the last attempt got. - Mark a step whose action is a message to the user done only after that message exists in the conversation. Reading the content in a tool result is not showing it.
- Run one Ori process at a time, never one per candidate model.
ori evalis what compares models. - Do not tell the user internal pass labels such as
eval run pass 3. Use plain progress language instead. - Treat the run directory's
task.txtas the only task prompt state. Append every later message to it, resend the whole file on every restart, never use--session, and keep one answer file and one error log per attempt. - Never ask the user what to eval before the run. Ori's interview covers the surface, success criteria, real data, cost limit, and baseline model. Pass a vague or empty request through unchanged.
- Never answer Ori's question on the user's behalf. If you cannot reach the user, stop and wait. A guessed target produces an invalid eval that looks correct.
- Append only the user's reply to the question currently open. A clarification request or complaint is not an answer, so append nothing, respond to what the user actually said, and ask that same question again through the question UI. A later reply answers the question open at that time and never backfills an earlier gate.
- Do not invent an approval gate before starting the run. Steps 12 and 13 disclose the time and cost, and the only user pauses are the run directory choice in step 4 and the questions handled by step 21.
- Each turn is silent from start to finish. Say that plainly before starting it. Do not report phase banners as milestones because they arrive only when the turn ends.
- Never invent a number. Every attempt reports its own duration and cost on the summary line that ends its answer file, and the eval's own model calls come from Ori's closing table. Name a figure unmeasured only when the attempt wrote no summary line at all.
- Never name a winner unless the production model is in the table. "No change" is a valid result.
- Never give model ids or prices from memory. Check live prices on OpenRouter. The pins are the one exception, because this skill fixes them.
- The setup check must confirm that OpenRouter access resolves through
ori auth. Tell the user to runori loginwhen it does not; never tell the user to export a raw key. An already inherited key may satisfy the check. An unknownori authcommand means the installed Ori predates the headless run support this skill requires, so tell the user they need 0.3.0 or newer and stop. - Never paste step 9's output to the user. You read it, they did not ask for it.
- Never print a secret value from
credentials.json, a.envfile, or a config file. Name the key and its location only, such asOPENAI_API_KEY at .env:4. - Never write the eval into the user's repository. It is a throwaway measuring instrument, not something they asked to keep, and the decision to keep it is theirs to make after they see the numbers.
- Never put the eval inside the repo's own test framework.
ori evalfinds*.eval.tsfiles only, so a pytest, vitest, or Go test file silently never runs. - Never present raw API calls as an Ori eval. If you measure another way, label it clearly.
- Never show the user this skill's vocabulary, including "pre-run", "spawn", "verbatim", and "harness".
- Never write "bakeoff" to the user. Ori's eval docs and its narration still use the word, so replace it with "model comparison" every time you relay, quote, or summarise them, and in your own status lines and command labels.
- Write each status update in plain language. Do not show attempt numbers, file paths, process IDs, command flags, or exit codes to the user. This rule also applies when a run fails. Appendix E gives examples.
- Ori's interview has seven tags in this order:
[surface],[workspace-files],[workspace-data],[criteria-priority],[evaluation-constraint],[candidates], and[next-step].[surface]is conditional when the scan finds more than one call site.[workspace-files]is conditional only when the scan finds no model call site and no material to mine. The two conditional questions are mutually exclusive. The other five are always asked, so there are five questions at minimum and six at most. - Relay one question per turn. Preserve each question's three concrete options one for one and render
Otheras free text. If Ori emits two questions in one turn, relay only the first and report the one-question contract violation. - Ask every question through the question UI, including after an interruption or an out-of-band exchange. Ordinary prose that asks a question does not satisfy step 21.
- Print the full context in an ordinary message, including any table, before asking. This gives the user a readable table in the transcript that remains there after the answer. Update the step tracker between the context message and the question. This applies to every question, including
[next-step]. Print the full results and cost tables above the question rather than compressing them into it. Never put a markdown table inside a question body because the body renders plain wrapped text and turns a table into raw pipes. Appendix E gives the single placement. - Never copy CLI details into this skill or into text for the user. Re-read what step 9 printed for run options, reports, baselines, timeouts, and the eval-file API, because the CLI changes and copies go stale.
Appendix A: run directory and step tracker
What you need is one scratch directory outside the user's repository whose name is fixed by the repository being evaluated. Two properties matter. The same repository must always resolve to the same directory, including when the run is started from a subdirectory, so derive the name from the absolute path of the repository root and fall back to the working directory when there is no repository. Two different repositories must never resolve to the same directory, so the name varies with that path, and whatever produces it has to work on Linux and macOS alike, because a step that quietly produces nothing on one of them collapses every repository into a single directory. Work the name out again in each shell that needs it rather than trusting a variable to survive, because shell state usually does not persist between commands.
The name has to be reproducible to the byte, because a later run of this skill finds the earlier one by arriving at the same path rather than by searching. So it is /tmp/spawn-ori-eval-<hash>, where the hash is the first twelve characters of the hexadecimal SHA-256 of exactly the path that identifies the tree, which is the repository root or the working directory when there is no repository, with no trailing newline and nothing else fed in. Only that value is pinned, not how you compute it, but it is worth checking that whatever you reach for hashes those bytes and no others, since a trailing newline produces a different directory and hides an earlier run. /tmp rather than whatever the environment calls the temporary directory, since that varies between machines and would hide a run from the next session on the same one.
Every file the outer run produces lives there and nowhere else: steps.txt, task.txt, and each attempt's answer-<n>.txt and error-<n>.log. The ori/ subdirectory is reserved for Ori's tracker and every file the run writes itself. The scratch workspace is wherever create-eval's own surface puts it, so record the path Ori reports in ori/. The directory is per repository, so two repos evaluated on one machine never read each other's prompt or answer.
steps.txt carries the user's request on its first line and then one line for each step from 5 onward, each marked todo, current, or done. Steps 1 to 4 are not tracked, because they are what produce the file.
request: which model should we use for the support triage agent
5 done look up the ori binary
6 done fallback lookup not needed
...
15 current start one run
16 todo wait for it to exit and read the answer file
A directory with no run files of its own needs no question, because there is nothing to decide about. That means it is empty apart from previous/ and has no steps.txt, task.txt, attempt files, or ori/ subdirectory. This covers a directory that is empty and one that holds only an earlier archive, since archiving leaves previous/ behind for good. Everything else goes to the user, whatever it holds. A tracker started for a different request, or one whose every step is done, is a reason to tell the user what they are looking at rather than a licence to clear it, because the answer files are the run they paid for and they may want to read them before anything moves.
So read the directory and report it. Give the user what they need to decide without opening it themselves: the request the old tracker was started for, the step it stopped at in plain language, how many attempts ran, and how long ago the last one wrote anything. Then ask with the operator's own question UI and wait.
Offer resuming only when the old tracker's first line matches the request you are working on and a step is unfinished. Resuming anything else would resend another request's prompt file to Ori. Starting a new run and stopping are always available, so the question has three answers at most and two at least.
Resuming reuses what is there as it stands: mark up the same steps.txt, append to the same task.txt, keep every earlier attempt in the cost table, and keep the ori/ directory with its recorded scratch workspace path, because the user already paid for that work. Starting a new run archives the tracker, the prompt file, every answer and error log, and the ori/ directory, which drops the answers the user already gave Ori and pays for the repo exploration again. Stopping changes nothing and ends the task there, which is what the user wants when they would rather read the old files before anything moves. Say which one you are recommending and why, and let them decide.
One thing to settle before resuming: step 15 or 16 left marked current means an attempt was started and its outcome is unknown. Establish whether that process is still running before starting another, and wait for it if it is, because two runs against the same prompt file break the one-process rule. Any other step left current was interrupted rather than started, including step 22, which stays current while it waits for a reply that answers the question.
Archiving means the old run's files, including ori/, end up under previous/ inside the run directory, in their own subdirectory named after the time they were moved, and nothing is deleted. Two things go wrong without the timestamp: a later archive overwrites an earlier one, and the archive directory gets moved inside itself. So move the run's own files and leave previous/ where it is.
Appendix B: setup commands
Install the binary with curl -fsSL https://openrouter.ai/labs/ori/install.sh | bash. It lands in ~/.local/bin, which is frequently absent from PATH in a non-login shell, so try ~/.local/bin/ori --version before reporting a failure. Bun is required because Ori executes *.eval.ts with it.
Read the eval surface with ori eval -h and ori eval skill, falling back to ori skills get create-eval if the second errors. This is what Ori itself follows inside the run, so it tells you what the run will do and which questions it will ask. It never blocks the task: if both commands error, carry on.
Run ori auth before starting. It resolves the credential the CLI will use, including an inherited environment key, and exits zero when access is available. Read its output to distinguish an unknown command from a missing credential, but do not show that output to the user or repeat any credential value. If it exits non-zero because no credential resolves, tell the user to run ori login and stop. If the binary reports that auth is an unknown command, tell the user that the installed Ori predates the headless run support this skill requires, that they need 0.3.0 or newer, and stop.
Appendix C: task prompt template
Write this to task.txt in the run directory, filling in every angle-bracket field, taking <JUDGE_MODEL> from the pins.
Pass the run directory into the prompt so the outer run can archive every file it owns and still start the next session cleanly.
Use the create-eval skill. Follow its five phases in this order: workspace
context, criteria and narrowing, model comparison, routing, close. There are
seven possible question tags in this order: `[surface]`, `[workspace-files]`,
`[workspace-data]`, `[criteria-priority]`, `[evaluation-constraint]`,
`[candidates]`, and `[next-step]`. The first two are mutually exclusive
conditional questions, so each run asks five or six questions.
Ask exactly one question per turn and end the turn after asking it. Give each
question three concrete options plus a free-text `Other` option. Never combine
questions in one turn.
Judge with <JUDGE_MODEL> rather than the SDK's default judge model: pass it
to setupJudge as its own agent.
User request: <verbatim request>
Repo context pointers: <paths>. Read these first.
The Ori directory is <absolute run directory>/ori. Create it if it is absent.
Keep the step tracker and every file you write outside the scratch workspace
under that directory. Record the scratch workspace path you report in the
tracker directory. Do not derive another tracker path, and do not adopt or
resume tracker state outside it. The scratch workspace path you report is the
only other location this run may use for its eval and supporting files. Any
other tracker or state files outside these locations belong to a different
session. Keep the eval and supporting files in that scratch workspace outside
the user's repository. Run the eval with ori eval. Do not create or modify
anything in the user's repository.
Appendix D: starting a run
What you want at the end of this step is one ori code process, started from the repository root on the pinned model with the whole prompt file passed to it, whose assistant text and whose diagnostics have landed in two separate files in the run directory under the same attempt number.
The attempt number is the first one not already used, never a fixed one, because the cost table is read back out of every attempt's files and an overwritten answer takes an attempt's cost with it. Keeping the two streams apart matters for the same reason: only the answer stream carries the assistant text and the summary line the cost table needs, and diagnostics mixed into it would corrupt both. Note which attempt number this run is using, since every later step refers to that attempt's files.
Run it in the foreground. If the operator's shell calls are cut off before a run ends, background it instead and poll it with the operator's own process-management tools.
Appendix E: answer shape
The current run's answer file is answer-<n>.txt in the run directory. The process writes the complete assistant answer when the turn settles, so read the answer file after it exits. Diagnostics go to the error log. There is no live progress source or question detection during the turn.
The last line of the answer file is Ori's own summary line rather than part of the answer, and it looks like this.
summary model=served/model duration=200ms input=100 tok output=25 tok context=90 tok $0.012346
Every attempt writes it, including one that stopped at a question, so it is where that attempt's duration and cost come from. A turn that died before finishing writes none. Read the question from the assistant text above it, since the summary line is what actually ends the file.
The assistant text above the summary line contains Ori's narration: short plain lines that tell what it did, for example "Now scanning where this repo calls models, a few minutes." Show these lines to the user when the turn ends, before the question or the result. They tell the user what happened during the silence. If there are many lines, give a short summary. Keep Ori's own words when they are already plain.
A restart is not a retry. Ori cannot hold a live conversation, so each answer starts a new session that re-reads the full prompt file and continues. Never show the words "restart" or "attempt" to the user, because they suggest a failure that did not happen.
Status updates the user sees must stay plain. Examples:
| Do not say | Say |
|---|---|
| Attempt 2 exited with a tagged question; see answer-2.txt. | Ori read your repo and has a question before it continues. |
| eval run pass 3 completed. | Ori has finished reading. I am checking what it came back with. |
| Restarting ori code --prompt-file with n=3. | I sent your answer to Ori. It reads the project and the full story again, then continues from where it stopped. About 15 minutes. |
| Background command "Restart Ori run as attempt 4 with priority answer" completed (exit code 0) | Ori has finished reading. I am checking what it came back with. |
| Process 48210 is running; error-1.log is empty. | The run continues. Silence is normal here. |
| The run wrote no summary line. | The run stopped before it could report its time and cost. |
| The bakeoff is launched. | The model comparison is running. |
A finished turn ends its assistant text either on a question or on the final report. Find question tags anywhere in the completed answer text, and treat any narration after the first question as noise rather than evidence that the turn continued past it. Relay only the first question when a turn contains more than one, report the one-question contract violation, then append and restart under the rule below. An untagged question at the end of the assistant text is also relayed and handled the same way, with the contract violation reported alongside it. Show the first question and its three options to the user, ask with the operator's own question UI, keep Other as free text, and append the question and the user's own answer to task.txt only when the reply answers it. A reply that asks for clarification or otherwise does not answer is not an answer, so append nothing, respond to what the user said, ask the same question again, and wait rather than restarting, because a restart on an unchanged prompt file pays to re-read the repo and arrives back at the same question. Do not answer the question yourself. If Ori answered its own scoping question instead, discard that attempt rather than relaying it as a result, ask the user, append the answer, and restart. Every question still requires the question UI after an interruption or out-of-band exchange; an ordinary prose question does not satisfy the step.
A question is not only its labels. It carries context the labels do not, such as the markdown table of surface and current model, and the user must see that context at answer time. Print the narration and the full context in an ordinary message, including any table, then update the step tracker before asking in the same turn. Mark the context step done only after its message exists in the conversation, and record the table header row that was actually printed or an explicit note that no table was present. The printed table stays readable in the transcript after the answer. This applies to every question, including [next-step]. Print the full results and cost tables above the question rather than compressing them into it.
Ask with a minimal question UI that carries only one short sentence, the three short option labels, and free-text Other. Never put a markdown table in the question body. It renders plain wrapped text, so a table there turns into raw pipes and is unreadable. Keep the three options one for one, keep Other as free text, and translate the wording into simple language.
What you append afterwards is the question's full text in plain language plus the single answer string, including the typed text when the user chose Other.
Appendix F: cost and timing table
Include one row for every attempt, including each attempt that ended at a question, since a restart repeats repo exploration. Each attempt's duration and cost come from the summary line at the end of its answer file, and the eval's own model calls and judging come from Ori's closing table in the final answer. Start times are the operator's observation, because the summary line reports duration only. An attempt whose answer file has no summary line reported nothing, so mark it "unmeasured", which is not zero, and report the total as a floor whenever any row is unmeasured. Label the rows in plain language, because the table goes to the user and the plain-language rule holds here too.
| Step | Start | Duration | Cost |
|---|---|---|---|
| Reading the project, stopped to ask you a question | observed 20:29 | 39s | $0.42 |
| Reading the project again after your answer | observed 20:30 | 15m 10s | $3.20 |
| Eval model calls | 20:46 | 2m | $0.46 |
| Judging | 20:48 | 1m | $0.05 |
| … | |||
| Total | $4.13 |
Follow it with one line, for example: the run cost $4.13 in total, and a rerun costs only the amount shown in Ori's closing table.
Appendix G: troubleshooting
| Symptom | Do this |
|---|---|
| The run directory holds run files already | Report what is in it and ask the user. Never continue it and never clear it on your own. |
ori: command not found after a good installation | Run ~/.local/bin/ori. The installer's PATH change does not apply to the current shell. |
| The credential is missing | Stop. Tell the user to run ori login. |
| A long pause on the first run | The first run creates ~/.ori/global and downloads templates. It takes about 30 seconds and is not a stopped run. |
| Ori does nothing and the prompt looks empty | The path in the start command does not match the file you wrote. |
| Ori reports that a model id is not available | Tell Ori to find the id again. Do not supply one from memory. |
| The eval file is inside the user's repository | Move it and its supporting files to a temporary workspace and run ori eval on the new path. |
| Ori resumed a tracker of its own from an earlier session | Discard that attempt rather than relaying it. Tell the user plainly that Ori resumed state from an earlier session, and ask before anything moves. When they agree, move only the leftover ori/ state under previous/<timestamp>/, leave the current tracker, prompt file, and cost table intact, then restart from the full prompt file with the next attempt number. |
| Ori picked the target itself | Discard the attempt rather than accepting the guessed target. Ask the user, append the answer, and restart from the full prompt file. |
| The answer has no tagged question but the run looks stopped | Read the final answer. Relay an untagged question, report the contract violation, and carry on from step 19. |
| The user says they cannot read the table | Print the context again in an ordinary message. Never put the markdown table inside the question body, because it renders as raw pipes. |
ori code refuses a redirected run because it needs a terminal | Stop. The attempt spent nothing, and the run cannot proceed on this binary. Tell the user to use Ori 0.3.0 or newer. |
403 Key limit exceeded or a 402 payment error | The key is at its spend limit. See below. |
A run that dies within seconds on a key limit or payment error is not a defect in Ori or in the eval. Tell the user plainly that the key has no credit, no eval was written, and the attempt spent nothing. Give them the exact Manage it using <url> link from the error and ask whether to raise the limit or add credits. The dashboard change is enough, since the credential stays valid and a new ori login is not needed. When they confirm, start the same run again and continue the task from the same point, since the error is a recoverable pause rather than a terminal failure.
Sponsors
Details
- Marketplace
- OpenRouterTeam/skills
- Category
- Community