README
¶
modelsdotdev-go
A Go client for the models.dev catalog — a community registry of LLM providers and models with their capabilities, token limits, and pricing.
Typed structs over https://models.dev/api.json, an in-memory catalog with
lookup/filter helpers, and an HTTP client with TTL caching.
import "github.com/promptrails/modelsdotdev-go"
model, _ := modelsdev.GetModelByID(ctx, "anthropic:claude-opus-4-8")
fmt.Println(model.Name, *model.Cost.Input) // Claude Opus 4.8 5
provider, _ := modelsdev.GetProviderByName(ctx, "OpenAI")
for id := range provider.Models {
fmt.Println(id)
}
Install
go get github.com/promptrails/modelsdotdev-go
Requires Go 1.26+. No third-party dependencies — standard library only.
Usage
Package-level helpers
Backed by a shared client (live fetch, 1h cache):
model, err := modelsdev.GetModelByID(ctx, "openai:gpt-4o")
provider, err := modelsdev.GetProviderByName(ctx, "Anthropic")
A configured client
c := modelsdev.New(
modelsdev.WithTTL(30*time.Minute),
modelsdev.WithUserAgent("my-app/1.0"),
)
cat, err := c.Catalog(ctx) // fetched once, then cached until the TTL expires
// Every reasoning-capable model that also reports a cache-read price:
for _, m := range cat.Filter(func(m modelsdev.Model) bool {
return m.Reasoning && m.Cost.CacheRead != nil
}) {
fmt.Printf("%s:%s\n", m.Provider, m.ID)
}
Catalog serves the last good snapshot if a refetch fails. Refresh forces a
refetch.
Bring your own snapshot
The library does not ship a baked-in copy of the catalog — it would be stale the moment it's built. If you need catalog data without a network call, fetch a snapshot on your own schedule and parse it:
//go:embed models.json
var snapshot []byte
cat, err := modelsdev.Parse(snapshot)
Catalog API
| Method | Returns |
|---|---|
Provider(id) |
a provider by ID ("openai") |
ProviderByName(name) |
a provider by display name, case-insensitive ("OpenAI") |
Model("provider:model") |
a model by fully qualified ID |
ModelOf(provider, model) |
a model by provider ID + model ID |
ProviderIDs() |
all provider IDs, sorted |
Models() |
every model, sorted by provider then model ID |
Filter(func(Model) bool) |
every model matching a predicate |
Missing lookups return ErrNotFound; a malformed qualified ID returns
ErrInvalidID.
Data model
Each Model carries its capabilities (Reasoning, ToolCall, Attachment,
StructuredOutput, Modalities), Limit (context/output tokens), and Cost
(per-1M-token Input, Output, CacheRead, CacheWrite, Reasoning, audio,
and long-context tiers). Cost fields are pointers: nil means "not reported",
which is distinct from a reported zero.
License
MIT — see LICENSE.
Documentation
¶
Overview ¶
Package modelsdev is a Go client for the models.dev catalog — a community registry of LLM providers and models with their capabilities, token limits, and pricing.
It mirrors the data exposed at https://models.dev/api.json with typed Go structs, an in-memory Catalog with lookup/filter helpers, and an HTTP Client with TTL caching.
The quickest start uses the package-level helpers backed by a shared client:
model, err := modelsdev.GetModelByID(ctx, "anthropic:claude-opus-4-8") provider, err := modelsdev.GetProviderByName(ctx, "OpenAI")
For control over the HTTP client, URL, cache TTL, or offline fallback, construct a Client:
c := modelsdev.New(modelsdev.WithTTL(30*time.Minute), modelsdev.WithOfflineFallback(true))
cat, err := c.Catalog(ctx)
for _, m := range cat.Filter(func(m modelsdev.Model) bool { return m.Reasoning }) {
fmt.Println(m.Provider, m.ID)
}
To work without a network call, parse a snapshot you manage yourself (read from disk, embedded via go:embed, …):
cat, err := modelsdev.Parse(mySnapshotBytes)
Index ¶
- Constants
- Variables
- type Catalog
- func (c *Catalog) Filter(keep func(Model) bool) []Model
- func (c *Catalog) Model(qualifiedID string) (Model, error)
- func (c *Catalog) ModelOf(providerID, modelID string) (Model, error)
- func (c *Catalog) Models() []Model
- func (c *Catalog) Provider(id string) (Provider, error)
- func (c *Catalog) ProviderByName(name string) (Provider, error)
- func (c *Catalog) ProviderIDs() []string
- type Client
- type Cost
- type Limit
- type Modalities
- type Model
- type Option
- type Provider
- type TierCost
Constants ¶
const DefaultAPIURL = "https://models.dev/api.json"
DefaultAPIURL is the models.dev machine-readable catalog endpoint.
Variables ¶
var ErrInvalidID = errors.New("modelsdev: invalid model id, want \"provider:model\"")
ErrInvalidID is returned when a fully qualified model ID is not in the "provider:model" form.
var ErrNotFound = errors.New("modelsdev: not found")
ErrNotFound is returned by lookup methods when no provider or model matches.
Functions ¶
This section is empty.
Types ¶
type Catalog ¶
type Catalog struct {
// Providers is keyed by provider ID (Provider.ID).
Providers map[string]Provider
}
Catalog is an in-memory snapshot of the models.dev registry. It is immutable once built and safe for concurrent reads.
func Parse ¶ added in v0.2.0
Parse builds a Catalog from a raw models.dev api.json document. Use it to load a snapshot you manage yourself (embedded via go:embed, read from disk, etc.) when you want catalog data without a network call.
func (*Catalog) Filter ¶
Filter returns every model for which keep reports true, in the same deterministic order as Models.
func (*Catalog) Model ¶
Model returns a model by its fully qualified ID in "provider:model" form, e.g. "openai:gpt-4o" or "amazon-bedrock:anthropic.claude-sonnet".
func (*Catalog) Models ¶
Models returns every model in the catalog, sorted by provider ID then model ID for deterministic iteration. Each returned model has its ID and Provider fields populated.
func (*Catalog) ProviderByName ¶
ProviderByName returns the provider whose Name matches name, case-insensitively (e.g. "OpenAI"). The first match in sorted-ID order is returned.
func (*Catalog) ProviderIDs ¶
ProviderIDs returns all provider IDs in lexical order.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client fetches and caches the models.dev catalog. It is safe for concurrent use. The zero value is not usable — construct one with New.
func Default ¶
func Default() *Client
Default returns the shared Client used by the package-level helpers. Callers who want different behavior should construct their own Client with New.
type Cost ¶
type Cost struct {
// Input is the price per 1M input (prompt) tokens.
Input *float64 `json:"input,omitempty"`
// Output is the price per 1M output (completion) tokens.
Output *float64 `json:"output,omitempty"`
// CacheRead is the price per 1M prompt tokens served from cache (cache hits).
CacheRead *float64 `json:"cache_read,omitempty"`
// CacheWrite is the price per 1M tokens written to the prompt cache.
CacheWrite *float64 `json:"cache_write,omitempty"`
// Reasoning is the price per 1M reasoning tokens, when billed separately.
Reasoning *float64 `json:"reasoning,omitempty"`
// InputAudio / OutputAudio are per-1M-token audio prices, when applicable.
InputAudio *float64 `json:"input_audio,omitempty"`
OutputAudio *float64 `json:"output_audio,omitempty"`
// ContextOver200K holds the long-context pricing some providers apply to
// requests whose context exceeds 200K tokens. Nil when not applicable.
ContextOver200K *TierCost `json:"context_over_200k,omitempty"`
}
Cost holds a model's pricing in USD per 1M tokens. All fields are pointers because models.dev omits the ones a provider does not publish; a nil field means "not reported", which is distinct from a reported zero price.
type Limit ¶
type Limit struct {
// Context is the maximum combined input+output context window in tokens.
Context int `json:"context,omitempty"`
// Input is the maximum input tokens, when reported separately.
Input int `json:"input,omitempty"`
// Output is the maximum output tokens.
Output int `json:"output,omitempty"`
}
Limit holds a model's token limits. Zero means the limit is not reported.
type Modalities ¶
type Modalities struct {
Input []string `json:"input,omitempty"`
Output []string `json:"output,omitempty"`
}
Modalities describes the input and output modalities of a model. Values are lowercase tokens such as "text", "image", "audio", "pdf", "video".
type Model ¶
type Model struct {
// ID is the provider-local model identifier, e.g. "gpt-4o".
ID string `json:"id"`
// Name is the human-readable model name, e.g. "GPT-4o".
Name string `json:"name"`
// Family groups related models, e.g. "claude-opus".
Family string `json:"family,omitempty"`
// Provider is the models.dev provider ID this model belongs to. It is a
// derived back-reference (backfilled from the parent provider), not the
// upstream "provider" object, so it is exposed under a distinct JSON key.
Provider string `json:"provider_id,omitempty"`
// Attachment reports whether the model accepts file/image attachments.
Attachment bool `json:"attachment"`
// Reasoning reports whether the model supports extended thinking / reasoning.
Reasoning bool `json:"reasoning"`
// ToolCall reports whether the model supports function/tool calling.
ToolCall bool `json:"tool_call"`
// Temperature reports whether the model honors a temperature parameter.
Temperature bool `json:"temperature"`
// OpenWeights reports whether the model's weights are openly available.
OpenWeights bool `json:"open_weights"`
// StructuredOutput reports native JSON-schema structured output support.
// It is a pointer because models.dev omits it for models where it is unknown.
StructuredOutput *bool `json:"structured_output,omitempty"`
// Status is the lifecycle status reported upstream (e.g. "deprecated"), if any.
Status string `json:"status,omitempty"`
// Knowledge is the training-data cutoff, e.g. "2024-10".
Knowledge string `json:"knowledge,omitempty"`
// ReleaseDate is the model's release date, e.g. "2026-05-28".
ReleaseDate string `json:"release_date,omitempty"`
// LastUpdated is when the model entry was last updated upstream.
LastUpdated string `json:"last_updated,omitempty"`
// Modalities lists the input/output modalities the model supports.
Modalities Modalities `json:"modalities"`
// Limit holds the context/output token limits.
Limit Limit `json:"limit"`
// Cost holds the per-million-token pricing in USD.
Cost Cost `json:"cost"`
}
Model is a single model offered by a Provider.
func GetModelByID ¶
GetModelByID returns a model by its fully qualified ID in "provider:model" form, e.g. "anthropic:claude-opus-4-8", using the shared Default client.
func (Model) SupportsInput ¶
SupportsInput reports whether the model accepts the given input modality.
func (Model) SupportsVision ¶
SupportsVision reports whether the model accepts image input.
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithHTTPClient ¶
WithHTTPClient sets the HTTP client used for fetching. Defaults to a client with a 20s timeout.
func WithTTL ¶
WithTTL sets how long a fetched catalog is cached before it is refetched. A non-positive ttl disables caching (every call refetches).
func WithUserAgent ¶
WithUserAgent sets the User-Agent header sent with catalog requests.
type Provider ¶
type Provider struct {
// ID is the models.dev provider identifier, e.g. "openai", "amazon-bedrock".
ID string `json:"id"`
// Name is the human-readable provider name, e.g. "OpenAI".
Name string `json:"name"`
// NPM is the @ai-sdk package for the provider, when one exists.
NPM string `json:"npm,omitempty"`
// Doc is a link to the provider's model documentation.
Doc string `json:"doc,omitempty"`
// Env lists the environment variables the provider's SDK reads for credentials.
Env []string `json:"env,omitempty"`
// Models is keyed by model ID (the same value as Model.ID).
Models map[string]Model `json:"models"`
}
Provider is a single inference provider listed on models.dev (OpenAI, Anthropic, Google, …) together with the models it serves.
Source Files
Directories