Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

17.5 KB
Raw Blame
/**
 * Cost Calculator — extracted from usageDb.js (T-15)
 *
 * Pure function for calculating request cost based on model pricing.
 * No DB interaction — pricing is fetched from localDb.
 *
 * @module lib/usage/costCalculator
 */

import { toNumber } from "@/shared/utils/numeric";
import { splitCodexReasoningSuffix } from "@omniroute/open-sse/executors/codex/reasoningSuffix.ts";
import { isCreditMeteredProvider } from "./creditMeteredProviders";
import { isFlatRateProvider } from "./flatRateProviders";

/**
 * Normalize model name — strip provider path prefixes.
 * Examples:
 *   "openai/gpt-oss-120b" → "gpt-oss-120b"
 *   "accounts/fireworks/models/gpt-oss-120b" → "gpt-oss-120b"
 *   "deepseek-ai/DeepSeek-R1" → "DeepSeek-R1"
 *   "gpt-oss-120b" → "gpt-oss-120b" (no-op)
 *
 */
export function normalizeModelName(model: string): string {
  if (!model || !model.includes("/")) return model;
  const parts = model.split("/");
  return parts[parts.length - 1];
}

export type CostCalculationOptions = {
  provider?: string | null;
  model?: string | null;
  serviceTier?: string | null;
  /**
   * When true, return $0 for flat-rate (subscription / cookie-web) providers
   * instead of the per-token estimate (#5552). Opt-in so only analytics/display
   * surfaces zero out; budget / quota / routing keep estimating. Requires
   * `provider` to be set.
   */
  flatRateAsZero?: boolean;
};

/**
 * xAI reports the exact provider-billed cost of a request in the chat-completions
 * `usage` object via `cost_in_usd_ticks` (port of decolua/9router#2453, capability
 * A — @ryanngit). Per the official docs — both
 * https://docs.x.ai/developers/cost-tracking and the API reference's usage schema
 * ("TICKS_IN_USD_CENT: i64 = 100_000_000") — there are 10_000_000_000 (1e10) ticks
 * per USD. Example from the docs: 37756000 ticks ≈ $0.0038.
 *
 * NOTE: this divisor is intentionally 1e10, not the 1e12 used by the upstream PR
 * (which under-reports cost 100x) — verified directly against the xAI docs.
 */
const USD_TICKS_PER_DOLLAR = 10_000_000_000;

type CostTokenDetails = {
  cached_tokens?: number;
  cache_creation_tokens?: number;
  cache_write_tokens?: number;
  cache_creation_in_prompt?: boolean;
  reasoning_tokens?: number;
};

/** Numeric aliases and nested details accepted from normalized or raw usage. */
interface CostTokenUsage extends Record<string, unknown> {
  input?: number;
  prompt_tokens?: number;
  input_tokens?: number;
  cacheRead?: number;
  cached_tokens?: number;
  cache_read_input_tokens?: number;
  cacheCreation?: number;
  cache_creation_input_tokens?: number;
  output?: number;
  completion_tokens?: number;
  output_tokens?: number;
  reasoning?: number;
  reasoning_tokens?: number;
  cost_in_usd_ticks?: number;
  prompt_tokens_details?: CostTokenDetails;
  input_tokens_details?: CostTokenDetails;
  completion_tokens_details?: CostTokenDetails;
  output_tokens_details?: CostTokenDetails;
}

/**
 * Extract an exact, provider-reported USD cost from a token/usage record when one
 * is present, so callers can trust it over the token × pricing estimate. Handles
 * xAI's `cost_in_usd_ticks` (see comment above) first, then the normalized
 * `cost_usd` carried from OpenRouter's `usage.cost` (bare USD number).
 */
function extractExactCostUsd(tokens: CostTokenUsage | null | undefined): number | null {
  const ticks = tokens?.cost_in_usd_ticks;
  if (typeof ticks === "number" && Number.isFinite(ticks) && ticks >= 0) {
    return ticks / USD_TICKS_PER_DOLLAR;
  }
  const costUsd = tokens?.cost_usd;
  if (typeof costUsd === "number" && Number.isFinite(costUsd) && costUsd >= 0) {
    return costUsd;
  }
  return null;
}

function normalizeServiceTier(value: unknown): string {
  return typeof value === "string" ? value.trim().toLowerCase() : "";
}

function stripCodexEffortSuffix(model: string): string {
  return model.replace(/-(?:ultra|max|xhigh|high|medium|low|none)$/i, "");
}

/**
 * Effort-free pricing keys for a Codex model id, most specific first. The Codex
 * executor also accepts a parenthesized override (`gpt-6-luna(max)`), which the
 * pricing tables only list in its hyphen form (`gpt-6-luna-max`), so try that tier
 * key before the bare base model.
 */
