Intelligent Routing API Reference

The intelligent routing API is available in the China (Beijing) and Singapore regions, and supports pay-as-you-go billing only (charge_type="post_paid"). For the business description of intelligent routing (routing strategy, candidate models, invocation methods, and usage limits), see Intelligent Routing.

Prerequisites

Read Intelligent Routing to understand concepts such as route model versions, routing strategies, and candidate models.
A Bailian API key is configured. For more information, see Obtain an API key.
The request domain varies by region: the Beijing region uses dashscope.aliyuncs.com, and the Singapore region uses dashscope-intl.aliyuncs.com; the workspace-specific domain ({WorkspaceId}.{region}.maas.aliyuncs.com) is available in all regions. For the complete domain information of each region, see Regions and service deployment scopes.

API Overview

Intelligent routing services reuse the model deployment /api/v1/deployments series of APIs, and use plan="mr" in requests to distinguish the deployment type:

Function	API
Get a List of Model Routing Versions	`GET /api/v1/deployments/model-routing/versions`
Create an Intelligent Routing Service	`POST /api/v1/deployments`
List Intelligent Routing Services	`GET /api/v1/deployments?plan=mr`
Query Intelligent Routing Service Details	`GET /api/v1/deployments/{deployed_model}`
Edit the Routing Configuration	`PUT /api/v1/deployments/{deployed_model}/update`
Delete an Intelligent Routing Service	`DELETE /api/v1/deployments/{deployed_model}`

Get a List of Model Routing Versions

Before creating or editing an intelligent routing service, call this API to query the available route model versions, and the strategies and candidate models supported by each version. No request body is required, and plan is not passed.

GET https://dashscope.aliyuncs.com/api/v1/deployments/model-routing/versions

Request Example

curl "https://dashscope.aliyuncs.com/api/v1/deployments/model-routing/versions?page_no=1&page_size=50" \
    --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
    --header 'Content-Type: application/json'

Request Parameters

Parameter	Type	Passing Parameters	Required	Description
page_no	Number	query	No	Page number. Default is 1. Must be greater than 0.
page_size	Number	query	No	Page size. Default is 50. Range is 1-1000.

Response Example and Parameters

Click to view the details.

After the command is executed, the following result is obtained (the versions and candidate models are format examples only, and the actual query result prevails):

{
    "request_id": "<request-id>",
    "output": {
        "total": 1,
        "page_no": 1,
        "page_size": 50,
        "total_page": 1,
        "route_model_versions": [
            {
                "route_model_version": "model-router-20260908",
                "supported_strategies": ["EFFECT_FIRST", "COST_FIRST"],
                "supported_candidate_model_ids": ["qwen3.8-flash", "qwen3.7-plus"],
                "offline_model_ids": []
            }
        ]
    }
}

Parameter	Type	Description
total	Long	Total number of selectable routing versions.
total_page	Number	Total number of pages.
page_no	Number	Current page number.
page_size	Number	Current page size.
route_model_versions	Array	List of routing versions on the current page.
route_model_versions[].route_model_version	String	Routing version identifier, submitted when you create or edit a deployment.
route_model_versions[].supported_strategies	Array	Strategies supported by this version: `EFFECT_FIRST` (effect first) and `COST_FIRST` (cost first).
route_model_versions[].supported_candidate_model_ids	Array	Set of candidate model IDs supported by this version and not offline.
route_model_versions[].offline_model_ids	Array	Set of model IDs already offline in this version. It is an empty array when no models are offline.

This API does not return inference permission information about candidate models: the appearance of a model in supported_candidate_model_ids does not indicate that the current workspace has been granted invocation authorization for the model. Models without permission are filtered out in real time by the routing service during invocation.
The server filters selectable versions before paginating. If the queried page number exceeds the total number of pages, an empty route_model_versions is returned and the total is retained. Paginate by total_page to obtain all results.

Create an Intelligent Routing Service

POST https://dashscope.aliyuncs.com/api/v1/deployments

Creating an intelligent routing service requires only the service name and the three routing configuration fields (routing_config is required, and its values are obtained by calling the Get a List of Model Routing Versions API). Do not pass model_name:

Request Example

curl "https://dashscope.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "name": "my-router",
    "plan": "mr",
    "charge_type": "post_paid",
    "routing_config": {
        "route_model_version": "model-router-20260908",
        "strategy": "EFFECT_FIRST",
        "candidate_model_ids": ["qwen3.8-flash", "qwen3.7-plus"]
    }
}'

Request Parameters

Parameter	Type	Passing Parameters	Required	Description
name	String	body	Yes	Service name: 1-64 characters, only letters, digits, and hyphens are allowed.
plan	String	body	Yes	Deployment plan. Set this parameter to `mr` when you create an intelligent routing service.
charge_type	String	body	No	Billing method. Intelligent routing supports only `post_paid` (pay-as-you-go, the default).
routing_config	Object	body	Yes	Intelligent routing configuration, which contains the following fields.
routing_config.route_model_version	String	body	Yes	Route model version, which is obtained by calling the Get a List of Model Routing Versions API.
routing_config.strategy	String	body	Yes	Routing strategy: `EFFECT_FIRST` (effect first) and `COST_FIRST` (cost first).
routing_config.candidate_model_ids	Array	body	Yes	List of candidate model IDs, with at least 1 ID. The IDs must be within the supported range of the selected route model version. Duplicate values are merged, and the order has no routing significance.

