# Auto Router

> Automatically selects a suitable text model for each request through Modelverse.

## Overview

Auto Router is Modelverse's automatic model routing capability. Callers do not need to specify a particular model manually for every request. Set `model` to `auto`, and Modelverse selects a suitable model from the available model pool based on the request content, task type, prompt complexity, context length, model capabilities, and cost preferences.

Auto Router uses Modelverse's OpenAI Chat Completions-compatible API and is suitable when you:

- Do not want to maintain a fixed model list in your application code.
- Want simple tasks to use more economical models and complex tasks to use more capable models.
- Want to minimize application-side changes when models are upgraded or the model pool changes.
- Want to retain OpenAI-compatible request and response formats.

## API Endpoint

The default endpoint for access from mainland China is:

```text
https://api.modelverse.cn/v1/chat/completions
```

If you require overseas access, lower latency, or data residency, you can select another Modelverse endpoint according to your project configuration. The request path remains the same; only the domain needs to be replaced.

## Quick Start

Set `model` to `auto` to enable automatic routing.

### TypeScript (fetch)

```typescript
const response = await fetch('https://api.modelverse.cn/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <MODELVERSE_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'auto',
    messages: [
      {
        role: 'user',
        content: 'Explain quantum entanglement in simple terms',
      },
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);
console.log('Model actually used:', data.model);
```

### Python (requests)

```python
import json
import requests

response = requests.post(
    'https://api.modelverse.cn/v1/chat/completions',
    headers={
        'Authorization': 'Bearer <MODELVERSE_API_KEY>',
        'Content-Type': 'application/json',
    },
    data=json.dumps({
        'model': 'auto',
        'messages': [
            {
                'role': 'user',
                'content': 'Explain quantum entanglement in simple terms',
            }
        ],
    }),
)

data = response.json()
print(data['choices'][0]['message']['content'])
print('Model actually used:', data['model'])
```

### Python (OpenAI SDK)

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url='https://api.modelverse.cn/v1',
    api_key=os.environ['MODELVERSE_API_KEY'],
)

response = client.chat.completions.create(
    model='auto',
    messages=[
        {
            'role': 'user',
            'content': 'Explain quantum entanglement in simple terms',
        }
    ],
)

print(response.choices[0].message.content)
print('Model actually used:', response.model)
```

## Request Parameters

Auto Router reuses the common Chat Completions parameters. Common fields are listed below:

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Always set to `auto` to enable automatic routing. |
| `messages` | array | Yes | An OpenAI-compatible list of messages. |
| `stream` | boolean | No | Whether to use an SSE streaming response. |
| `temperature` | number | No | Sampling temperature, forwarded to the model that actually executes the request. |
| `top_p` | number | No | Nucleus sampling parameter, forwarded to the model that actually executes the request. |
| `max_tokens` | number | No | Maximum number of output tokens. |
| `allowed_models` | array | No | Restricts the set of candidate models. Only exact model names are supported. If omitted or empty, all available candidate models are used. |

## Response Format

The response retains the Chat Completions-compatible format. The `model` field contains the model selected for this request, making it useful for log tracing, cost analysis, and troubleshooting.

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 150,
    "total_tokens": 165
  }
}
```

For streaming requests, the response is still returned as SSE chunks. We recommend recording the complete response or the `model` field in the final aggregated result in your logs to confirm which model actually executed the request.

## How It Works

Auto Router follows this execution flow:

1. **Parse the request**: Read `messages`, context length, task intent, and the optional `allowed_models` configuration.
2. **Filter candidate models**: Build a candidate set based on account permissions, model availability, candidate-model rules, and task requirements.
3. **Select an execution model**: Select a model based on its capabilities, quality preferences, cost preferences, context requirements, and service status.
4. **Forward the request**: Forward the original Chat Completions request to the selected model.
5. **Return the result**: Return the result in an OpenAI-compatible format and identify the actual model in the `model` field.

## Session Affinity

Auto Router supports session affinity. When the same session sends consecutive requests within a short period, the system attempts to keep the same model and provider. This reduces style fluctuations caused by switching models during multi-turn conversations and improves cache hit rates.

Session affinity rules:

