@opencode-ai/models

@opencode-ai/models

Official typed client for the Models.dev API.

npm install @opencode-ai/models

Usage

import { Models } from "@opencode-ai/models"

const client = Models.make()

const providers = await client.providers() // GET /api.json
providers["anthropic"]?.models["claude-opus-4-6"]?.cost?.input // USD per 1M tokens

const models = await client.models() // GET /models.json
models["anthropic/claude-opus-4-6"]?.knowledge // provider-agnostic metadata

const catalog = await client.catalog() // GET /catalog.json — both in one request

Options:

const client = Models.make({
  baseUrl: "https://models.dev", // default
  fetch: myFetch,                // proxies, polyfills, test doubles
  headers: { "x-extra": "1" },   // sent with every request
})

await client.providers({ signal: AbortSignal.timeout(5000) })

Errors are a single ModelsDevError with reason: "Transport" | "UnexpectedStatus" | "MalformedResponse" and the underlying cause.

Snapshot

A full copy of the database ships inside the package as a separate, tree-shakable entrypoint:

import snapshot, { providers, models, generatedAt } from "@opencode-ai/models/snapshot"

providers["anthropic"]?.models["claude-opus-4-6"]?.limit.context

Use it for no-network runtimes, tests, cold-start-sensitive paths, or as an explicit fallback:

const providers = await client.providers().catch(async () => (await import("@opencode-ai/models/snapshot")).providers)

The published snapshot is at most ~24h behind the live API (data releases are automated).

Effect

An Effect-native client lives at @opencode-ai/models/effect (requires the optional peer dependency effect):

import { Models } from "@opencode-ai/models/effect"
import { FetchHttpClient } from "effect/unstable/http"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const client = yield* Models.make()
  return yield* client.providers() // Effect<ProviderMap, ModelsDevError>
})

await program.pipe(Effect.provide(FetchHttpClient.layer), Effect.runPromise)

Transport comes from the environment's HttpClient service, so proxies, retries, tracing, and test transports compose the usual Effect way. For DI, Models.Service and Models.layer(options?) are provided:

const program = Effect.gen(function* () {
  const client = yield* Models.Service
  return yield* client.models()
})

program.pipe(Effect.provide(Models.layer().pipe(Layer.provide(FetchHttpClient.layer))))