Skills for the OpenRouter platform

GitHub stars
326

Install

/plugin install openrouter@openrouter

Run it inside Claude Code after adding the marketplace with /plugin marketplace add OpenRouterTeam/skills.

Contents

Discovered from source

Skills 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


Decision Tree

User wants to...Action
Build a new agent from scratchPresent checklist below → follow Generation Workflow
Add tools to an existing harnessRead references/tools.md, present tool checklist only
Add a harness moduleRead references/modules.md, generate the module
Add an API server entry pointRead 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)

ToolType stringDefaultConfig
Web Searchopenrouter:web_searchONengine, max_results, domain filtering
Datetimeopenrouter:datetimeONtimezone
Image Generationopenrouter:image_generationOFFmodel, 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/)

ToolDefaultDescription
File ReadONRead files with offset/limit, detect images
File WriteONWrite/create files, auto-create directories
File EditONSearch-and-replace with diff validation
Glob/FindONFile discovery by glob pattern
Grep/SearchONContent search by regex
Directory ListONList directory contents
Shell/BashONExecute commands with timeout and output capture; asks the user before each command
JS REPLOFFPersistent Node.js environment
Sub-agent SpawnOFFDelegate tasks to child agents
Plan/TodoOFFTrack multi-step task progress
Request User InputOFFStructured multiple-choice questions
Web FetchOFFFetch and extract text from web pages
View ImageOFFRead local images as base64
Custom Tool TemplateONEmpty skeleton for domain-specific tools

Harness Modules (architectural components)

ModuleDefaultDescription
Session PersistenceONJSONL append-only conversation log
ASCII Logo BannerOFFCustom ASCII art banner on startup — ask for project name
Context CompactionOFFSummarize older messages when context is long
System Prompt CompositionOFFAssemble instructions from static + dynamic context
Tool Permissions / ApprovalOFFGate other dangerous tools behind user confirmation (the shell tool always asks)
Structured Event LoggingOFFEmit events for tool calls, API requests, errors
@-file ReferencesOFF@filename to attach file content to next message
! Shell ShortcutOFF!command to run shell and inject output into context
Multi-line InputOFFShift+Enter for multi-line (requires raw terminal mode)

Slash Commands (user-facing REPL commands)

CommandDefaultDescription
/modelONSwitch model via OpenRouter API
/newONStart a fresh conversation
/helpONList available commands
/compactOFFManually trigger context compaction
/sessionOFFShow session metadata and token usage
/exportOFFSave 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:

StyleDefaultDescription
blockONFull-width background box with › prompt, adapts to terminal theme
borderedHorizontal ─ lines above and below input
plainSimple > readline prompt, no escape sequences
OtherUser describes what they want — implement a custom input style

Tool display — how tool calls appear during execution. See references/tool-display.md:

StyleDefaultDescription
groupedONBold action labels with tree-branch output
emojiPer-call ⚡/✓ markers with args and timing
minimalAggregated one-liner summaries
hiddenNo tool output
OtherUser describes what they want — implement a custom display

Loader animation — shown while waiting for model response. See references/loader.md:

StyleDefaultDescription
spinnerONBraille dot spinner (⠋⠙⠹…) to the left of the text
gradientScrolling color shimmer over the loader text
minimalTrailing dots (Working···)
OtherUser 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


Decision Tree

User wants to...Action
Build a new headless agentPresent checklist below, follow Generation Workflow
Add tools to an existing agentRead references/tools.md, present tool checklist only
Add a moduleRead references/modules.md, generate the module
Add an entry pointRead 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 PointDefaultDescription
CLIONargs/stdin to agent to stdout, --json for NDJSON
Library moduleONimport { runAgent } from './agent'
HTTP serverOFFBun.serve() with SSE streaming
MCP serverOFFExpose as MCP tool via stdio

OpenRouter Server Tools (server-side, zero implementation)

ToolType stringDefault
Web Searchopenrouter:web_searchON
Web Fetchopenrouter:web_fetchON
Datetimeopenrouter:datetimeON
Image Generationopenrouter:image_generationOFF

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/)

ToolDefaultDescription
File ReadONRead files with offset/limit
File WriteONWrite/create files inside the working directory, auto-create directories
File EditONSearch-and-replace with diff validation, inside the working directory
Glob/FindONFile discovery by glob pattern
Grep/SearchONContent search by regex
Directory ListONList directory contents
Shell/BashONExecute commands with timeout and output capture; refuses unless run with --allow-shell, and is not confined to the working directory once allowed
Custom Tool TemplateONEmpty skeleton for domain-specific tools
JS/TS REPLOFFPersistent Bun REPL
Sub-agent SpawnOFFDelegate tasks to child agents
View ImageOFFRead local images as base64