When plan is mr, do not pass model_name. Parameters such as suffix, display_name, deploy_spec, SKU, templates, capacity, rate limits, and thinking/context are also not supported. Candidate models that are offline or whose metadata is unavailable cannot be submitted.

Response Example and Parameters

After the creation succeeds, the deployment is immediately in the RUNNING status. deployed_model is the deployment instance ID (in the format of auto-model-Ab12Cd34), and the client uses this deployed_model as the model parameter to make calls. model_name is a fixed value auto-model and does not represent the route model version:

{
    "request_id": "<request-id>",
    "output": {
        "name": "my-router",
        "deployed_model": "auto-model-Ab12Cd34",
        "model_name": "auto-model",
        "status": "RUNNING",
        "workspace_id": "llm-8v53e*******",
        "charge_type": "post_paid",
        "creator": "16542902******",
        "modifier": "16542902******",
        "gmt_create": "2026-01-15T10:00:00",
        "gmt_modified": "2026-01-15T10:00:00",
        "plan": "mr",
        "routing_config": {
            "route_model_version": "model-router-20260908",
            "strategy": "EFFECT_FIRST",
            "candidate_model_ids": ["qwen3.8-flash", "qwen3.7-plus"]
        }
    }
}

Parameter	Type	Description
request_id	String	ID of this request.
name	String	Service name.
deployed_model	String	Deployment instance ID (the `auto-model-` prefix followed by 8 characters), which is passed as the `model` parameter during invocation.
model_name	String	Fixed value `auto-model`, which does not represent the route model version.
status	String	Deployment status: `RUNNING` (running), `UPDATING` (updating), `FAILED` (failed), `DELETED` (deleted).
workspace_id	String	ID of the workspace to which the deployment belongs.
charge_type	String	Fixed to `post_paid`.
plan	String	Fixed to `mr`.
creator	String	UID of the creator.
modifier	String	UID of the account that performed the last operation.
gmt_create	String	Creation time.
gmt_modified	String	Last modification time.
routing_config	Object	Current routing configuration. The fields are the same as the request parameters.

List Intelligent Routing Services

GET https://dashscope.aliyuncs.com/api/v1/deployments

Request Example

Pass plan=mr to query only intelligent routing services. If this parameter is omitted, a mixed list of regular deployments and intelligent routing services is returned, and total and pagination count only the matched records:

curl "https://dashscope.aliyuncs.com/api/v1/deployments?page_no=1&page_size=10&plan=mr" \
    --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
    --header 'Content-Type: application/json'

Request Parameters

Parameter	Type	Passing Parameters	Required	Description
page_no	Number	query	No	Page number. Default is 1.
page_size	Number	query	No	Page size. Default is 10. Range is 1-100.
plan	String	query	No	Pass `mr` to query only intelligent routing services. If omitted, a mixed list is returned.

Response Example and Parameters

The fields of each element in the deployments array are the same as the response parameters of creating an intelligent routing service.

{
    "request_id": "<request-id>",
    "output": {
        "page_no": 1,
        "page_size": 10,
        "total": 1,
        "deployments": [
            {
                "name": "my-router",
                "deployed_model": "auto-model-Ab12Cd34",
                "model_name": "auto-model",
                "status": "RUNNING",
                "workspace_id": "llm-8v53e*******",
                "charge_type": "post_paid",
                "creator": "16542902******",
                "modifier": "16542902******",
                "gmt_create": "2026-01-15T10:00:00",
                "gmt_modified": "2026-01-15T10:30:00",
                "plan": "mr",
                "routing_config": {
                    "route_model_version": "model-router-20260908",
                    "strategy": "EFFECT_FIRST",
                    "candidate_model_ids": ["qwen3.8-flash", "qwen3.7-plus"]
                }
            }
        ]
    }
}

Query Intelligent Routing Service Details

GET https://dashscope.aliyuncs.com/api/v1/deployments/{deployed_model}

Request Example

curl "https://dashscope.aliyuncs.com/api/v1/deployments/auto-model-Ab12Cd34" \
    --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
    --header 'Content-Type: application/json'

Request Parameters

Parameter	Type	Passing Parameters	Required	Description
deployed_model	String	path	Yes	Deployment instance ID, which can be obtained by creating an intelligent routing service or listing intelligent routing services.

Response Example and Parameters

The response parameters are the same as those of creating an intelligent routing service. Additionally, offline_model_ids (the set of offline model IDs of the current routing version, which is returned only by the detail API) is returned in routing_config:

