Text Generation - Create Deployment

Updated at:

Deploy a trained text model as an online API service.

Prerequisites

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.com for the China (Beijing) region and dashscope-intl.aliyuncs.com for 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_KEY with %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: application/json.

Authorization

String

Yes

API key authentication, in the format Bearer sk-xxxx.

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.com domain 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. Query sku_code, template_code, and the capacity range through the deployable models list API with plan=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: dtu (DTU dedicated computing power), mu (Model Unit), cu (Computing Power Unit), lora (LoRA shared deployment, billed by Token usage).

display_name

String

Yes

Service display name, up to 50 characters (other deployment plans use name).

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 plan=dtu.

template_code

String

Yes

Deployment template that matches the model and SKU. Obtained from the same query as sku_code.

charge_type

String

Yes

Billing method. For DTU, always set to pre_paid (subscription).

dtu_capacity

Object

Yes

DTU capacity to purchase. You must provide both input_tpm and output_tpm. For the purchase range and step rules, see Model Deployment API Reference.

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: pricing_cycle (always set to Month), duration (subscription duration in months), auto_renewal (enable auto-renewal), auto_renewal_duration (auto-renewal duration in months, required when auto-renewal is enabled).

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: dtu (DTU dedicated computing power), mu (Model Unit), cu (Computing Power Unit), lora (LoRA shared deployment, billed by Token usage).

name

String

No

Display name of the model in the console. If not provided, the value of model_name will be used as the deployment name.

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 template_id returned by the deployable models list API. Required when plan is mu. We recommend using this parameter to specify the model unit spec (for example, MU1).

deploy_spec (deprecated)

String

No

Model unit spec. Deprecated. Use template_id instead.

capacity

Integer

Conditionally required

Number of resource units for the deployment. Must be an integer multiple of base_capacity. Different specs have different constraints: for example, MU2 must be a multiple of 8, while MU5 can be 1.

charge_type

String

No

Billing method: post_paid (pay-as-you-go, default) or pre_paid (subscription).

enable_thinking

Boolean

No

Whether to enable thinking mode. Supported by some models. Can be set to true or false.

max_context_length

Number

No

Maximum context length. Supported by some models. Example: "max_context_length": 131072.

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: dtu (DTU dedicated computing power), mu (Model Unit), cu (Computing Power Unit), lora (LoRA shared deployment, billed by Token usage).

name

String

No

Display name of the model in the console. If not provided, the value of model_name will be used as the deployment name.

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_tpm and output_tpm in ptu_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 return 429).
  • By Model Unit: Adjust rpm_limit and tpm_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: PENDING (creating), DEPLOYING (deploying), WAIT_PRE_PAID_BILLING_TO_DEPLOYING (creation waiting for the pre-paid order to be processed, DTU), WAIT_PRE_PAID_BILLING_TO_SCALING (scaling waiting for the pre-paid order to be processed, DTU), UPDATING (updating), RUNNING (running and ready to process requests), SCALING (scaling), STOPPED (stopped, no longer billed), DELETING (deleting), FAILED (creation or update failed).

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: post_paid (pay-as-you-go) or pre_paid (subscription).

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 input_tpm (maximum input tokens per minute) and output_tpm (maximum output tokens per minute); some models also support thinking_output_tpm (maximum output tokens for preset thinking).

Only returned by the DTU (dtu) deployment method

output.dtu_capacity

Object

The purchased input/output TPM capacity, including input_tpm and output_tpm.

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.