Agent Modules (architectural components)

ModuleDefaultDescription
Session PersistenceONJSONL conversation log, --no-session to disable
Retry with BackoffONBuilt into agent.ts
Context CompactionOFFSummarize when context is long
Tool Result OffloadOFFPersist oversized tool outputs to disk, keep preview in context
System Prompt CompositionOFFDynamic instructions from context files
Tool Approval FlowOFFProgrammatic approve/reject
Structured Event LoggingOFFJSON events to stderr
Output Schema ValidationOFFZod schema constraining response
Webhook NotificationsOFFPOST on completion

CLI Output Mode (single-select, if CLI entry point is ON)

ModeDefaultDescription
TextONFinal response text to stdout
JSONOFFNDJSON event stream
QuietOFFExit code only

Generation Workflow

Before generating, ask the user what to name their agent. This name is used as:

  • the "name" field in package.json
  • the "bin" command (so bun link makes 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:

  • callModel or uses client.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

OldNew
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

OldNew
import { tool } from '@openrouter/sdk'import { tool } from '@openrouter/agent/tool'

Stop Conditions

OldNew
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

OldNew
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

OldNew
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

OldNew
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:

FeatureAccess
Model listingclient.models.list()
Chat completionsclient.chat.send()
Legacy completionsclient.completions.generate()
Usage analyticsclient.analytics.getUserActivity()
Credit balanceclient.credits.getCredits()
API key managementclient.apiKeys.list(), .create(), etc.
OAuth PKCE flowclient.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:

SubpathExports
@openrouter/agentBarrel: all exports below
@openrouter/agent/clientOpenRouter class
@openrouter/agent/call-modelcallModel standalone function
@openrouter/agent/tooltool() factory function
@openrouter/agent/tool-typesTool, ToolWithExecute, ToolWithGenerator, ManualTool, type guards
@openrouter/agent/stop-conditionsstepCountIs, hasToolCall, maxCost, maxTokensUsed, finishReasonIs
@openrouter/agent/model-resultModelResult response wrapper
@openrouter/agent/async-paramsCallModelInput, hasAsyncFunctions, resolveAsyncFunctions
@openrouter/agent/anthropic-compatfromClaudeMessages, toClaudeMessage
@openrouter/agent/chat-compatfromChatMessages, toChatMessage
@openrouter/agent/conversation-statecreateInitialState, updateState, appendToMessages
@openrouter/agent/next-turn-paramsnextTurnParams utilities
@openrouter/agent/stream-transformersextractUnsupportedContent, getUnsupportedContentSummary
@openrouter/agent/tool-contextbuildToolExecuteContext, ToolContextStore
@openrouter/agent/tool-event-broadcasterToolEventBroadcaster
@openrouter/agent/turn-contextbuildTurnContext

OpenRouter Analytics Query Execution

Full reference for constructing and executing analytics queries against the OpenRouter API.

Prerequisites

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 (or discover-schema.ts) and treat its response as canonical. For agent-readable docs, OpenRouter publishes llms.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

FieldTypeDescription
metricsstring[]At least one metric to compute. Call the meta endpoint to see available metrics.

Optional Fields

FieldTypeDefaultDescription
dimensionsstring[][]Up to 2 dimensions to group by
granularitystringnoneTime bucketing: minute, hour, day, week, month
time_rangeobjectlast 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.
filtersobject[][]Up to 20 filter conditions
order_byobjecttime 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)
limitinteger1000Maximum 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_limitintegerauto-computedMaximum 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_dimensionsobjectnoneGroup by dynamic classifier-produced dimensions. See Classifier Dimensions below.
classifier_filtersobjectnoneFilter 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): value is a string or number
  • Array operators (in, not_in): value is an array of strings or numbers
  • in / not_in accept an optional include_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 (from GET /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
  }
}
FieldTypeRequiredDescription
classifier_idstring (UUID)YesID of the classifier (must belong to the caller's account)
dimension_namesstring[]NoSpecific 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_nullsbooleanNoWhen 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_names omitted → result uses generic clf_dimension_name / clf_dimension_value columns (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"] }
    ]
  }
}
FieldTypeRequiredDescription
classifier_idstring (UUID)YesID of the classifier (must belong to the caller's account)
filtersobject[]Yes1–10 filter conditions on classifier dimensions
filters[].fieldstringYesClassifier dimension name to filter on
filters[].operatorstringYesOne of: eq, neq, in, not_in (no gt/lt — values are strings)
filters[].valuestring | string[]YesScalar 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

FieldDescription
data.dataArray 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_msQuery execution time in milliseconds
data.metadata.row_countNumber of rows returned
data.metadata.truncatedtrue if results were truncated at the limit
data.cachedAtUnix timestamp (ms) when the result was cached. Present when the response was served from cache
data.warningsOptional 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 with Number() or parseInt() before arithmetic.

Label resolution: Dimensions api_key_id, app, user, and workspace return 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-UUID workspace sentinel → Unattributed. model is never relabelled — it stays a permaslug.

CLI Reference

The query-analytics.ts script in the openrouter-analytics skill accepts these flags:

FlagDescriptionExample
--api-keyAPI key (falls back to OPENROUTER_API_KEY env var)--api-key sk-or-v1-...
--metricsComma-separated metric names (required)--metrics request_count,total_usage
--dimensionsComma-separated dimension names--dimensions model,provider
--granularityTime bucket size--granularity day
--startTime range start (ISO 8601 UTC, seconds required)--start 2026-05-01T00:00:00Z
--endTime range end (ISO 8601 UTC, seconds required)--end 2026-05-20T00:00:00Z
--filter-fieldFilter dimension name (first filter; see notes below)--filter-field model
--filter-opFilter operator (first filter)--filter-op eq
--filter-valueFilter value (comma-separated for in/not_in)--filter-value anthropic/claude-sonnet-4
--filter-field-NDimension name for the Nth additional filter (N = 1–19)--filter-field-1 provider
--filter-op-NOperator for the Nth additional filter--filter-op-1 eq
--filter-value-NValue for the Nth additional filter--filter-value-1 anthropic
--order-byField to sort by--order-by total_usage
--order-dirSort direction--order-dir desc
--limitMax total rows (1–10000)--limit 100
--group-limitMax 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. If true, the result was capped at --limit and is a partial dataset — increase --limit or paginate before reporting totals/rankings. Dimensions api_key_id, user, app, and workspace are 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

StatusMeaningAction
400Invalid 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.
401Invalid or missing API keyCheck OPENROUTER_API_KEY is set correctly
403Not a management keyThe key must be a provisioning/management key. Create one at openrouter.ai/settings/management-keys
408Query timed outNarrow the time range, reduce dimensions, or add filters to scan less data
429Rate limited (64 RPM)Wait and retry
500Server errorRetry 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

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:

FieldMeaning
nameIdentifier to use in query requests
display_labelHuman-readable label
is_rateWhether this is a ratio/rate (averaged, not summed)
display_formatHow 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 items
  • tokens_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 tools
  • guardrail_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 as sum(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 of credits_usage charged on BYOK requests (31-day limit). credits_usage includes 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: null for 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 from native_tokens_completion / generation_time; null for 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 guardrails
  • response_cached_rate — ratio of responses served from cache

Understanding Dimensions

Each dimension has:

FieldMeaning
nameIdentifier to use in query requests
display_labelHuman-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:

DimensionResolved to
api_key_idKey name/label
appApp title or origin URL
userUser name or email address
workspaceWorkspace 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)
  • workspace max-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 user value 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 request
  • user — the creator user ID (for org-level queries)
  • workspace — workspace ID
  • app — 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 the openrouter-generations skill)
  • provider — upstream provider name
  • origin — request origin/source
  • country — request country
  • data_region — data region the request was served from; empty values report as global
  • skin — 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 caller
  • context_length_bucket — bucketed context length (1K, 10K, 100K, etc.)
  • session_id — session the request belonged to; sessionless requests group as the literal none
  • streamed — whether the request was streamed; values are the strings true and false

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_dimensions request 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_filters request 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-query skill for the full request shape

