modelpricing-ai

TypeScript client for the ModelPricing.ai API — estimate LLM usage costs and track spending with a single call.

Zero runtime dependencies. Uses native fetch — works in Node.js 18+, Deno, Bun, Cloudflare Workers, and browsers.

Installation

npm install modelpricing-ai

Quick Start

import { ModelPricingClient } from 'modelpricing-ai'

const client = new ModelPricingClient({ apiKey: 'YOUR_API_KEY' })

const estimate = await client.estimate({
    model: 'gpt-4o-mini',
    tokensIn: 1000,
    tokensOut: 500,
    traceId: { requestId: 'abc-123' }
})

console.log(`Cost: $${estimate.total.toFixed(6)}`)

Response Structure

estimate() returns an EstimateResponse object:

estimate.total // number — total USD cost
estimate.model // string — canonical model name
estimate.traceId // object | null — your pass-through trace ID
estimate.trace // string — server-assigned trace identifier
estimate.breakdown.input.unit.branch.qty.rate.subtotal.output // EstimateBreakdownGroup // EstimateBreakdown //   string — e.g. "per-1M-input" //   string — pricing tier that matched //   number — number of input tokens //   number — per-unit rate //   number — input cost // EstimateBreakdown (same fields for output tokens)

Configuration

| Parameter | Default | Description | | ------------ | ------------------------------- | ------------------------------------------------------------------------ | | apiKey | required | Your ModelPricing.ai API key (also reads MODELPRICING_API_KEY env var) | | baseUrl | "https://api.modelpricing.ai" | API base URL (also reads MODELPRICING_BASE_URL env var) | | timeout | 30000 | Request timeout in milliseconds | | maxRetries | 3 | Maximum retry attempts for transient errors | | fetch | globalThis.fetch | Optional custom fetch function for testing or custom HTTP |

Parameters are resolved in order: constructor option > environment variable > default.

const client = new ModelPricingClient({
    apiKey: 'YOUR_API_KEY',
    baseUrl: 'https://api.modelpricing.ai',
    timeout: 30000,
    maxRetries: 3
})

Error Handling

The client raises typed exceptions for different failure modes:

| Exception | HTTP Status | When | | ----------------- | ----------- | ----------------------------- | | Unauthorized | 401 | Invalid or missing API key | | ValidationError | 422 | Invalid model name or metrics | | NotFound | 404 | Unknown endpoint | | ServerError | 5xx | Server-side failures |

All exceptions inherit from ModelPricingError and include a statusCode property.

import { Unauthorized, ValidationError, ServerError } from 'modelpricing-ai'

try {
    const estimate = await client.estimate({
        model: 'gpt-4o-mini',
        tokensIn: 1000,
        tokensOut: 500
    })
} catch (error) {
    if (error instanceof Unauthorized) {
        console.log('Check your API key')
    } else if (error instanceof ValidationError) {
        console.log(`Bad request: ${error.message}`)
    } else if (error instanceof ServerError) {
        console.log('Server error — will be retried automatically')
    }
}

Retry Behavior

The client automatically retries on transient errors with exponential backoff:

• Retries: 5xx server errors and network errors (TypeError from fetch)
• No retry: 4xx client errors (401, 404, 422)
• Default: 3 retries with exponential backoff + jitter

// Increase retries for unreliable networks
const client = new ModelPricingClient({ apiKey: 'YOUR_API_KEY', maxRetries: 5 })

// Disable retries (no retry attempts)
const client = new ModelPricingClient({ apiKey: 'YOUR_API_KEY', maxRetries: 0 })

License

MIT