Model catalog

The model catalog stores normalized metadata and external reference prices used to enrich model resources. It does not contain provider credentials, create upstreams, or define the model price charged to users.

Catalog fields

Reference pricing

Prices imported from models.dev, OpenRouter, and similar catalogs are comparison metadata only. They never participate in user settlement. An administrator maintains actual model prices manually on the Platform models page, and catalog imports cannot overwrite them.

Reference prices use controlled semantic pricing units:

Price records do not accept arbitrary multipliers. models.dev token prices are stored directly; OpenRouter per-token prices are converted through an exact decimal adapter at the import boundary. The database, internal APIs, and UI use per-million-token prices exclusively; only the LiteLLM runtime adapter converts them back to per-token prices. Currency, source, observation time, and conditional tiers remain part of the immutable reference-price version.

Import rules

• Capability metadata follows source priority: models.dev (priority 10) wins, OpenRouter (priority 20) is the fallback, and explicit administrator overrides have the highest priority. APIs preserve the source code, observation time, and coverage state.
• Each channel model can store a structured reasoning transport profile with its mapping, carried efforts, parameter style, provenance, verification time, and runtime version. An explicit profile may only narrow native model support; an unknown or mismatched level is never substituted with a lower one.
• The models.dev models collection is authoritative for canonical model identities. Its providers collection only contributes inference-channel mappings, channel model IDs, and reference prices.
• Provider records first match catalog models by exact source identity. Name matching is allowed only when the display name is globally unique. Ambiguous records are reported as unmatched and never create guessed catalog models.
• OpenRouter uses the permanent canonical_slug for author and canonical-model identity, while its callable id becomes the OpenRouter provider-model ID. A record without a permanent identity is invalid.
• The reference catalog can retain cache write, reasoning, image/audio/video quantities and tokens, audio transcription, citation tokens, OCR pages or credits, and web search as distinct descriptive meters, but they do not automatically become selling prices. Administrators can choose from all 24 bidirectionally verified meters according to model capability. Supported conditions include verified long-context thresholds, one-hour cache write, 1080p output video, and a shared off-peak schedule for five token rates: uncached input, cache read, standard cache write, ordinary output, and reasoning output. The off-peak schedule can combine multiple UTC time windows and applicable weekdays; every window uses the same set of off-peak rates. The weekday timezone only determines the weekday of the pricing instant, while window times always use UTC. Dedicated image calls select one configured output-image count, output-megapixel, or output-image-token branch, while OCR prefers credits only when credits are reported and a credit price is configured. Audio transcription, speech input characters, output megapixels, and Rerank search units project to fields consumed by LiteLLM 1.102.0-rc.1 and are recovered as numeric-only callback metadata. Type-only output-audio-duration and output_cost_per_pixel fields that its calculators do not consume remain unsupported selling prices. The upstream generic tiered_pricing support is not yet part of this bidirectional selling-price contract. OpenRouter's one-hour cache-write reference price is imported with cacheTtlSeconds=3600. Catalog-only fixed request fees and fields without a stable calculation-and-Spend-recovery contract never enter selling prices.
• Every source record stores raw and normalized data, normalization version, and a content hash. A normalization-version upgrade forces a fresh fetch and reprocessing even if the upstream ETag is unchanged.

Relationship to model resources

Upstream /models discovery creates model resources and proves only that the credential can see a model ID; it is not a complete capability declaration. Every read resolves catalog capabilities from the current inference channel and channel-model ID, so discovered resources store neither a catalog foreign key nor a second metadata snapshot. Catalog imports, manual mapping edits, and upstream channel changes therefore take effect without a link-refresh step. The model author describes who created the model; the inference channel describes where the model can be called. A missing mapping does not mean the model is unavailable; it means complete capability metadata is not known.

For a published model with failover candidates, commonCapabilities is the intersection of every candidate's catalog declaration and is used for configuration matching. availableCapabilities is the union and means only that at least one candidate declares the capability. Any unmapped candidate makes coverage partial and conservatively reduces the common set.

Callability still depends on the upstream, credential, and connection result.

Permissions and use

Regular users normally read catalog models. Authors are global entities: an administrator manages the author code, name, and logo separately before creating a manual catalog model. Editing a catalog model never creates or renames an author implicitly, and an author referenced by a catalog model or inference channel cannot be deleted. Updating a catalog model or channel mapping is reflected the next time a resource is read.

• Check required streaming, tool, vision, or reasoning capabilities before configuration.
• Compare the model author, canonical model ID, and provider mappings rather than relying on the display name alone.
• Rediscover models after an author releases a new version.
• Validate custom models directly when no catalog model exists.