Consuming data

AI Model Directory publishes an npm package, ai-model-directory, with typed helpers for JavaScript and TypeScript apps. The package bundles the generated dataset, so you do not need to fetch or host it yourself.

Install

bun add ai-model-directory

The package is ESM-only and ships its own TypeScript types. It is released under the MIT license.

Quick start

The package exports a const per provider, so the common case needs no lookup code:

import { openai } from "ai-model-directory";

openai.name; // "OpenAI"
openai.models["gpt-5.6-luna"]?.pricing?.input;

providers is the whole directory if you prefer to index by id at runtime.

API

Named provider exports

Every provider is exported as a const named after its id, e.g. anthropic, google, openrouter, perplexity. Each is a ProviderEntry. Identifiers that would start with a digit are prefixed with an underscore. When a provider id does not map to a valid identifier, no named export is generated and you must use getProvider instead.

`providers`

Record<string, ProviderEntry> - the whole directory, keyed by provider id.

`getModelDirectory()`

Returns the full ModelDirectory. The bundled payload is decoded once and cached, so later calls return the same object - treat it as read-only.

`getProvider(providerId)`

Returns the ProviderEntry for a provider id, or undefined.

`getProviders()`

Returns an array of all ProviderEntry values.

`getModel(providerId, modelId)`

Returns the ModelRecord for a model within a provider, or undefined.

import { getModel, getProvider, getProviders } from "ai-model-directory";

const openai = getProvider("openai");
const gpt = getModel("openai", "gpt-5.6-luna");
const providers = getProviders();

Advanced

decodeModelDirectory and compactModelDirectoryData expose the raw compact payload for consumers who want to build their own decoder. In most cases you do not need them.

Experimental live data

Node.js applications can opt into newer directory data without updating the package. Importing the package never accesses the network or filesystem.

The Node.js-only live data helpers are available from the ai-model-directory/remote-data subpath, keeping filesystem and network dependencies out of the main package entry point.

experimental_useModelDirectoryData() uses cached data immediately when available and refreshes it in the background. On the first run, when no valid cached data exists, it waits for the download before returning. Pass updateMode: "await" when the call must wait for newly downloaded data instead.

import { getModel } from "ai-model-directory";
import { experimental_useModelDirectoryData } from "ai-model-directory/remote-data";

await experimental_useModelDirectoryData();

const model = getModel("openai", "gpt-5.6-luna");

await experimental_useModelDirectoryData({
  updateMode: "await",
  path: "/custom/cache/all.min.json",
  url: "https://example.com/all.min.json",
  expectedSha256: "...",
});

The default file location uses the operating system's user cache directory on Windows, macOS, and Linux. experimental_downloadModelDirectoryData() and experimental_loadModelDirectoryData() are also available when download and activation need to be controlled separately.

Downloaded files are always treated as untrusted. Downloads require HTTPS and have redirect, timeout, and size limits. Data is parsed only as UTF-8 JSON, strictly schema-validated before being atomically installed, and validated again before activation. The lookup helpers use the activated data; static named provider exports remain snapshots of the bundled data.

Types

The package exports ModelDirectory, ProviderEntry, ModelRecord, ModelPricing, ModelLimit, ModelFeatures, ModelModalities, ModelModality, and ProviderAiSdk.

import type { ModelPricing, ModelRecord } from "ai-model-directory";

Data shape

The package decodes the bundled compact payload into the same provider/model shape as data/all.json.

A provider entry:

field	type	description
`id`	`string`	Provider id used across the directory.
`name`	`string`	Display name.
`website`	`string`	Provider website.
`apiBaseUrl`	`string`	Base URL for API calls.
`aiSdk`	`{ npmPackage?, defaultApiKeyEnv? }`	AI SDK package and default key env var.
`models`	`Record<string, ModelRecord>`	Models keyed by id.

A model record:

field	type	description
`id`	`string`	Model id.
`name`	`string`	Display name; falls back to the id when omitted.
`knowledge_cutoff`	`string`	Unix timestamp (seconds) as a string.
`release_date`	`string`	Unix timestamp (seconds) as a string.
`last_updated`	`string`	Unix timestamp (seconds) as a string.
`open_weights`	`boolean`	Whether the model has open weights.
`features`	`ModelFeatures`	`attachment`, `reasoning`, `tool_call`, `structured_output`, `temperature` booleans.
`pricing`	`ModelPricing`	`input`, `output`, `reasoning`, `cache_read`, `cache_write`, `input_audio`, `output_audio`.
`limit`	`ModelLimit`	`context`, `input`, `output` token limits.
`modalities`	`ModelModalities`	`input` and `output` modality arrays.

Pricing values are USD per one million tokens ($ / MTok). Optional fields are omitted from the payload when the provider does not report them, so check for presence rather than relying on defaults.

Keep it updated

Provider pricing and model lists change often. The dataset is refreshed daily. Update the package regularly and avoid assuming a model or price will never change.

Fetch the JSON directly

If you do not want the package, fetch the generated JSON from the repository or from your own copy of the data.

type Directory = Record<string, unknown>;

const response = await fetch(
  "https://raw.githubusercontent.com/The-Best-Codes/ai-model-directory/main/data/all.min.json",
);
const directory = (await response.json()) as Directory;

all.json is formatted for reading. all.min.json is better for download size.