Text Generation - Create Deployment
Deploy a trained text model as an online API service.
Prerequisites
- Applicable regions: The regions where the Model Deployment API is available vary by deployment method—Model Unit (MU) and Dedicated Throughput (DTU) support China (Beijing). If the corresponding deployment method is not available in your region, complete model deployment operations in the Bailian console of that region.
- Enable account permissions: If you use an Alibaba Cloud sub-account (RAM user), you must grant the sub-account permissions for model invocation, training, and deployment.
- Configure environment variables: You have successfully obtained an API Key and configured it as an environment variable.
- Read the deployment documentation: We recommend that you first read Dedicated Deployment Overview and Create a Model Deployment Task via API to understand how to use Model Deployment and its basic steps.
Create a deployment
China (Beijing)
POST https://dashscope.aliyuncs.com/api/v1/deployments
Singapore
POST https://dashscope-intl.aliyuncs.com/api/v1/deployments
The request domain varies by region: use
dashscope.aliyuncs.comfor the China (Beijing) region anddashscope-intl.aliyuncs.comfor the Singapore region. The workspace-specific domain ({WorkspaceId}.{region}.maas.aliyuncs.com) is available in all regions. For the complete regional domain information, see Regional access information.
For Windows CMD, replace
$DASHSCOPE_API_KEYwith%DASHSCOPE_API_KEY%. For PowerShell, replace it with$env:DASHSCOPE_API_KEY
Request parameters
Headers
Parameter | Type | Required | Description |
|---|---|---|---|
Content-Type | String | Yes | Fixed value: |
Authorization | String | Yes | API key authentication, in the format |
Request Body
Request body parameters vary by deployment plan (plan). The complete request body parameters and deployment examples for each billing mode are as follows:
DTU dedicated compute billing
Dedicated Throughput (DTU) is pre-paid (monthly) billing with capacity purchased as input/output TPM and dedicated GPU resources. DTU is the successor to model unit (MU) deployment and is recommended for new dedicated deployments. Before use, enable the DTU feature in the console and apply for a resource quota. For more information, see Dedicated Throughput (DTU).
API requests for DTU deployments must use the workspace-scoped
maas.aliyuncs.comdomain of the region and workspace where the deployment resides (for example,ws-vxxx.cn-beijing.maas.aliyuncs.com) together with the API key of that workspace. Querysku_code,template_code, and the capacity range through the deployable models list API withplan=dtu. For the complete parameters and APIs such as scaling, rate limit modification, and model updates, see Model Deployment API Reference.
Parameter | Type | Required | Description |
|---|---|---|---|
model_name | String | Yes | Name of the model to deploy, corresponding to the Model ID in My Models. You can also obtain it from the output of the Create a tuning job API. |
plan | String | Yes | Deployment plan, which determines the billing method: |
display_name | String | Yes | Service display name, up to 50 characters (other deployment plans use |
suffix | String | No | Suffix of the deployment identifier, up to 24 characters. The generated full deployment identifier must not exceed 100 characters. Omitted means auto-generated. |
sku_code | String | Yes | Pre-paid SKU available for the current model. Query it through the deployable models list API with |
template_code | String | Yes | Deployment template that matches the model and SKU. Obtained from the same query as |
charge_type | String | Yes | Billing method. For DTU, always set to |
dtu_capacity | Object | Yes | DTU capacity to purchase. You must provide both |
dtu_capacity.input_tpm | Integer | Yes | Purchased input TPM (tokens/min). Non-negative integer, maximum 2147483647, and must be an integer multiple of the queried step. |
dtu_capacity.output_tpm | Integer | Yes | Purchased output TPM (tokens/min). Non-negative integer, maximum 2147483647, and must use the same multiple as the input TPM. |
pre_paid_info | Object | Yes | Pre-paid purchase and auto-renewal settings. Fields: |
curl "https://ws-vxxx.cn-beijing.maas.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model_name": "your-supported-model",
"display_name": "业务模型服务",
"suffix": "production",
"plan": "dtu",
"sku_code": "your-prepaid-sku",
"template_code": "your-template",
"charge_type": "pre_paid",
"pre_paid_info": {
"pricing_cycle": "Month",
"duration": 1,
"auto_renewal": false
},
"dtu_capacity": {"input_tpm": 10000, "output_tpm": 10000}
}'
Model unit billing
Billing is based on the usage duration of model units. Suitable for large-scale inference after model fine-tuning, with dedicated resources and flexible performance and cost control.
After executing the deployment command below, billing will start once the deployment is successful, even if you have not yet invoked the model. Please confirm the billing rules before executing the deployment command.
Parameter | Type | Required | Description |
|---|---|---|---|
model_name | String | Yes | Name of the model to deploy, corresponding to the Model ID in My Models. You can also obtain it from the output of the Create a tuning job API. |
plan | String | Yes | Deployment plan, which determines the billing method: |
name | String | No | Display name of the model in the console. If not provided, the value of |
suffix | String | No | After model deployment, a new model name will be generated. The suffix specifies the suffix of the new model name, with a maximum length of 8 characters, and must be globally unique. It can be omitted for the first deployment of a model but must be set for subsequent deployments of the same model. |
template_id | String | Conditionally required | Deployment template ID, corresponding to the |
deploy_spec (deprecated) | String | No | Model unit spec. Deprecated. Use |
capacity | Integer | Conditionally required | Number of resource units for the deployment. Must be an integer multiple of |
charge_type | String | No | Billing method: |
enable_thinking | Boolean | No | Whether to enable thinking mode. Supported by some models. Can be set to |
max_context_length | Number | No | Maximum context length. Supported by some models. Example: |
rpm_limit | Number | No | Requests per minute rate limit. Supported by some models. |
tpm_limit | Number | No | Tokens per minute rate limit. Supported by some models. |
curl "https://dashscope.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"name": "my_qwen_plus",
"model_name": "qwen-plus-2025-12-01",
"plan": "mu",
"template_id": "MU1",
"enable_thinking": true,
"capacity": 4,
"charge_type": "post_paid",
"max_context_length": 10000,
"rpm_limit": 500,
"tpm_limit": 1000
}'
Token-based billing
Billing is based on token usage. Suitable for cost-effective scenarios with lower concurrency and latency requirements. This mode offers the best pricing, with throughput/concurrency and generation speed preset by the platform and not user-adjustable.
Parameter | Type | Required | Description |
|---|---|---|---|
model_name | String | Yes | Name of the model to deploy, corresponding to the Model ID in My Models. You can also obtain it from the output of the Create a tuning job API. |
plan | String | Yes | Deployment plan, which determines the billing method: |
name | String | No | Display name of the model in the console. If not provided, the value of |
suffix | String | No | After model deployment, a new model name will be generated. The suffix specifies the suffix of the new model name, with a maximum length of 8 characters, and must be globally unique. |
capacity | Integer | Conditionally required | When billed by Token usage, this parameter setting has no effect but is required; always set it to 1. |
curl "https://dashscope.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model_name": "qwen3-8b-ft-202511132025-0260",
"plan": "lora",
"capacity": 1,
"name": "qwen3-8b-ft"
}'
Deployment troubleshooting and performance tuning
max-num-seqs parameter is not configurable
Under the two billing methods of Bailian Model Deployment—Throughput Reservation (a separate product; see its API documentation) and By Model Unit—throughput, concurrency, and generation speed are all preset by the platform. Directly adjusting inference engine parameters inside vLLM such as max-num-seqs is not supported, and this parameter does not exist in the request parameters of this API.
Under the model unit billing plan, you can indirectly control throughput by selecting the model unit type (corresponding to the request parameter template_id) and adjusting the number of deployment replicas (corresponding to the request parameter capacity).
Deployment template and resource isolation
Currently, the deployment template only supports single-machine deployment (Single-machine deployment - Enhanced general inference) and does not support multi-GPU instance isolation. For resource isolation, use the model unit billing plan, which provides dedicated computing resources for your workload.
Throttling error handling
When concurrent requests exceed the throttling threshold, the API returns HTTP 429 with error code Throttling.RateQuota and error message Requests rate limit exceeded, please try again later. You can handle this as follows:
- Throughput Reservation (a separate product; see its API documentation): Adjust
input_tpmandoutput_tpminptu_capacity(corresponding to Input kTPM and Output kTPM in the console), or reduce the request frequency. Under this method, the overflow policy can be auto overflow (switch to pay-as-you-go) or reserved capacity only (requests exceeding the capacity directly return429). - By Model Unit: Adjust
rpm_limitandtpm_limit, or reduce the request frequency.
Context length tuning
Under the model unit billing plan, you can configure the maximum context length via the request parameter max_context_length, with a value range of 1 to 262144 (the actual upper limit depends on the capabilities of the deployed model). This parameter limits the context size per request, thereby limiting the memory usage per request and reducing the risk of OOM errors.
When processing tasks with a large number of images, set this parameter based on the image dimensions and the number of images per request.
Response parameters
Parameter | Type | Description |
|---|---|---|
request_id | String | Unique identifier of the request. |
output | Object | Task details. |
output.deployed_model | String | Unique identifier of the deployed model. Used to query the deployment status and invoke the model. |
output.name | String | Display name of the deployment. |
output.model_name | String | Model identifier name. |
output.base_model | String | Base model used. |
output.status | String | Deployment status: |
output.workspace_id | String | ID of the workspace to which the API key belongs. See Obtain the workspace ID. |
output.charge_type | String | Billing method: |
output.creator | String | Alibaba Cloud account ID of the creator. |
output.modifier | String | Alibaba Cloud account ID of the user who last modified the deployment. |
output.plan | String | Deployment mode. |
output.gmt_create | String | Time when the deployment task was created. |
output.gmt_modified | String | Time when the deployment task was last updated. |
Returned only for model unit (mu) deployments | ||
output.base_capacity | Number | Minimum number of resource units required to run the base model. |
output.ready_capacity | Number | Number of resource units that are ready and can immediately process requests. |
output.capacity | Number | Number of resource units used by the deployment. |
output.model_unit_spec | String | Model unit spec. |
output.enable_thinking | Boolean | Whether thinking mode is enabled. |
output.max_context_length | Number | Maximum context length limit. |
output.rpm_limit | Number | Requests per Minute. |
output.tpm_limit | Number | Token usage per minute. |
Only returned by the preset throughput (ptu_v2) deployment method | ||
output.ptu_capacity | Object | Preset throughput configuration, including |
Only returned by the DTU (dtu) deployment method | ||
output.dtu_capacity | Object | The purchased input/output TPM capacity, including |
output.pre_paid_info | Object | Upfront and auto-renewal information. |
For the complete DTU response field descriptions, see Model Deployment API Reference | ||
Returned when the call fails | ||
code | String | Error code. Returned when the call fails. |
message | String | Error details description. Returned when the call fails. |
Success response example
Key fields: output.deployed_model (unique identifier of the deployed model) and output.status (deployment status).
{
"request_id": "f2ae64f7-83cc-410c-bc0b-840443f7eb86",
"output": {
"deployed_model": "qwen-plus-2025-12-01-mu-xxxx",
"gmt_create": "2025-06-17T11:00:38.68",
"gmt_modified": "2025-06-17T11:00:38.68",
"status": "PENDING",
"model_name": "qwen-plus-2025-12-01",
"base_model": "qwen-plus",
"model_unit_spec": "MU1",
"enable_thinking": true,
"max_context_length": 10000,
"rpm_limit": 500,
"tpm_limit": 1000,
"base_capacity": 1,
"ready_capacity": 0,
"workspace_id": "llm-v71tlv3d***",
"charge_type": "post_paid",
"creator": "175805416***",
"modifier": "175805416***",
"plan": "mu"
}
}
Error response example
{
"code": "InvalidParameter",
"request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
"message": "The model xxx does not exist or is not deployable"
}
Next steps
Deployment is an asynchronous operation. After calling this API, you can use the Get deployment details API to query the deployment status.