Concepts · ai
Models
Model struct, identification, modalities, cost, and provider compatibility
- Adding or configuring a model
- Working with model metadata or pricing
This page gives the model metadata used to bind providers and calculate cost. A Model describes an AI model and its capabilities. Models are plain structs. They carry metadata but do not run anything. Providers run model calls.
Design: data, not behavior
Models are value types with no methods and no provider identity. They contain only intrinsic metadata. This keeps them serializable and free from provider dependencies. Any provider that serves a model can bind it. ai.NewLanguageModel(model, provider) produces the callable unit. The catalog performs the same binding when it resolves a spec string.
Identification
IDis the canonical identifier sent to the provider, for example"claude-sonnet-4-6".Aliasesregister extra lookup specs in a catalog,"<provider>/<alias>".
Catalog and lookup
Provider identity lives in catalog.Catalog, not on the model. Registering a provider ingests every model that it serves. The catalog keys each model by "<provider>/<ID>" and one key per alias. Each provider package ships a generated model table. make gen sources those tables from models.dev. Registering a provider makes its models resolvable.
catalog.GenerateText(ctx, "anthropic-messages/claude-sonnet-4-6", prompt) resolves the spec to a bound model and runs it. Callers can name a model by string instead of constructing one. StreamText, GenerateObject[T], GenerateImage, and GenerateSpeech share the same spec-first form. Every modality uses the same access pattern on a Catalog and package-level helpers in pi.
A bare model ID, such as "claude-sonnet-4-6", also resolves when exactly one registered provider serves it. If several providers serve it, the error lists the full specs to choose from. This keeps the happy path free of internal provider identities like "anthropic-messages".
Modalities
Input and Output describe what the model accepts and produces, such as text and image. These fields are advisory. Providers can reject unsupported modality combinations at call time.
Cost
Cost defines per-million-token pricing in USD. CalculateCost(model, usage) computes the cost breakdown for a response. See Usage.
Provider compatibility
ProviderCompat is an optional interface for provider-specific compatibility metadata. JSON excludes it. Providers that need cross-compatible model handling implement this interface. One example is mapping between different tool calling conventions.