- The system generates a session fingerprint from the first `system` message and the first `user` message.
- After a session-affinity cache hit, subsequent requests prioritize the previously selected model and provider.
- The affinity cache expires after a period without requests.
- If the model or provider in the cache is unavailable, the system routes the request again.

In most cases, the application does not need to handle session affinity. For multi-turn conversations, we recommend keeping the initial `system` message and the user's initial intent stable to avoid changing the session fingerprint unnecessarily.

## Supported Models

Auto Router currently selects from the following models. When using `allowed_models` to restrict the candidate set, use the exact model names below.

| Model ID |
| --- |
| `claude-sonnet-4-6` |
| `claude-opus-4-6` |
| `claude-opus-4-7` |
| `claude-opus-4-8` |
| `claude-haiku-4-5-20251001` |
| `kimi-k2.6` |
| `kimi-k2.7-code` |
| `glm-5.2` |
| `deepseek-v4-flash` |
| `deepseek-v4-pro` |
| `MiniMax-M3` |
| `gpt-5.5` |
| `gpt-5.4-mini` |
| `gpt-5.4-nano` |
| `qwen3.7-plus` |
| `qwen3.7-max` |
| `gemini-3.5-flash` |
| `gemini-3.1-pro-preview` |

## Restricting Candidate Models

You can use the top-level `allowed_models` parameter to restrict the candidate model set. This is useful when you:

- Want automatic selection from only a specified group of models.
- Need to exclude models that have not completed business validation.
- Want different business lines to use different model pools.
- Are rolling out a new model gradually and want only some requests to participate in routing.

Rules for `allowed_models`:

- If the field is omitted, all Auto Router candidate models accessible to the account are used.
- An empty array `[]` behaves the same as an omitted field.
- For a non-empty array, the system uses the intersection of `allowed_models` and the server-side Auto Router model pool.
- Only exact model names are supported; wildcard matching is not supported.
- Empty strings and duplicate models in the array are ignored.
- The request fails if the intersection is empty or the API key does not have permission to use any candidate model.

### Request Example

```typescript
const response = await fetch('https://api.modelverse.cn/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <MODELVERSE_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'auto',
    messages: [
      {
        role: 'user',
        content: 'Explain quantum entanglement',
      },
    ],
    allowed_models: [
      'claude-sonnet-4-6',
      'deepseek-v4-pro',
      'glm-5.2'
    ],
  }),
});
```

### Python Example

```python
response = requests.post(
    'https://api.modelverse.cn/v1/chat/completions',
    headers={
        'Authorization': 'Bearer <MODELVERSE_API_KEY>',
        'Content-Type': 'application/json',
    },
    data=json.dumps({
        'model': 'auto',
        'messages': [
            {
                'role': 'user',
                'content': 'Explain quantum entanglement',
            }
        ],
        'allowed_models': [
            'claude-sonnet-4-6',
            'deepseek-v4-pro',
            'glm-5.2',
        ],
    }),
)
```

### Matching Rules

`allowed_models` currently uses exact model-name matching. It does not expand prefixes, providers, or wildcards.

| Syntax | Supported | Description |
| --- | --- | --- |
| `deepseek-v4-pro` | Yes | Exact match for one candidate model. |
| `glm-5.2` | Yes | Exact match for one candidate model. |
| `claude-sonnet-4-6` | Yes | Exact match for one candidate model. |
| `deepseek-*` | No | Not expanded as a wildcard. |
| `*/claude-*` | No | Not matched by provider or model-name prefix. |

## Cost and Quality Trade-offs

Auto Router currently does not expose an independent request parameter for balancing cost and quality. Routing strategies are configured centrally by the server and take the candidate model set, account permissions, model availability, and request content into account.

For stronger cost control, use `allowed_models` to limit the candidate set to models that have been evaluated. For more consistent quality, include only models that have been verified to meet your quality requirements.

## Configure Claude Code in cc-switch

