DOCSEARCHbyAlgolia
Submit Docs

Models.dev Documentation

repository·dev·Indexed 26 days ago

https://github.com/anomalyco/models.dev

An open-source database of AI model specifications, pricing, and capabilities. It provides a unified source of truth for model metadata and provider information via the @opencode-ai/models typed client, which supports standard, offline snapshot, and Effect-native entrypoints. The project includes provider-specific configurations and synchronization scripts for Cloudflare AI Gateway, Helicone, Neuralwatt, Venice AI, and Vercel AI Gateway.

Tokens
10.2K
Snippets
27
Records
69
Agent score
92%

What's inside Models.dev

  1. Overview of Models.dev

    dev
    Models.dev is an open-source database providing comprehensive specifications, pricing, and capabilities for AI models. It serves as a centralized resource for model metadata and is used internally by opencode.

  2. Add a Model Definition

    dev

    Create a TOML file in the provider's models/ directory. The filename is the model ID. If the ID contains a slash (e.g., openai/gpt-5), use subfolders (providers/openai/models/gpt-5.toml).

    Key fields include name, attachment, reasoning, tool_call, structured_output, temperature, knowledge, release_date, last_updated, open_weights, and tables for [cost], [limit], [modalities], and [interleaved].

    name = "Model Display Name"
attachment = true           # or false
reasoning = false           # or true
tool_call = true            # or false
structured_output = true    # or false
temperature = true          # or false
knowledge = "2024-04"
release_date = "2025-02-19"
last_updated = "2025-02-19"
open_weights = true

[cost]
input = 3.00
output = 15.00
reasoning = 15.00
cache_read = 0.30
cache_write = 3.75
input_audio = 1.00
output_audio = 10.00

[limit]
context = 400_000
input = 272_000
output = 8_192

[modalities]
input = ["text", "image"]
output = ["text"]

[interleaved]
field = "reasoning_content"

  3. Sync DigitalOcean models

    dev

    DigitalOcean synchronization is implemented in packages/core/src/sync/providers/digitalocean.ts using two endpoints:

    • https://api.digitalocean.com/v2/gen-ai/models (lifecycle and reasoning metadata)
    • https://api.digitalocean.com/v2/gen-ai/models/catalog (availability, modalities, limits, and pricing)

    Authentication:

    • Requires DIGITALOCEAN_API_TOKEN or DIGITALOCEAN_ACCESS_TOKEN for the control-plane endpoint. The catalog endpoint is public.

    Behavior:

    • Manages serverless text-output models.
    • Retains other model types, dedicated-only models, and local models absent from the API for manual review.
    • Catalog pricing updates standard, cache-read, cache-write, and extended-context rates while preserving authored reasoning and audio prices.

  5. Generate Helicone model TOML files

    dev

    Use the helicone:generate command to fetch model data from Helicone's public registry and generate individual TOML configuration files.

    Details:

    • Source: https://jawn.helicone.ai/v1/public/model-registry/models
    • Output Path: providers/helicone/models/<model-id>.toml
    • Structure: The generator produces a flat directory structure (no nested provider folders). For example, a model might be saved as providers/helicone/models/claude-3.5-haiku.toml.
    • Cleanup: The generator automatically cleans the output folder before writing, removing any existing nested provider folders or old TOML files to maintain the flat structure.
    bun run helicone:generate

  6. Sync Venice AI model TOMLs

    dev

    Use the Venice sync script to generate and update model TOML files from the Venice AI API. The script fetches model data from https://api.venice.ai/api/v1/models?type=text and outputs them to providers/venice/models/<model-id>.toml.

    Key behaviors:

    • Merge behavior: Updates fields sourced from the API while preserving manual fields.
    • Deletion: Provider files that are no longer present in the API response will be deleted.
    • Exclusions: The script skips E2EE (End-to-End Encrypted) models as they require unsupported client-side encryption.
    • Dry Run: Use the --dry-run flag to preview changes before they are applied to the filesystem.

  7. Add a New Provider

    dev

    To add a new provider, create a folder in providers/ named after the provider's ID and add a provider.toml file.

    For standard providers, include name, npm (the AI SDK package name), env (array of required environment variable keys), and doc (documentation link).

    For OpenAI-compatible endpoints that do not have a dedicated npm package, use @ai-sdk/openai-compatible and provide the api base URL.

    name = "Provider Name"
npm = "@ai-sdk/provider"
env = ["PROVIDER_API_KEY"]
doc = "https://example.com/docs/models"

  8. Set up the Cloudflare AI Gateway Provider

    dev

    To use the Cloudflare AI Gateway provider, you must first configure your environment with the necessary Cloudflare credentials and then run the synchronization scripts to generate the model configuration files.

    Prerequisites

    • A Cloudflare account with AI Gateway configured.
    • The following environment variables set:
      • CLOUDFLARE_API_TOKEN: Your Cloudflare API token.
      • CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID.
      • CLOUDFLARE_GATEWAY_ID: Your AI Gateway name/ID.

    Running the Synchronization Scripts

    Run the scripts in sequence to fetch data, map names, and generate TOML files:

    1. Fetch model data: Downloads the latest model list from the Cloudflare API.
    2. Update model names: Updates data/model_names.json with human-readable mappings.
    3. Generate TOML files: Creates the final configuration files in the models/ directory.
    # Step 1: Fetch model data from Cloudflare API
cd scripts
CLOUDFLARE_API_TOKEN=xxx \
CLOUDFLARE_ACCOUNT_ID=xxx \
CLOUDFLARE_GATEWAY_ID=xxx \
./01_fetch_model_data.sh

# Step 2: Update model name mappings
./02_generate_model_names.sh

# Step 3: Generate TOML files
./03_generate_model_toml.sh

  9. Sync xAI models

    dev

    xAI model synchronization is implemented in packages/core/src/sync/providers/xai.ts. It uses three endpoints: https://api.x.ai/v1/language-models, https://api.x.ai/v1/image-generation-models, and https://api.x.ai/v1/video-generation-models.

    Authentication:

    • Requires XAI_API_KEY.

    Behavior:

    • Provides model IDs, creation timestamps, modalities, pricing (for language models), and prompt/input limits.
    • Updates existing models with API-authoritative fields while preserving local metadata for fields not exposed by the API (like output token limits).
    • New API models are not created automatically (skipCreates).
    • Missing IDs trigger a deduped GitHub issue.
    • Alias IDs that match existing canonical IDs are skipped silently.

  12. Add Model Metadata

    dev

    To define provider-agnostic facts about a model, create a TOML file in the models/ directory using the same path-style ID as provider models (e.g., models/openai/gpt-5.toml).

    Use this for properties like name, family, release_date, knowledge, attachment, reasoning, tool_call, structured_output, temperature, and default [limit] or [modalities] settings. You can also include [[benchmarks]] and [[weights]] arrays.

    name = "GPT-5"
family = "gpt"
release_date = "2025-08-07"
last_updated = "2025-08-07"
attachment = true
reasoning = true
temperature = false
tool_call = true
structured_output = true
open_weights = false

[limit]
context = 400_000
input = 272_000
output = 128_000

[modalities]
input = ["text", "image"]
output = ["text"]

[[benchmarks]]
name = "Benchmark Name"
score = 72.5
metric = "accuracy"
source = "https://example.com/results"

[[weights]]
label = "Model weights"
url = "https://huggingface.co/example/model"
format = "safetensors"