{
    "request_id": "<request-id>",
    "output": {
        "name": "my-router",
        "deployed_model": "auto-model-Ab12Cd34",
        "model_name": "auto-model",
        "status": "RUNNING",
        "workspace_id": "llm-8v53e*******",
        "charge_type": "post_paid",
        "creator": "16542902******",
        "modifier": "16542902******",
        "gmt_create": "2026-01-15T10:00:00",
        "gmt_modified": "2026-01-15T10:30:00",
        "plan": "mr",
        "routing_config": {
            "route_model_version": "model-router-20260908",
            "strategy": "EFFECT_FIRST",
            "candidate_model_ids": ["qwen3.8-flash", "qwen3.7-plus"],
            "offline_model_ids": []
        }
    }
}

Edit the Routing Configuration

PUT https://dashscope.aliyuncs.com/api/v1/deployments/{deployed_model}/update

This API can be called only when the service status is RUNNING; other statuses return an OperationDenied error. The three routing_config fields are required, and the update is a full replacement rather than a partial update. When you switch route_model_version, the version and its routing are atomically switched by the server: after a successful save, both detail queries and online inference use the new version; if the save fails, the original configuration remains entirely unchanged.

Request Example

curl -X PUT "https://dashscope.aliyuncs.com/api/v1/deployments/auto-model-Ab12Cd34/update" \
    --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
    --header 'Content-Type: application/json' \
    --data '{
    "routing_config": {
        "route_model_version": "model-router-20260908",
        "strategy": "COST_FIRST",
        "candidate_model_ids": ["qwen3.8-flash", "qwen3.7-plus"]
    }
}'

Request Parameters

Parameter	Type	Passing Parameters	Required	Description
deployed_model	String	path	Yes	Deployment instance ID.
routing_config	Object	body	Yes	The routing configuration after full replacement. The fields are the same as those for creating an intelligent routing service: `route_model_version`, `strategy`, and `candidate_model_ids`. All three fields are required.

This API only edits the routing configuration and does not modify the service name (intelligent routing does not support renaming at this time), nor does it support modifying other fields at the same time. After a successful update, you can query the details again to confirm the configuration.

Response Example and Parameters

The response is the updated deployment details, and the parameters are the same as those of querying intelligent routing service details.

Delete an Intelligent Routing Service

DELETE https://dashscope.aliyuncs.com/api/v1/deployments/{deployed_model}

An intelligent routing service can be deleted directly when it is in the RUNNING status (the status in the delete response is DELETED). After the deletion, the list and detail queries no longer return the resource, and the deployed_model is not reused. You must create the service again.

Request Example

curl -X DELETE "https://dashscope.aliyuncs.com/api/v1/deployments/auto-model-Ab12Cd34" \
    --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
    --header 'Content-Type: application/json'

Request Parameters

Parameter	Type	Passing Parameters	Required	Description
deployed_model	String	path	Yes	Deployment instance ID.

Response Example and Parameters

The response is the deployment details before the deletion (status is DELETED), and the parameters are the same as those of querying intelligent routing service details.

Error Responses

{
    "request_id": "<request-id>",
    "code": "InvalidParameter",
    "message": "<message>"
}

Response Parameters

Parameter	Type	Description
request_id	String	System-generated ID of this request.
code	String	Error code, which indicates the error type.
message	String	Error details for troubleshooting. Do not rely on the text for business branching.

Common Errors

Error code	Scenario
InvalidParameter	Parameter error, such as a missing required field, an empty candidate list or candidate models that do not belong to the selected version, or an invalid service name.
AccessDenied	No permission or no valid user identity.
NotFound	The specified deployment does not exist.
Conflict	Duplicate service name or concurrent conflict.
QuotaLimit	Quota limit.
OperationDenied	Operation not allowed in the current status, such as editing the routing configuration when the service is not in the RUNNING status.
UnsupportedOperation	Unsupported operation, such as compute-related operations like scaling, start/stop, and rate limit configuration.
InternalError	Internal error.
ResponseTimeout	Response timeout.

​Prerequisites

​API Overview

​Get a List of Model Routing Versions

​Request Example

​Request Parameters

​Response Example and Parameters

​Create an Intelligent Routing Service

​Request Example

​Request Parameters

​Response Example and Parameters

​List Intelligent Routing Services

​Request Example

​Request Parameters

​Response Example and Parameters

​Query Intelligent Routing Service Details

​Request Example

​Request Parameters

​Response Example and Parameters

​Edit the Routing Configuration

​Request Example

​Request Parameters

​Response Example and Parameters

​Delete an Intelligent Routing Service

​Request Example

​Request Parameters

​Response Example and Parameters

​Error Responses

​Response Parameters

​Common Errors

Prerequisites

API Overview

Get a List of Model Routing Versions

Request Example

Request Parameters

Response Example and Parameters

Create an Intelligent Routing Service

Request Example

Request Parameters

Response Example and Parameters

List Intelligent Routing Services

Request Example

Request Parameters

Response Example and Parameters

Query Intelligent Routing Service Details

Request Example

Request Parameters

Response Example and Parameters

Edit the Routing Configuration

Request Example

Request Parameters

Response Example and Parameters

Delete an Intelligent Routing Service

Request Example

Request Parameters

Response Example and Parameters

Error Responses

Response Parameters

Common Errors