function getCodexEffortlessPricingKeys(model: string): string[] {
  const lowered = model.toLowerCase();
  const { baseModel, effort } = splitCodexReasoningSuffix(lowered);
  if (effort && lowered === `${baseModel}(${effort})`) {
    return [`${baseModel}-${effort}`, baseModel];
  }
  const stripped = stripCodexEffortSuffix(model);
  return stripped !== model ? [stripped] : [];
}

function isCodexProvider(provider: string | null | undefined): boolean {
  const providerKey = normalizeServiceTier(provider);
  return providerKey === "codex" || providerKey === "cx";
}

/**
 * Pricing row for (provider, model): exact id first (so a user override on an
 * annotated id wins), then the prefix-free id, then — for Codex — the id with its
 * reasoning-effort suffix removed.
 */
async function resolvePricingRow(provider: string, model: string) {
  const { getPricingForModel } = await import("@/lib/db/settings");
  const exact = await getPricingForModel(provider, model);
  if (exact) return exact;
  const normalized = normalizeModelName(model);
  if (normalized !== model) {
    const pricing = await getPricingForModel(provider, normalized);
    if (pricing) return pricing;
  }
  if (!isCodexProvider(provider)) return null;
  for (const key of getCodexEffortlessPricingKeys(normalized)) {
    const pricing = await getPricingForModel(provider, key);
    if (pricing) return pricing;
  }
  return null;
}

export function getCodexFastCostMultiplier(
  provider: string | null | undefined,
  model: string | null | undefined,
  serviceTier: string | null | undefined
): number {
  const providerKey = normalizeServiceTier(provider);
  const tier = normalizeServiceTier(serviceTier);
  if (providerKey !== "codex" && providerKey !== "cx") {
    return 1;
  }

  // OpenAI Flex Processing is billed at a 50% token discount, like Batch,
  // while still using the Responses API with service_tier="flex".
  if (tier === "flex") return 0.5;

  if (tier !== "priority" && tier !== "fast") return 1;

  const modelKey = stripCodexEffortSuffix(
    splitCodexReasoningSuffix(normalizeModelName(String(model || "")).toLowerCase()).baseModel
  );
  const compactModelKey = modelKey.replace(/-/g, "");
  // Codex GPT-6 Fast is 2.5x Standard (https://developers.openai.com/codex/pricing).
  if (
    /^gpt-6(?:\.1)?-(?:astra|sol|luna)$/.test(modelKey) ||
    /^gpt6(?:\.1)?(?:astra|sol|luna)$/.test(compactModelKey)
  ) {
    return 2.5;
  }
  if (
    /^gpt-5\.6-(?:sol|terra|luna)$/.test(modelKey) ||
    /^gpt5\.6(?:sol|terra|luna)$/.test(compactModelKey)
  ) {
    return 1.5;
  }
  if (modelKey === "gpt-5.5" || compactModelKey === "gpt5.5") return 2.5;
  if (modelKey === "gpt-5.4" || compactModelKey === "gpt5.4") return 2;
  return 1;
}

/**
 * Long-context pricing tier: a row may carry `long_context: { threshold, inclusive?, ...rates }`
 * (e.g. OpenAI bills prompts above 272K input tokens at 2x input / 1.5x output for the whole
 * request; xAI switches at >= 200K). The threshold compares the total, cache-inclusive prompt
 * size. When it is crossed, the tier's rates replace the flat ones for the whole request; any
 * rate the tier omits keeps its flat value. Malformed tiers are ignored.
 */
function applyLongContextTier(
  pricing: Record<string, unknown>,
  inputTokens: number
): Record<string, unknown> {
  const tier = pricing.long_context;
  if (!tier || typeof tier !== "object" || Array.isArray(tier)) return pricing;
  const { threshold, inclusive, ...tierRates } = tier as Record<string, unknown>;
  const limit = toNumber(threshold, Number.NaN);
  if (!Number.isFinite(limit) || limit <= 0) return pricing;
  const crossed = inclusive === true ? inputTokens >= limit : inputTokens > limit;
  return crossed ? { ...pricing, ...tierRates } : pricing;
}

/**
 * Calculate cost for a usage entry.
 *
 * @param {string} provider
 * @param {string} model
 * @param {Object} tokens
 * @returns {Promise<number>} Cost in USD
 */
/**
 * Compute cost synchronously from a pre-fetched pricing record.
 * Use this when pricing has already been loaded (e.g. in batch analytics).
 */
