Global virtual models

config.example.yaml

@@ -336,6 +336,14 @@ nonstream-keepalive-interval: 0
 #     - name: "kimi-k2.5"
 #       alias: "k2.5"
 
+# Global virtual models (works across all auth types)
+# The provider is determined automatically from the model name via the alias mechanism.
+# virtual-models:
+#   - name: "fast"                 # client-facing model name used in requests
+#     model: "gpt-5-codex-mini"    # upstream model identifier
+#   - name: "quality"
+#     model: "claude-opus-4-5-20251101"
+
 # OAuth provider excluded models
 # oauth-excluded-models:
 #   gemini-cli:

internal/config/config.go

@@ -228,6 +228,16 @@ type OAuthModelAlias struct {
 	Fork  bool   `yaml:"fork,omitempty" json:"fork,omitempty"`
 }
 
+// VirtualModel defines a global virtual model alias that maps to a specific model.
+// Virtual models are resolved before provider selection and work across all providers
+// regardless of auth type. The provider is determined by the normal alias mechanism.
+type VirtualModel struct {
+	// Name is the client-facing virtual model name used in requests.
+	Name string `yaml:"name" json:"name"`
+	// Model is the upstream model identifier to route requests to.
+	Model string `yaml:"model" json:"model"`
+}
+
 // AmpModelMapping defines a model name mapping for Amp CLI requests.
 // When Amp requests a model that isn't available locally, this mapping
 // allows routing to an alternative model that IS available.
@@ -679,6 +689,9 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 	// Normalize global OAuth model name aliases.
 	cfg.SanitizeOAuthModelAlias()
 
+	// Normalize global virtual models.
+	cfg.SanitizeVirtualModels()
+
 	// Validate raw payload rules and drop invalid entries.
 	cfg.SanitizePayloadRules()
 
@@ -818,6 +831,33 @@ func (cfg *Config) SanitizeOAuthModelAlias() {
 	cfg.OAuthModelAlias = out
 }
 
+// SanitizeVirtualModels normalizes and deduplicates global virtual model definitions.
+// It trims whitespace, drops empty entries, and ensures virtual model names are unique globally.
+func (cfg *Config) SanitizeVirtualModels() {
+	if cfg == nil || len(cfg.VirtualModels) == 0 {
+		return
+	}
+	seenName := make(map[string]struct{}, len(cfg.VirtualModels))
+	clean := make([]VirtualModel, 0, len(cfg.VirtualModels))
+	for _, vm := range cfg.VirtualModels {
+		name := strings.TrimSpace(vm.Name)
+		model := strings.TrimSpace(vm.Model)
+		if name == "" || model == "" {
+			continue
+		}
+		nameKey := strings.ToLower(name)
+		if _, ok := seenName[nameKey]; ok {
+			continue
+		}
+		seenName[nameKey] = struct{}{}
+		clean = append(clean, VirtualModel{
+			Name:  name,
+			Model: model,
+		})
+	}
+	cfg.VirtualModels = clean
+}
+
 // SanitizeOpenAICompatibility removes OpenAI-compatibility provider entries that are
 // not actionable, specifically those missing a BaseURL. It trims whitespace before
 // evaluation and preserves the relative order of remaining entries.

internal/config/sdk_config.go

