API reference

Model rankings API

A public, read-only JSON API (no key required) serving daily-updated AI model rankings. Fetch OpenRouter-compatible model IDs by capability category and price tier, then use them directly in your own calls. Rankings cover the full OpenRouter provider catalog; a model is published once it has an Artificial Analysis quality match.

The complete machine-readable schema lives in the OpenAPI spec.

Base URL

https://ai.peculiar.cloud

Endpoints

GET /v1/models/:category/:tier

GET /v1/health

GET /v1/meta

Parameters

Param	Values	Description
`category`	`text` \| `vision`	Model capability category
`tier`	`low` \| `medium` \| `high` \| `ultra`	Price tier, by blended effective cost

Tiers are assigned by a single blended effective cost per million tokens — (prompt × 3 + completion) / 4 — so a model sits in the tier that matches its realistic spend rather than being bumped by one price dimension.

Tier	Blended $/M
`low`	≤ $0.60
`medium`	≤ $2.00
`high`	≤ $12.00
`ultra`	> $12.00

The uncapped ultra tier holds premium models above the high-tier cap, limited to those released within the last 12 months so it surfaces current flagships rather than legacy-expensive models.

Scoring

The score (0–100) reflects capability only: the Artificial Analysis intelligence index rescaled against a fixed reference range. Price is deliberately not part of the score — the tiers handle cost. LM Arena ELO is not scored either; it breaks ties within a tier, with OpenRouter usage (popularity) as a secondary tiebreak. Each model also carries an informational scores.value (quality per blended dollar).

Fetch ranked models

Type definitions and basic fetching. Model IDs are OpenRouter-compatible.

interface RankedModel {
  id: string;
  name: string;
  provider: string;
  score: number;
  scores: {
    quality?: number;
    arena_elo?: number;
    value?: number;
  };
  pricing: {
    prompt_per_million: number;
    completion_per_million: number;
  };
  context_length: number;
  release_date?: string | null;
  modalities: { input: string[]; output: string[] };
  supports_reasoning: boolean;
  sources: { aa: boolean; arena: boolean };
  effort_variant?: string;
  openrouter_params?: Record<string, unknown>;
}

interface TierResponse {
  category: "text" | "vision";
  tier: "low" | "medium" | "high" | "ultra";
  updated_at: string | null;
  tier_config: {
    max_cost_per_million?: number;
    min_cost_per_million?: number;
  };
  models: RankedModel[];
}

const BASE_URL = "https://ai.peculiar.cloud";

async function getModels(
  category: "text" | "vision",
  tier: "low" | "medium" | "high" | "ultra",
): Promise<TierResponse> {
  const res = await fetch(`${BASE_URL}/v1/models/${category}/${tier}`);
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}

const { models } = await getModels("text", "high");
console.log("Top models:", models.map((m) => m.name));

Pick the cheapest model above a quality threshold

Scan tiers from cheapest to most expensive and take the first model that meets your quality bar.

async function pickCheapestAbove(
  minQuality: number,
  category: "text" | "vision" = "text",
): Promise<RankedModel | null> {
  for (const tier of ["low", "medium", "high", "ultra"] as const) {
    const { models } = await getModels(category, tier);
    const qualifying = models
      .filter((m) => (m.scores.quality ?? 0) >= minQuality)
      .sort((a, b) => a.pricing.completion_per_million - b.pricing.completion_per_million);
    if (qualifying.length > 0) return qualifying[0];
  }
  return null;
}

const model = await pickCheapestAbove(40);
if (model) {
  console.log(`Use: ${model.id} ($${model.pricing.completion_per_million}/M output)`);
}

Health check

Monitor data freshness and source availability before relying on rankings.

interface HealthResponse {
  status: "ok" | "degraded" | "stale";
  updated_at: string | null;
  age_hours: number | null;
  sources: {
    artificial_analysis: "ok" | "failed";
    lm_arena: "ok" | "failed";
    openrouter: "ok" | "failed";
  };
}

async function checkHealth(): Promise<HealthResponse> {
  const res = await fetch(`${BASE_URL}/v1/health`);
  return res.json();
}

const health = await checkHealth();
if (health.status !== "ok") {
  console.warn(`API degraded: ${health.status}, age: ${health.age_hours}h`);
}

OpenRouter integration

Model IDs from this API are OpenRouter-compatible. Use them directly with the OpenAI SDK.

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const { models } = await getModels("text", "medium");
const best = models[0];

const completion = await openai.chat.completions.create({
  model: best.id,
  messages: [{ role: "user", content: "Hello!" }],
  ...best.openrouter_params,
});

console.log(completion.choices[0].message.content);

Response shape — GET /v1/models/text/high

{
  "category": "text",
  "tier": "high",
  "updated_at": "2026-02-27T06:00:00Z",
  "tier_config": {
    "max_cost_per_million": 12
  },
  "models": [
    {
      "id": "anthropic/claude-opus-4-6",
      "name": "Claude Opus 4.6",
      "provider": "Anthropic",
      "score": 75.7,
      "scores": { "quality": 53, "arena_elo": 1503, "value": 42.1 },
      "pricing": { "prompt_per_million": 5, "completion_per_million": 25 },
      "context_length": 200000,
      "release_date": "2026-04-16",
      "modalities": { "input": ["text", "image"], "output": ["text"] },
      "supports_reasoning": true,
      "sources": { "aa": true, "arena": true },
      "effort_variant": "adaptive",
      "openrouter_params": {
        "provider": {
          "anthropic": {
            "thinking": { "type": "enabled", "budget_tokens": 5000 }
          }
        }
      }
    }
  ]
}