export function computeCostFromPricing(
  pricing: Record<string, unknown> | null | undefined,
  tokens: CostTokenUsage | null | undefined,
  options: CostCalculationOptions = {}
): number {
  if (!tokens) return 0;
  // Trust an exact, provider-reported cost over the token × pricing estimate
  // when one is present — works even when no local pricing row exists yet.
  const exactCostUsd = extractExactCostUsd(tokens);
  if (exactCostUsd !== null) return exactCostUsd;
  if (!pricing) return 0;
  // Flat-rate (subscription / cookie-web) providers don't bill per token — their
  // per-token pricing rows exist only for estimation, so display surfaces opt in
  // to show $0 instead of an inflated estimate (#5552).
  if (options.flatRateAsZero && isFlatRateProvider(options.provider)) return 0;
  // A credit-metered provider bills in credits, reported per request as the exact
  // cost handled above. Its per-token rows describe no real tariff, so they are
  // never a cost basis: pricing them would bill the request a second time.
  if (isCreditMeteredProvider(options.provider)) return 0;
  const inputTokens = tokens.input ?? tokens.prompt_tokens ?? tokens.input_tokens ?? 0;
  const rates = applyLongContextTier(pricing, inputTokens);
  const inputPrice = toNumber(rates.input, 0);
  const cachedPrice = toNumber(rates.cached, inputPrice);
  const outputPrice = toNumber(rates.output, 0);
  const reasoningPrice = toNumber(rates.reasoning, outputPrice);
  const cacheCreationPrice = toNumber(rates.cache_creation, inputPrice);

  let cost = 0;
  const promptDetails = tokens.prompt_tokens_details;
  const inputDetails = tokens.input_tokens_details;
  const cachedTokens =
    tokens.cacheRead ??
    tokens.cached_tokens ??
    tokens.cache_read_input_tokens ??
    promptDetails?.cached_tokens ??
    inputDetails?.cached_tokens ??
    0;
  const cacheCreationTokens =
    tokens.cacheCreation ??
    tokens.cache_creation_input_tokens ??
    promptDetails?.cache_creation_tokens ??
    inputDetails?.cache_creation_tokens ??
    promptDetails?.cache_write_tokens ??
    inputDetails?.cache_write_tokens ??
    0;
  const cacheCreationInPrompt =
    inputDetails?.cache_creation_in_prompt ?? promptDetails?.cache_creation_in_prompt;

  // prompt_tokens from extractors already includes cache_read + cache_creation,
  // so we must subtract BOTH cache types to avoid pricing cache at the full
  // input rate in addition to their dedicated cache_* rates below.
  // Translated usage can explicitly keep cache creation outside that total.
  const includedCacheCreation = cacheCreationInPrompt === false ? 0 : cacheCreationTokens;
  const nonCachedInput = Math.max(0, inputTokens - cachedTokens - includedCacheCreation);
  cost += nonCachedInput * (inputPrice / 1_000_000);
  if (cachedTokens > 0) cost += cachedTokens * (cachedPrice / 1_000_000);

  const outputTokens = tokens.output ?? tokens.completion_tokens ?? tokens.output_tokens ?? 0;
  cost += outputTokens * (outputPrice / 1_000_000);

  // completion_tokens is reasoning-inclusive. Reasoning is already billed at
  // the output rate above, so a dedicated price contributes only its premium.
  const reasoningTokens =
    tokens.reasoning ??
    tokens.reasoning_tokens ??
    tokens.completion_tokens_details?.reasoning_tokens ??
    tokens.output_tokens_details?.reasoning_tokens ??
    0;
  if (reasoningTokens > outputTokens) {
    // Reasoning exceeding completion is impossible when completion is inclusive,
    // so the provider reports separate buckets (#15496): bill reasoning on top.
    cost += reasoningTokens * (reasoningPrice / 1_000_000);
  } else if (reasoningTokens > 0 && rates.reasoning !== undefined && rates.reasoning !== null) {
    cost += reasoningTokens * ((reasoningPrice - outputPrice) / 1_000_000);
  }
  cost = Math.max(0, cost);

  if (cacheCreationTokens > 0) cost += cacheCreationTokens * (cacheCreationPrice / 1_000_000);

  return cost * getCodexFastCostMultiplier(options.provider, options.model, options.serviceTier);
}

/**
 * Result of a cost calculation that also reports whether the number is backed by
 * a real pricing row. Budget-enforcement callers (#12341) must be able to tell
 * "$0, priced" (a genuinely free/flat-rate model) apart from "$0, unpriced" (no
 * pricing row was ever found — e.g. a routing alias like `auto`) so they can fail
 * closed on the latter instead of letting it silently pass a hard budget cap.
 */
export interface CostCalculationResult {
  costUsd: number;
  /** false when no pricing row (direct, normalized, or codex-effortless) was found. */
  priced: boolean;
  /** A lookup error is not evidence that the model lacks a price. */
  failed?: boolean;
}