@@ -31,6 +31,11 @@ type SDKConfig struct {
 	// Streaming configures server-side streaming behavior (keep-alives and safe bootstrap retries).
 	Streaming StreamingConfig `yaml:"streaming" json:"streaming"`
 
+	// VirtualModels defines global virtual model aliases that map to specific upstream models.
+	// Virtual models are resolved before provider selection and work across all providers
+	// regardless of auth type. The provider is determined by the normal alias mechanism.
+	VirtualModels []VirtualModel `yaml:"virtual-models,omitempty" json:"virtual-models,omitempty"`
+
 	// NonStreamKeepAliveInterval controls how often blank lines are emitted for non-streaming responses.
 	// <= 0 disables keep-alives. Value is in seconds.
 	NonStreamKeepAliveInterval int `yaml:"nonstream-keepalive-interval,omitempty" json:"nonstream-keepalive-interval,omitempty"`

sdk/api/handlers/claude/code_handlers.go

@@ -129,7 +129,8 @@ func (h *ClaudeCodeAPIHandler) ClaudeCountTokens(c *gin.Context) {
 // Parameters:
 //   - c: The Gin context for the request.
 func (h *ClaudeCodeAPIHandler) ClaudeModels(c *gin.Context) {
-	models := h.Models()
+	models := h.AppendVirtualModels(h.Models())
+
 	firstID := ""
 	lastID := ""
 	if len(models) > 0 {

sdk/api/handlers/gemini/gemini_handlers.go

@@ -72,6 +72,19 @@ func (h *GeminiAPIHandler) GeminiModels(c *gin.Context) {
 		}
 		normalizedModels = append(normalizedModels, normalizedModel)
 	}
+
+	// Add virtual models from config
+	if h.Cfg != nil && len(h.Cfg.VirtualModels) > 0 {
+		for _, vm := range h.Cfg.VirtualModels {
+			normalizedModels = append(normalizedModels, map[string]any{
+				"name":                       "models/" + vm.Name,
+				"displayName":                vm.Name,
+				"description":                "Virtual model: " + vm.Name,
+				"supportedGenerationMethods": defaultMethods,
+			})
+		}
+	}
+
 	c.JSON(http.StatusOK, gin.H{
 		"models": normalizedModels,
 	})
@@ -116,7 +129,22 @@ func (h *GeminiAPIHandler) GeminiGetHandler(c *gin.Context) {
 		return
 	}
 
-	c.JSON(http.StatusNotFound, handlers.ErrorResponse{
+		// Check virtual models if not found in registry
+		if h.Cfg != nil && len(h.Cfg.VirtualModels) > 0 {
+			for _, vm := range h.Cfg.VirtualModels {
+				if vm.Name == action || vm.Name == strings.TrimPrefix(action, "models/") {
+					c.JSON(http.StatusOK, map[string]any{
+						"name":                       "models/" + vm.Name,
+						"displayName":                vm.Name,
+						"description":                "Virtual model: " + vm.Name,
+						"supportedGenerationMethods": []string{"generateContent"},
+					})
+					return
+				}
+			}
+		}
+
+		c.JSON(http.StatusNotFound, handlers.ErrorResponse{
 		Error: handlers.ErrorDetail{
 			Message: "Not Found",
 			Type:    "not_found",

sdk/api/handlers/handlers.go

@@ -288,6 +288,22 @@ func NewBaseAPIHandlers(cfg *config.SDKConfig, authManager *coreauth.Manager) *B
 //   - cfg: The new application configuration
 func (h *BaseAPIHandler) UpdateClients(cfg *config.SDKConfig) { h.Cfg = cfg }
 
+// AppendVirtualModels appends virtual model entries in OpenAI/Claude format to the given model list.
+func (h *BaseAPIHandler) AppendVirtualModels(models []map[string]any) []map[string]any {
+	if h.Cfg == nil || len(h.Cfg.VirtualModels) == 0 {
+		return models
+	}
+	for _, vm := range h.Cfg.VirtualModels {
+		models = append(models, map[string]any{
+			"id":       vm.Name,
+			"object":   "model",
+			"created":  int64(0),
+			"owned_by": "virtual",
+		})
+	}
+	return models
+}
+
 // GetAlt extracts the 'alt' parameter from the request query string.
 // It checks both 'alt' and '$alt' parameters and returns the appropriate value.
 //
@@ -796,6 +812,22 @@ func (h *BaseAPIHandler) getRequestDetails(modelName string) (providers []string
 	parsed := thinking.ParseSuffix(resolvedModelName)
 	baseModel := strings.TrimSpace(parsed.ModelName)
 
+	// Check if this is a virtual model first
+	if h.AuthManager != nil {
+		virtualModel := h.AuthManager.ResolveVirtualModel(baseModel)
+		if virtualModel != "" {
+			// Preserve the thinking suffix from the original request.
+			// e.g. "fast(8192)" -> resolve "fast" to "gpt-5-codex-mini" -> "gpt-5-codex-mini(8192)"
+			if initialSuffix.HasSuffix {
+				resolvedModelName = virtualModel + "(" + initialSuffix.RawSuffix + ")"
+			} else {
+				resolvedModelName = virtualModel
+			}
+			parsed = thinking.ParseSuffix(resolvedModelName)
+			baseModel = strings.TrimSpace(parsed.ModelName)
+		}
+	}
+
 	providers = util.GetProviderName(baseModel)
 	// Fallback: if baseModel has no provider but differs from resolvedModelName,
 	// try using the full model name. This handles edge cases where custom models

sdk/api/handlers/openai/openai_handlers.go

@@ -63,8 +63,8 @@ func (h *OpenAIAPIHandler) OpenAIModels(c *gin.Context) {
 	allModels := h.Models()
 
 	// Filter to only include the 4 required fields: id, object, created, owned_by
-	filteredModels := make([]map[string]any, len(allModels))
-	for i, model := range allModels {
+	filteredModels := make([]map[string]any, 0, len(allModels))
+	for _, model := range allModels {
 		filteredModel := map[string]any{
 			"id":     model["id"],
 			"object": model["object"],
@@ -80,9 +80,12 @@ func (h *OpenAIAPIHandler) OpenAIModels(c *gin.Context) {
 			filteredModel["owned_by"] = ownedBy
 		}
 
-		filteredModels[i] = filteredModel
+		filteredModels = append(filteredModels, filteredModel)
 	}
 
+	// Add virtual models from config
+	filteredModels = h.AppendVirtualModels(filteredModels)
+
 	c.JSON(http.StatusOK, gin.H{
 		"object": "list",
 		"data":   filteredModels,

sdk/cliproxy/auth/conductor.go

@@ -158,6 +158,9 @@ type Manager struct {
 	// It is initialized in NewManager; never Load() before first Store().
 	runtimeConfig atomic.Value
 
+	// virtualModels stores global virtual model definitions (name -> upstream model).
+	virtualModels atomic.Value
+
 	// Optional HTTP RoundTripper provider injected by host.
 	rtProvider RoundTripperProvider
 
@@ -1167,6 +1170,8 @@ func (m *Manager) Load(ctx context.Context) error {
 // Execute performs a non-streaming execution using the configured selector and executor.
 // It supports multiple providers for the same model and round-robins the starting provider per model.
 func (m *Manager) Execute(ctx context.Context, providers []string, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (cliproxyexecutor.Response, error) {
+	req = resolveVirtualModelForRequest(m, req)
+
 	normalized := m.normalizeProviders(providers)
 	if len(normalized) == 0 {
 		return cliproxyexecutor.Response{}, &Error{Code: "provider_not_found", Message: "no provider supplied"}
@@ -1198,6 +1203,8 @@ func (m *Manager) Execute(ctx context.Context, providers []string, req cliproxye
 // ExecuteCount performs a non-streaming execution using the configured selector and executor.
 // It supports multiple providers for the same model and round-robins the starting provider per model.
 func (m *Manager) ExecuteCount(ctx context.Context, providers []string, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (cliproxyexecutor.Response, error) {
+	req = resolveVirtualModelForRequest(m, req)
+
 	normalized := m.normalizeProviders(providers)
 	if len(normalized) == 0 {
 		return cliproxyexecutor.Response{}, &Error{Code: "provider_not_found", Message: "no provider supplied"}
@@ -1229,6 +1236,8 @@ func (m *Manager) ExecuteCount(ctx context.Context, providers []string, req clip
 // ExecuteStream performs a streaming execution using the configured selector and executor.
 // It supports multiple providers for the same model and round-robins the starting provider per model.
 func (m *Manager) ExecuteStream(ctx context.Context, providers []string, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (*cliproxyexecutor.StreamResult, error) {
+	req = resolveVirtualModelForRequest(m, req)
+
 	normalized := m.normalizeProviders(providers)
 	if len(normalized) == 0 {
 		return nil, &Error{Code: "provider_not_found", Message: "no provider supplied"}

sdk/cliproxy/auth/virtual_models.go

@@ -0,0 +1,87 @@
+package auth
+
+import (
+	"strings"
+
+	cliproxyexecutor "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/executor"
+
+	internalconfig "github.com/router-for-me/CLIProxyAPI/v6/internal/config"
+)
+
+// virtualModelTable stores the mapping of virtual model name to upstream model.
+type virtualModelTable struct {
+	// name maps virtual model name (lowercase) to upstream model.
+	name map[string]string
+}
+
+// compileVirtualModelTable builds a lookup table from virtual model definitions.
+func compileVirtualModelTable(models []internalconfig.VirtualModel) *virtualModelTable {
+	if len(models) == 0 {
+		return &virtualModelTable{}
+	}
+	out := &virtualModelTable{
+		name: make(map[string]string, len(models)),
+	}
+	for _, vm := range models {
+		vname := strings.TrimSpace(vm.Name)
+		model := strings.TrimSpace(vm.Model)
+		if vname == "" || model == "" {
+			continue
+		}
+		key := strings.ToLower(vname)
+		if _, exists := out.name[key]; exists {
+			// Skip duplicates (first wins due to sanitization dedup)
+			continue
+		}
+		out.name[key] = model
+	}
+	if len(out.name) == 0 {
+		out.name = nil
+	}
+	return out
+}
+
+// SetVirtualModels updates the virtual model table used during request execution.
+// Virtual models are resolved before provider selection and work across all auth types.
+func (m *Manager) SetVirtualModels(models []internalconfig.VirtualModel) {
+	if m == nil {
+		return
+	}
+	table := compileVirtualModelTable(models)
+	m.virtualModels.Store(table)
+}
+
+// resolveVirtualModelForRequest resolves the virtual model in a request and returns the
+// potentially modified request. This avoids repeating the same resolve block in every Execute* method.
+func resolveVirtualModelForRequest(m *Manager, req cliproxyexecutor.Request) cliproxyexecutor.Request {
+	if virtualModel := m.ResolveVirtualModel(req.Model); virtualModel != "" {
+		req.Model = virtualModel
+	}
+	return req
+}
+
+// ResolveVirtualModel attempts to resolve a requested model name through the virtual model table.
+// If the model is a virtual model, it returns the upstream model name.
+// If not virtual or resolution fails, it returns an empty string.
+func (m *Manager) ResolveVirtualModel(requestedModel string) string {
+	if m == nil || requestedModel == "" {
+		return ""
+	}
+	key := strings.ToLower(strings.TrimSpace(requestedModel))
+	if key == "" {
+		return ""
+	}
+	raw := m.virtualModels.Load()
+	if raw == nil {
+		return ""
+	}
+	table, ok := raw.(*virtualModelTable)
+	if !ok || table == nil || table.name == nil {
+		return ""
+	}
+	model, exists := table.name[key]
+	if !exists {
+		return ""
+	}
+	return model
+}

sdk/cliproxy/builder.go

@@ -225,6 +225,7 @@ func (b *Builder) Build() (*Service, error) {
 	coreManager.SetRoundTripperProvider(newDefaultRoundTripperProvider())
 	coreManager.SetConfig(b.cfg)
 	coreManager.SetOAuthModelAlias(b.cfg.OAuthModelAlias)
+	coreManager.SetVirtualModels(b.cfg.VirtualModels)
 
 	service := &Service{
 		cfg:            b.cfg,

sdk/cliproxy/service.go

@@ -660,6 +660,7 @@ func (s *Service) Run(ctx context.Context) error {
 		if s.coreManager != nil {
 			s.coreManager.SetConfig(newCfg)
 			s.coreManager.SetOAuthModelAlias(newCfg.OAuthModelAlias)
+			s.coreManager.SetVirtualModels(newCfg.VirtualModels)
 		}
 		s.rebindExecutors()
 	}

sdk/config/config.go

@@ -15,6 +15,7 @@ type TLSConfig = internalconfig.TLSConfig
 type RemoteManagement = internalconfig.RemoteManagement
 type AmpCode = internalconfig.AmpCode
 type OAuthModelAlias = internalconfig.OAuthModelAlias
+type VirtualModel = internalconfig.VirtualModel
 type PayloadConfig = internalconfig.PayloadConfig
 type PayloadRule = internalconfig.PayloadRule
 type PayloadFilterRule = internalconfig.PayloadFilterRule