[FEATURE]: Allow custom provider models to reference official model definitions from Models.dev

[gzb1128]

Feature hasn't been suggested before.

• I have verified this feature I am about to request hasn't been suggested before.

Describe the enhancement you want to request

TL;DR: Allow a model in a custom provider to reference/alias an official model definition from Models.dev by ID, so limit, modalities, reasoning, interleaved, cost, etc. are inherited automatically without manual duplication.

---

Problem

Many users run self-hosted gateways or proxies (e.g. LiteLLM, OpenRouter-style routers, or enterprise AI hubs) that re-expose models already cataloged in Models.dev under providers like zai, moonshotai, minimax, anthropic, etc. Currently, every custom provider that offers these models must manually re-specify all model metadata:

{
  "provider": {
    "my-gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://my-gateway.example.com/api/v1" },
      "models": {
        "glm-5.1": {
          "name": "GLM-5.1",
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "attachment": false,
          "interleaved": { "field": "reasoning_content" },
          "modalities": { "input": ["text"], "output": ["text"] },
          "limit": { "context": 200000, "output": 131072 }
        },
        "kimi-k2.6": {
          "name": "Kimi-K2.6",
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "attachment": true,
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          "limit": { "context": 262144, "output": 131072 }
        },
        "MiniMax-M2.7": {
          "name": "MiniMax-M2.7",
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "modalities": { "input": ["text"], "output": ["text"] },
          "limit": { "context": 204800, "output": 131072 }
        }
      }
    }
  }
}

When the same models appear under multiple custom providers, all metadata is duplicated. This is error-prone and drifts out of sync with upstream model updates.

Suggested behavior

Add a way for a model in a custom provider to reference an official model definition. Proposed syntax options:

Option A — ref field (model-level reference)

{
  "provider": {
    "my-gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://my-gateway.example.com/api/v1" },
      "models": {
        "glm-5.1": {
          "ref": "zai/glm-5.1"
        },
        "kimi-k2.6": {
          "ref": "moonshotai/kimi-k2.6"
        },
        "MiniMax-M2.7": {
          "ref": "minimax/MiniMax-M2.7"
        }
      }
    }
  }
}

Option B — use id to auto-resolve from global Models.dev index

If a model id matches a known model in any Models.dev provider, automatically hydrate metadata:

{
  "provider": {
    "my-gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://my-gateway.example.com/api/v1" },
      "models": {
        "glm-5.1": {},       // auto-resolved from zai/glm-5.1 in Models.dev
        "kimi-k2.6": {},     // auto-resolved from moonshotai/kimi-k2.6
        "MiniMax-M2.7": {}   // auto-resolved from minimax/MiniMax-M2.7
      }
    }
  }
}

In both options, explicit user config fields should take precedence over the referenced definition (deep merge with user wins).

Benefits

1. DRY — no more duplicating limit, modalities, reasoning, interleaved, cost across custom providers.
2. Accuracy — metadata stays in sync with Models.dev as upstream providers update specs.
3. Ergonomics — adding a model to a custom gateway becomes a one-liner instead of a 10-line block.

Related

• [FEATURE]: Hydrate custom provider model metadata from /v1/models and Models.dev #25407 — Requests auto-hydration from /v1/models endpoint (complementary but different: that issue is about runtime discovery, this issue is about static config referencing).
• [Bug] Custom provider models fail with "maxOutputTokens must be >= 1" when limit is not defined #22253 — Custom provider models crash when limit is not defined (this would also be mitigated by auto-hydration from Models.dev).
• custom providers do not inherit provider loaders #18486 — Custom providers do not inherit provider loaders (related inheritance gap).

[github-actions]

This issue might be a duplicate of an existing issue. Please check:

• [FEATURE]: Hydrate custom provider model metadata from /v1/models and Models.dev #25407: Also requests hydrating custom provider model metadata from Models.dev — the end goal (avoiding manual duplication of model capability metadata for custom providers) appears substantially the same, even if the proposed mechanism differs slightly (static ref config vs. runtime /v1/models discovery). Please review whether your request could be addressed under that issue or if the distinction warrants a separate track.

[gzb1128]

Thanks for the triage. To clarify why this is distinct from #25407:

#25407 asks for runtime discovery — call the custom gateway's /v1/models endpoint at startup and hydrate metadata from whatever that endpoint returns. The gateway itself is the source of truth.

This issue asks for static config referencing — the user explicitly declares which models exist under their custom provider, and each model entry references a known model definition from Models.dev by ID. The Models.dev catalog is the source of truth.

The key difference:

	#25407	This issue
Source of truth	Gateway's /v1/models	Models.dev catalog
Discovery	Automatic (runtime)	Explicit (config)
Works for gateways that don't implement /v1/models?	No	Yes
Works behind firewalls / air-gapped networks?	No (needs to reach the gateway at startup)	Yes (Models.dev is already cached locally)
User controls which models appear?	No (all models from gateway)	Yes (whitelist via config)

In practice, many self-hosted gateways are internal proxies that forward to upstream providers. They don't always expose a standards-compliant /v1/models endpoint, and the models they serve are often exact re-exposures of models already in Models.dev. A static ref mechanism is both simpler and more reliable for this use case.

Both features are complementary and could coexist. But they solve different problems and should be tracked separately.