export async function calculateCostDetailed(
  provider: string,
  model: string,
  tokens: CostTokenUsage | null | undefined,
  options: CostCalculationOptions = {}
): Promise<CostCalculationResult> {
  if (!tokens || !provider || !model) return { costUsd: 0, priced: true };

  // Short-circuit before any pricing DB lookup when an exact, provider-reported
  // cost is present (xAI ticks or OpenRouter's USD cost — see extractExactCostUsd).
  const exactCostUsd = extractExactCostUsd(tokens);
  if (exactCostUsd !== null) return { costUsd: exactCostUsd, priced: true };

  try {
    const pricing = await resolvePricingRow(provider, model);
    // No pricing row anywhere — this is the #12341 case (e.g. a provider's own
    // routing alias such as "auto" that has no catalog price). Report it as
    // unpriced rather than a bare $0 so budget enforcement can fail closed.
    if (!pricing) return { costUsd: 0, priced: false };

    const pricingRecord =
      pricing && typeof pricing === "object" && !Array.isArray(pricing)
        ? (pricing as Record<string, unknown>)
        : {};
    const costUsd = computeCostFromPricing(pricingRecord, tokens, {
      provider,
      model,
      ...options,
    });
    return { costUsd, priced: true };
  } catch (error) {
    console.error("Error calculating cost:", error);
    return { costUsd: 0, priced: false, failed: true };
  }
}

export async function calculateCost(
  provider: string,
  model: string,
  tokens: CostTokenUsage | null | undefined,
  options: CostCalculationOptions = {}
): Promise<number> {
  const result = await calculateCostDetailed(provider, model, tokens, options);
  return result.costUsd;
}

type ModalPricing = Record<string, unknown>;

/** Per-image cost: flat per-image × n. 0 when pricing/usage absent. */
export function computeImageCost(
  pricing: ModalPricing | null | undefined,
  usage: { n?: number }
): number {
  if (!pricing) return 0;
  const perImage = toNumber(pricing.output_cost_per_image ?? pricing.input_cost_per_image, 0);
  const n = Math.max(0, Math.floor(toNumber(usage.n, 0)));
  return perImage * n;
}

/** Audio cost: per-second (transcription) OR per-character (TTS). 0 when no dimension. */
export function computeAudioCost(
  pricing: ModalPricing | null | undefined,
  usage: { seconds?: number; characters?: number }
): number {
  if (!pricing) return 0;
  const seconds = toNumber(usage.seconds, 0);
  if (seconds > 0) {
    const perSecond = toNumber(pricing.input_cost_per_second ?? pricing.output_cost_per_second, 0);
    if (perSecond > 0) return perSecond * seconds;
  }
  const characters = toNumber(usage.characters, 0);
  if (characters > 0) {
    const perChar = toNumber(
      pricing.input_cost_per_character ?? pricing.output_cost_per_character,
      0
    );
    // Round to 10 decimals to drop binary-FP artifacts (e.g. 0.000015 * 1000).
    if (perChar > 0) return Math.round(perChar * characters * 1e10) / 1e10;
  }
  return 0;
}

/** Rerank cost: per search unit (Cohere-style billed_units.search_units). */
export function computeRerankCost(
  pricing: ModalPricing | null | undefined,
  usage: { searchUnits?: number }
): number {
  if (!pricing) return 0;
  const perUnit = toNumber(pricing.search_unit_cost ?? pricing.input_cost_per_query, 0);
  const units = Math.max(0, toNumber(usage.searchUnits, 0));
  return perUnit * units;
}

/** Video cost: per video-second. */
export function computeVideoCost(
  pricing: ModalPricing | null | undefined,
  usage: { seconds?: number }
): number {
  if (!pricing) return 0;
  const perSecond = toNumber(
    pricing.output_cost_per_video_per_second ?? pricing.input_cost_per_video_per_second,
    0
  );
  const seconds = toNumber(usage.seconds, 0);
  return perSecond * seconds;
}

export type Modality = "image" | "audio" | "rerank" | "video";
export type ModalUsage = {
  n?: number;
  seconds?: number;
  characters?: number;
  searchUnits?: number;
};

/**
 * Load pricing for (provider, model) and dispatch to the per-modality cost
 * function. Like `calculateCost` for tokens: returns 0 (never throws) when
 * pricing is missing.
 */
export async function calculateModalCost(
  modality: Modality,
  provider: string,
  model: string,
  usage: ModalUsage
): Promise<number> {
  if (!provider || !model) return 0;
  try {
    const pricing = await resolvePricingRow(provider, model);
    if (!pricing) return 0;
    const rec = pricing as Record<string, unknown>;
    switch (modality) {
      case "image":
        return computeImageCost(rec, usage);
      case "audio":
        return computeAudioCost(rec, usage);
      case "rerank":
        return computeRerankCost(rec, usage);
      case "video":
        return computeVideoCost(rec, usage);
      default:
        return 0;
    }
  } catch (error) {
    console.error("Error calculating modal cost:", error);
    return 0;
  }
}