This section applies when you want to use [cc-switch](https://github.com/farion1231/cc-switch) to manage Claude Code providers and forward Claude Code requests to the Modelverse Auto Router.

1. In cc-switch, add or edit a provider and enter your Modelverse API key.
2. Enter the following request URL. Do not add a trailing slash:

   ```text
   https://api.modelverse.cn/v1
   ```

3. Expand the advanced options and set **API Format** to **OpenAI Chat Completions (Enable Routing)**.
4. Set **Authentication Field** to `ANTHROPIC_AUTH_TOKEN`. This makes cc-switch write the provider API key to the authentication environment variable read by Claude Code.

   ![cc-switch provider configuration](https://cdnv2.udelivrs.com/2026/07/0d6f38f06cc58c17691be8ce37d5ee06_1783478441975.png)

5. Under **Model Mapping**, map all Claude Code model roles to Auto Router.

   | Model role | Display name | Actual request model | Declare 1M support |
   | --- | --- | --- | --- |
   | Sonnet | `auto` | `auto` | Select as needed |
   | Opus | `auto` | `auto` | Select as needed |
   | Fable | `auto` | `auto` | Not recommended |
   | Haiku | `auto` | `auto` | Configure as needed |

   `Display name` only affects the model menu shown by Claude Code. The value actually sent to Modelverse is `Actual request model`. With `auto` in this field, Modelverse selects a model automatically based on the request content.

   ![cc-switch model mapping](https://cdnv2.udelivrs.com/2026/07/84d0da93ae0d52466c22cb1b0738528d_1783478441988.png)

6. To restrict Auto Router's candidate models, configure a body override under **Local Proxy Request Overrides**.

   Header override example:

   ```json
   {
     "X-Provider": "cc-switch"
   }
   ```

   Body override example:

   ```json
   {
     "allowed_models": [
       "kimi-k2.7-code",
       "glm-5.2"
     ]
   }
   ```

   `allowed_models` supports exact model names only. If it is not configured or is an empty array, Auto Router uses all candidate models available to the account.

   ![cc-switch request overrides](https://cdnv2.udelivrs.com/2026/07/9c8e489bf9b30324401b146b3faf992e_1783478441992.png)

7. After saving the provider configuration, return to the cc-switch home page, enable cc-switch local routing, and select the UCloud provider you just configured.

   ![Enable local routing in cc-switch](https://cdnv2.udelivrs.com/2026/07/f2eac6739e8c744743b19437555e4b2c_1783478442006.png)

8. Open a new terminal and run:

   ```bash
   claude "Hello"
   ```

   If content is returned normally, Claude Code is forwarding requests to Modelverse Auto Router through cc-switch. You can also run `/status` in Claude Code to verify that the environment variables and routing configuration are active.

## Streaming Responses

Auto Router supports `stream: true`. Routing occurs at the beginning of the request, after which tokens are continuously returned by the model that was selected.

```bash
curl -N https://api.modelverse.cn/v1/chat/completions \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "auto",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "Write a 200-word product introduction"
      }
    ]
  }'
```

Streaming responses are recommended for long answers, complex reasoning, or requests that may otherwise time out.

## Recommendations

- Record `id`, `model`, `usage`, and the business request identifier in production logs to troubleshoot routing results.
- For quality-sensitive critical paths, first use `allowed_models` to limit routing to a verified model pool, then gradually expand the range.
- For large batches of low-risk tasks, you can increase `cost_quality_tradeoff` to reduce overall calling costs.
- Keep the first `system` and first `user` messages stable in multi-turn conversations to make better use of session affinity.
- If a business process must use a fixed model, do not use `auto`; pass the specific model ID directly.

## Frequently Asked Questions

### How can I find out which model was used for this request?

Check the `model` field in the response. It identifies the model that Auto Router selected to execute the request.

### Does Auto Router change the request format?

No. Requests continue to use Modelverse's Chat Completions-compatible format. Except for setting `model` to `auto` and optionally configuring `plugins`, other parameters are used in the same way as for a standard chat completion request.

### What if no model is available after restricting the candidates?

The request may fail if the `allowed_models` rules are too restrictive or the account lacks permission for the specified models. Check the model names, wildcard rules, and the model permissions associated with the API key.

### Can Auto Router be used with streaming output?

Yes. Set `stream: true`. Model selection is completed when the request starts, and subsequent chunks are returned from the selected model.

### When is Auto Router not recommended?

If your business requires completely fixed model behavior, a fixed provider, a fixed pricing strategy, or strictly reproducible experiment results, specify a model ID directly.