Mapping Questions to Classifier Queries

Question patternRequest fieldsNotes
"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:

OperatorValue TypeMeaning
eqscalarEquals
neqscalarNot equals
gtscalarGreater than
gtescalarGreater than or equal
ltscalarLess than
ltescalarLess than or equal
inarrayIn list
not_inarrayNot 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:

GranularityUse when
minuteLast few hours, real-time monitoring
hourLast 1–3 days
dayLast week to 3 months
weekLast 3–12 months
monthYear-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 patternMetricsDimensionsNotes
"How much did I spend?"total_usage—Add granularity for trends
"Which models cost the most?"total_usagemodelOrder 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_latencyprovider31-day limit
"What's my cache hit rate?"cache_hit_ratemodelRate metric — shows per-model caching
"Which API key uses the most?"request_count, total_usageapi_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_latencymodel or provider31-day limit. Streamed requests with more than one completion token only
"Usage by country"request_countcountry31-day limit
"How can I save money?"total_usage, cache_hit_rate, tokens_totalmodelSee cost optimization in openrouter-analytics skill
"Show me individual requests"total_usage, tokens_totalgeneration_id31-day limit. Use returned IDs with openrouter-generations skill for full metadata and content
"How much BYOK spend?"byok_usagemodelUp to 367 days
"BYOK vs credits split?"byok_usage, credits_usage—Both up to 367 days
"BYOK platform fees?"byok_feesmodel31-day limit
"Non-BYOK inference spend?"openrouter_usagemodel31-day limit
"How many guardrail triggers?"guardrail_invoked_count, guardrail_invoked_ratemodel31-day limit
"How many cached responses?"response_cached_count, response_cached_ratemodel31-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_webmodelUp to 367 days
"File processing costs?"usage_file, usage_upstream_filemodel31-day limit
"Web fetch costs?"usage_web_fetch, usage_upstream_web_fetchmodel31-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:

DimensionFilter valueWhere to find it
api_key_idNumeric ID or 64-char SHA-256 hashNumeric 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).
userClerk user ID (e.g. user_abc123)User settings or org member list — not the display name/email shown in results.
workspaceWorkspace 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.
appNumeric app IDGeneration metadata (app_id field) or app settings — not the app title shown in results.
modelPermaslug (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
  • hour granularity reads the minute materialized view: 31-day maximum
  • Possible-cache metrics (possible_cached_tokens, possible_cache_hit_rate, cache_capture_rate): 31-day maximum, hour or coarser granularity, and only model/provider dimensions and filters — any other dimension, filter, classifier, or minute granularity 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 the OPENROUTER_API_KEY environment variable

First-Time Setup

cd <skill-path>/scripts && npm install

Decision Tree

User wants to…Do this
Know what data is availableRun discover-schema.ts to see metrics, dimensions, and filters
See spend / usage / volumeRun query-analytics.ts with appropriate metrics
Break down by model, provider, API keyAdd --dimensions to the query
See trends over timeAdd --granularity day (or hour, week, month)
Reduce costsRun suggest-queries.ts, find the cost optimization template, execute it
Inspect individual generationsAdd --dimensions generation_id, then use the openrouter-generations skill for details
Break down by classifier labelsUse classifier_dimensions in the request body (see openrouter-analytics-query skill)
Filter by classifier labelsUse classifier_filters in the request body (see openrouter-analytics-query skill)
Answer a specific questionMap the question → metrics + dimensions, then query

Workflow

The recommended workflow for answering a user's analytics question:

  1. Discover — Call discover-schema.ts to see available metrics and dimensions
  2. Map — Translate the user's question into metrics, dimensions, filters, and time range
  3. Query — Execute via query-analytics.ts
  4. 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_usage includes BYOK inference cost. usage_data is 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. *_latency is provider-side time to first token; *_router_latency is OpenRouter routing time; *_total_time_to_first_token is their sum over streamed requests only; *_generation_time is provider-side generation time; *_inter_token_latency is the average gap between completion tokens over streamed requests with more than one completion token. Each family has avg_, 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 granularity is set, rows include a date__<granularity> field for the time bucket (e.g., date__day, date__hour, date__month)
  • Label resolution: dimensions api_key_id, app, user, and workspace have their raw IDs replaced with human-readable names (key name, app title, user name, workspace name) directly in the data rows; generation_id and session_id return 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. If true, the result was capped at --limit and is a partial dataset — raise --limit or paginate before reporting totals or rankings

Cost Optimization Guidance

When the user asks "How can I spend less?" or similar:

  1. Query top models by spend: --metrics total_usage,tokens_total,cache_hit_rate,request_count --dimensions model --order-by total_usage --limit 10
  2. Query cost breakdown: --metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web,usage_file --granularity day to see where spend goes
  3. 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_tokens are a large fraction of total — consider disabling extended thinking if not needed
    • High usage_web or usage_file relative to usage_upstream — web search and file processing add-on costs may be significant

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 more
  • get-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-....

EndpointMethodDescription
/api/v1/analytics/metaGETReturns available metrics, dimensions, operators, granularities
/api/v1/analytics/queryPOSTExecutes 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 sourcesCall GET /api/v1/benchmarks and preserve source/citation metadata
Choose a model for an app/use caseCheck whether Artificial Analysis or Design Arena contains a relevant signal; say when no direct benchmark exists
Find best coding, intelligence, or agentic modelsUse task_type=coding, task_type=intelligence, or task_type=agentic
Query Artificial Analysis onlyUse source=artificial-analysis
Query Design Arena onlyUse source=design-arena, plus arena and category when relevant
Get raw API-shaped data for integration workReturn the raw data/meta shape from the endpoint
Understand all response fields or direct curl usageRead 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:

  1. Check GET /api/v1/models for an exact id match to the benchmark model_permaslug.
  2. If there is no exact id match but a model has canonical_slug equal to the benchmark model_permaslug, treat the benchmark row as evidence for that model family, not as a directly recommendable ID. Use the model's actual id only after verifying availability.
  3. Check GET /api/v1/models/{author}/{slug}/endpoints or use openrouter-models get-endpoints.ts for provider status.
  4. 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.
  5. 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:

FlagValuesNotes
sourceartificial-analysis, design-arenaOmitting it returns all sources.
task_typecoding, intelligence, agenticMaps to source-specific indices/categories.
arenamodels, builders, agentsDesign Arena only; defaults server-side to models.
categorycodecategories, uicomponent, gamedev, 3d, dataviz, image, video, svg, etc.Design Arena only.
max_resultspositive integerMaximum 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, and agentic_index; higher is better.
  • Design Arena rows include elo, win_rate, avg_generation_time_ms, arena, category, and tournament_stats; higher elo/win_rate is better, lower generation time is faster.
  • pricing.prompt and pricing.completion are USD per token as decimal strings. Multiply by 1,000,000 for per-million-token costs.
  • model_permaslug identifies the benchmarked model entry. Verify it against GET /api/v1/models before using it as a chat/completions model ID.
  • meta.model_count counts unique models in the response, which can differ from data.length when 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.

NeedPrimitiveReturns
One option from a defined setchoicechoice, probabilities per option, confidence
Whether a condition holdsnoulnoul, the probability of yes
Degree along ordered levelsscorescore (probability-weighted position), probabilities per level, confidence
Where something is in an image (Jev 1.14 only)boxbox 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

  1. 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.

  2. Pick the primitive per judgment. Mutually exclusive alternatives are a choice, which is relative and settles which option. An independently testable condition is a noul, which is absolute and can be low for every label, so labels that can co-occur are one noul each. A degree along one dimension is a score whose levels each describe a situation that stands alone. One unordered label from a written rubric is one choice whose criteria restate the labels, not several nouls recombined in code. Ordered levels (a 1 to 5 rating, low to critical) are a score whose criteria restate the levels in order, even if code stores the result as a label. Split into nouls only when code combines them with facts of its own or reuses them elsewhere. Comparable per-item scores ranked in code give graded ranking. Locating a target in an image is a box. Done when each judgment has a primitive and a reason.

  3. 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 state is read by at least one question and nothing a question needs is missing.

  4. Write the questions. instructions states the judgment and carries the task's own inclusion and exclusion rules (what counts, what looks similar but does not). criteria defines 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`. A choice lists every viable option. When nothing may fit, pair the choice (or a box) with a noul in the same request that asks whether anything fits, which works better on Jev 1.14 than a none option; 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 only state, instructions, and criteria.

  5. 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 (or GET /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 with decide.ts --compare and pick on the observed answers, latency, and cost. Pin the chosen canonical_slug (or the versioned id) 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 copy parseRequest and decide from scripts/lib.ts instead of rewriting them. Done when a request returns one typed answer per question key and the response model string is logged with the answer.

  6. Gate in code. Thresholds and business rules live in code as named constants next to the raw noul and probabilities. Before probing, a noul gate 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 a choice is its choice field, and every stricter number waits for step 7. A choice or box paired with a presence noul is read only in that noul'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, so is_breaking.noul >= T means breaking and "safe" is the else. 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. Use confidence only 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. A noul near 0.5 means yes and no are similarly likely, not medium intensity. A threshold does not carry from a noul to a choice or from one model to another, and P(yes) from one question plus P(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.

  7. 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 the OPENROUTER_API_KEY environment variable
  • Generation IDs look like gen-1234567890 or gen-aBcDeFgHiJkLmNoPqRsT.

First-Time Setup

cd <skill-path>/scripts && npm install

Endpoints

EndpointMethodPurpose
/api/v1/generationGETRequest metadata and usage (tokens, cost, latency, model, provider)
/api/v1/generation/contentGETStored 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_responses array 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/or messages (array of {role, content})
  • Output: completion (the model's response) and reasoning (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 tokens
  • finish_reason = "content_filter" means content was filtered
  • cancelled = true means the request was cancelled by the client
  • provider_responses with 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

StatusMeaning
401Invalid or missing API key
403You don't have access to this generation (belongs to another user)
404Generation ID not found
429Rate limited — wait and retry
500Server error — retry
502Upstream failure — retry

Key Fields Reference

Metadata fields

FieldTypeDescription
idstringGeneration ID (gen-...)
modelstringModel permaslug (e.g., openai/gpt-4o)
provider_namestring|nullProvider that served the request
api_typestringOne of: completions, embeddings, rerank, tts, stt, video
tokens_promptint|nullPrompt token count
tokens_completionint|nullCompletion token count
native_tokens_reasoningint|nullReasoning/thinking tokens
native_tokens_cachedint|nullCached input tokens
total_costnumberTotal cost in USD
usagenumberUsage amount in USD
upstream_inference_costnumber|nullProvider's cost in USD
cache_discountnumber|nullDiscount from caching
latencynumber|nullTotal latency in ms
generation_timenumber|nullModel generation time in ms
moderation_latencynumber|nullModeration check time in ms
finish_reasonstring|nullWhy generation stopped (stop, length, content_filter, etc.)
native_finish_reasonstring|nullRaw finish reason from provider
streamedbool|nullWhether response was streamed
is_byokboolWhether user's own provider key was used
cancelledbool|nullWhether request was cancelled
app_idint|nullOAuth app ID
external_userstring|nullExternal user identifier (X-External-User header)
session_idstring|nullSession grouping ID
request_idstring|nullRequest grouping ID (all gens from one API call)
routerstring|nullRouter used (e.g., openrouter/auto)
service_tierstring|nullProvider service tier
web_search_enginestring|nullSearch engine used (e.g., exa, firecrawl)
num_search_resultsint|nullNumber of search results included
provider_responsesarray|nullProvider attempt chain with per-provider latency/status

Content fields

FieldTypeDescription
data.input.promptstring|nullRaw prompt text
data.input.messagesarray|nullMessages array ([{role, content}])
data.output.completionstring|nullModel's completion text
data.output.reasoningstring|nullChain-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...ScriptExample
See which image models exist and what they supportdiscover.ts"What image models can I use?"
Check the exact params a specific model acceptsdiscover.ts <model>"Does seedream support 4K?"
Generate an image from a text descriptiongenerate.ts "prompt""Create an image of a sunset over mountains"
Generate with specific optionsgenerate.ts "prompt" --aspect-ratio 16:9"Make a wide landscape image of a forest"
Generate with a different modelgenerate.ts "prompt" --model <id>"Generate using gemini 3.1 flash lite image"
Edit or modify an existing imageedit.ts path "prompt""Make the sky purple in photo.png"
Transform an image with instructionsedit.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:

FieldMeaning
provider_name / provider_slugThe serving provider. Use provider_slug as the key in --provider-options.
supported_parametersThe exact parameters this endpoint accepts, with allowed values.
allowed_passthrough_parametersProvider-specific keys you can pass under --provider-options (e.g. steps, guidance).
supports_streamingWhether this endpoint streams.
pricingPer-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>.

FlagDescriptionDefault
--model <id>OpenRouter model IDgoogle/gemini-3.1-flash-image-preview
--output <path>Output file pathimage-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 highModel default
--output-format <f>png, jpeg, webp, or svg (vector models)Model default
--background <b>auto, transparent, or opaqueModel default
--output-compression <n>Compression 0–100 for webp/jpegModel 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_slugNone

--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...ScriptExample
See all available modelslist-models.ts"What models does OpenRouter have?"
Find recently added modelslist-models.ts --sort newest"What are the newest models?"
Find cheapest modelslist-models.ts --sort price"What's the cheapest model?"
Find highest throughput modelslist-models.ts --sort throughput"Which models have the most output capacity?"
Find models in a categorylist-models.ts --category X"Best programming models?"
Search by namesearch-models.ts "query""Do they have Claude?"
Resolve an informal model nameresolve-model.ts "query""Use the nano banana 2.0 model"
Find image-capable modelssearch-models.ts --modality image"Which models accept images?"
Compare specific modelscompare-models.ts A B"Compare Claude vs GPT-4o"
Compare by throughputcompare-models.ts A B --sort throughput"Which has higher throughput, Claude or GPT-4o?"
Check provider performanceget-endpoints.ts "model-id""Which provider is fastest for Claude?"
Find fastest providerget-endpoints.ts "model-id" --sort throughput"Fastest provider for Claude Sonnet?"
Find lowest-latency providerget-endpoints.ts "model-id" --sort latency"Lowest latency provider for GPT-4o?"
Check model availabilityget-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:

ConfidenceScoreAction
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 — operational or degraded
  • 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):

ParameterExampleEffect
category?category=programmingServer-side category filter
supported_parameters?supported_parameters=toolsOnly 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_cutoff and expiration_date are date strings or null.
  • links.details points to the per-provider endpoints API for that model. GET /api/v1/models/{author}/{slug}/endpoints returns { data: { id, name, endpoints: Endpoint[] } }.
  • Endpoint status: 0 = operational, non-zero = degraded.
  • Endpoint latency_last_30m / throughput_last_30m: percentile objects with p50, 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

FieldMeaning
pricing.prompt / pricing.completionCost per token in USD. Multiply by 1,000,000 for per-million-token pricing
context_lengthMax total tokens (input + output)
top_provider.max_completion_tokensMax output tokens from the best provider
top_provider.is_moderatedWhether content moderation is applied
per_request_limitsPer-request token limits (when non-null)
supported_parametersAPI parameters the model accepts (e.g., tools, structured_outputs, reasoning, web_search_options)
createdUnix timestamp — use for sorting by recency
expiration_dateNon-null means the model is being deprecated
latency_30m_ms.p50Median response latency over last 30 min
throughput_30m_tokens_per_sec.p50Median generation speed over last 30 min
uptime_30mProvider availability percentage over last 30 min

Presenting Results

  • When a user mentions a model by informal name, use resolve-model.ts first, then feed the resolved id into 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_date as 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 appFollow 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 authDo 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_verifier in sessionStorage (not localStorage) — 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
ParamValue
callback_urlYour app's URL (where the user returns after auth)
code_challengeThe S256 challenge from Step 1
code_challenge_methodAlways 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 key in localStorage
  • Clean the URL: history.replaceState({}, "", location.pathname) to remove ?code=
  • Cross-tab sync: Listen for storage events on the API key's localStorage entry 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>
ModeFill
Light backgrounds#7624F4
Dark backgrounds#C8FF00

Variants (Tailwind)

Recommended classes for visual consistency with the reference implementation:

VariantClasses
defaultrounded-lg border border-neutral-300 bg-white text-neutral-900 shadow-sm hover:bg-neutral-50
minimaltext-neutral-700 underline-offset-4 hover:underline
brandedrounded-lg bg-neutral-900 text-white shadow hover:bg-neutral-800
iconSame as default + aspect-square (logo only, no text)
ctarounded-xl bg-neutral-900 text-white shadow-lg hover:bg-neutral-800 hover:scale-[1.02] active:scale-[0.98]

Sizes

SizeClasses
smh-8 px-3 text-xs
defaulth-10 px-5 text-sm
lgh-12 px-8 text-base
xlh-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

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 includes cost. Providers additionally report either seconds of 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

FieldRequiredNotes
modelyesFull model slug from /api/v1/models?output_modalities=transcription.
input_audio.datayesBase64-encoded raw audio bytes. Not a data URI — just the base64 payload, no data:audio/...;base64, prefix.
input_audio.formatyeswav, mp3, flac, m4a, ogg, webm, or aac. Must match the actual bytes. Support varies by provider.
languagenoISO-639-1 code (en, ja, fr). Auto-detected if omitted.
temperatureno0–1. Lower is more deterministic.
providernoProvider 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/mpeg for 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 (format gen-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

FieldRequiredNotes
modelyesTTS model slug (e.g. openai/gpt-4o-mini-tts-2025-12-15, mistralai/voxtral-mini-tts-2603).
inputyesThe text to synthesize.
voiceyesVoice 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_formatnomp3 or pcm. Default is pcm. Set this explicitly — the default is usually not what a user wants to save.
speednoPlayback 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.
providernoProvider 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 response Content-Type carries the sample rate and channel count (e.g. rate=24000;channels=1 for 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):

  1. Split the text at sentence or paragraph boundaries — never mid-word.
  2. Synthesize each chunk with the same model + voice so prosody stays consistent.
  3. Concatenate the resulting audio files. For mp3, ffmpeg -i "concat:part1.mp3|part2.mp3" -c copy out.mp3 works for simple cases; for mixed bitrates or tight seams, re-encode via ffmpeg -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
  1. Visit openrouter.ai/settings/keys
  2. Create a new API key
  3. 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:

ParameterTypeRequiredDescription
callbackUrlstringYesYour 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:

ParameterTypeRequiredDescription
codestringYesThe 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

  1. Environment Variables: Store API keys in environment variables, never in code
  2. Key Rotation: Rotate keys periodically using the key management API
  3. Environment Separation: Use different keys for development, staging, and production
  4. OAuth for Users: Use the OAuth PKCE flow for user-facing apps to avoid handling user credentials
  5. Secure Storage: Store user API keys encrypted in your database
  6. 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:

MethodPurpose
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

ConditionDescription
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

PropertyTypeDescription
numberOfTurnsnumberCurrent turn count
messagesarrayAll messages so far
instructionsstringCurrent system instructions
totalCostnumberAccumulated 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:

RoleDescription
userUser-provided input
assistantModel-generated responses
systemSystem instructions
developerDeveloper-level directives
toolTool 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 TypeDescriptionPayload
response.createdResponse object initialized{ response: ResponseObject }
response.in_progressGeneration has started{}
response.output_text.deltaText chunk received{ delta: string }
response.output_text.doneText generation complete{ text: string }
response.reasoning.deltaReasoning chunk (o1 models){ delta: string }
response.reasoning.doneReasoning complete{ reasoning: string }
response.function_call_arguments.deltaTool argument chunk{ delta: string }
response.function_call_arguments.doneTool arguments complete{ arguments: string }
response.completedFull response complete{ response: ResponseObject }
tool.preliminary_resultGenerator 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

CodeMeaningAction
400Bad requestCheck request parameters
401UnauthorizedVerify API key
402Payment requiredAdd credits
429Rate limitedImplement exponential backoff
500Server errorRetry with backoff
503Service unavailableTry 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


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.

  1. POST /api/v1/videos → { id, polling_url, status: "pending" }
  2. GET <polling_url> every ~30s until status is completed (terminal failures: failed, cancelled, expired — surface the error field verbatim)
  3. GET /api/v1/videos/{id}/content?index=0 with 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's supported_durations.
  • resolution (string) / aspect_ratio (string) / size (string, "WxH") — size is interchangeable with resolution + aspect_ratio.
  • generate_audio (bool) — only meaningful if the model's generate_audio capability is true.
  • seed (int) — honored only if the model's seed capability 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, no frame_type. If both arrays are present, frame_images wins.
  • 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_MODEL is openai/gpt-5.6-terra. The run uses this model.
  • JUDGE_MODEL is openai/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.

  1. Create the run directory and derive its path from the repo root (appendix A).
  2. Tell the user where the run directory is.
  3. Read whatever is already in the directory without changing it, and tell the user what is there and how old it is (appendix A).
  4. Ask the user what to do with it, then reuse the existing steps.txt and jump to the first step after 4 that is not done, or archive the files and write a fresh steps.txt covering 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).
  5. Run the lookup or install for the ori binary yourself (appendix B).
  6. If it is still missing, run the ~/.local/bin/ori fallback yourself, and stop if that fails too.
  7. Run ori auth yourself, 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).
  8. Check for bun yourself, and stop if it is missing.
  9. Read the eval surface yourself, continuing even if the commands error (appendix B).
  10. Tell the user where the binary landed, if you installed it.
  11. Tell the user what the run will do, from what you read in step 9.
  12. Tell the user it takes 10 to 30 minutes and can spend more than the credit on their key.
  13. Tell the user they get a scored table and that a question can restart the run.
  14. Write the task prompt file (appendix C).
  15. Start one run from the repo root and capture its answer and error files (appendix D).
  16. Wait for the run to exit, then read the answer file (appendix E).
  17. Show the user Ori's narration lines from the answer file in plain language.
  18. 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).
  19. Print Ori's full context for the first question in an ordinary message, including any table. Do nothing else in this step (appendix E).
  20. Update steps.txt here, 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).
  21. 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).
  22. 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).
  23. 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).
  24. Relay the result table, the ship or no-ship decision, and the quoted failures.
  25. Relay Ori's cost and timing table in full (appendix F).
  26. Add each attempt's own duration and cost from the summary line at the end of its answer file (appendix F).
  27. Add one line on the cheaper cost of a re-run.
  28. Tell the user where Ori left the temporary workspace and that it is throwaway.
  29. 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-eval skill 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 -p flag 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.txt as 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 eval is 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.txt as 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 run ori login when it does not; never tell the user to export a raw key. An already inherited key may satisfy the check. An unknown ori auth command 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 .env file, or a config file. Name the key and its location only, such as OPENAI_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 eval finds *.eval.ts files 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 Other as 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 saySay
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.

StepStartDurationCost
Reading the project, stopped to ask you a questionobserved 20:2939s$0.42
Reading the project again after your answerobserved 20:3015m 10s$3.20
Eval model calls20:462m$0.46
Judging20:481m$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

SymptomDo this
The run directory holds run files alreadyReport 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 installationRun ~/.local/bin/ori. The installer's PATH change does not apply to the current shell.
The credential is missingStop. Tell the user to run ori login.
A long pause on the first runThe 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 emptyThe path in the start command does not match the file you wrote.
Ori reports that a model id is not availableTell Ori to find the id again. Do not supply one from memory.
The eval file is inside the user's repositoryMove 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 sessionDiscard 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 itselfDiscard 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 stoppedRead the final answer. Relay an untagged question, report the contract violation, and carry on from step 19.
The user says they cannot read the tablePrint 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 terminalStop. 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 errorThe 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