Create a model deployment task.
The model deployment API is currently available only in the China (Beijing) region. If you use another region, deploy models in the Model Studio console of that region.
Prerequisites
-
Read Introduction to model deployment and Deploy a model by using the API to understand how model deployment works and the basic workflow on Alibaba Cloud Model Studio.
-
Configure your API key for Model Studio. For details, see Get an API key.
Model deployment
Endpoint
POST https://dashscope.aliyuncs.com/api/v1/deployments
Request examples
Billing by provisioned throughput units (PTU)
After running the deployment command below, billing starts immediately upon successful deployment—even if you have not yet called the model. Confirm the billing rules before deploying.
The PTU billing mode charges based on the duration of provisioned throughput usage. It suits scenarios requiring stable throughput guarantees, high concurrency, low latency, and predictable traffic. In this mode, throughput/concurrency and generation speed are preset by the platform and cannot be adjusted.
curl "https://dashscope.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"name": "my_qwen_flash",
"model_name": "qwen-flash-2025-07-28",
"plan": "ptu",
"ptu_capacity": {
"input_tpm": 10000,
"output_tpm": 1000
}
}'
Billing by model unit usage duration
-
After running the deployment command below, billing starts immediately upon successful deployment—even if you have not yet called the model. Confirm the billing rules before deploying.
-
Model unit pay-as-you-go computing resources are allocated on a first-come, first-served basis. If purchase fails, you receive a full refund.
Select the model unit billing method. This mode charges based on model unit usage duration and suits large-scale inference workloads after model fine-tuning. Resources are dedicated, and performance and cost are flexible. Throughput/concurrency and generation speed are customizable.
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",
"deploy_spec": "MU1",
"enable_thinking": true,
"capacity": 4,
"max_context_length": 10000,
"rpm_limit": 500,
"tpm_limit": 1000
}'
The model unit deployment mode supports additional settings:
|
Configuration item |
Configuration details |
|
Service name |
Custom name for the deployment service. |
|
Select model |
Select the model to deploy, including platform built-in models and fine-tuned models. |
|
Model unit type |
Select the deployment specification. Different specifications correspond to different compute power and performance. |
|
Deployment replica count |
Set the initial number of deployment replicas, which affects the concurrency capacity of the service. |
|
Deployment template |
Select a deployment template (such as "single-node deployment"). Different templates correspond to different resource configuration schemes. Available only under the model unit billing mode. |
|
Configure model inference mode |
For some models deployed in Model Unit mode, you can configure the inference mode, maximum context length, and more.
|
|
Maximum context length |
The Model Unit deployment mode of some models supports this setting. The maximum context length depends on the model type. |
|
Service rate limiting |
The Model Unit deployment mode of some models supports this setting. You can limit the RPM and TPM of model invocations. |
For details on setting these options via API, see Create a model deployment task using the API.
Billing by token usage
Select the token-based billing method. This mode charges based on token usage and suits cost-sensitive scenarios with low requirements for concurrency and latency. It offers the highest price advantage. Throughput/concurrency and generation speed are preset by the platform and cannot be adjusted.
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"
}'
The capacity parameter has no effect but must be included. To scale up or down, go to the Model Studio model deployment console and submit a form request.
Request parameters
|
Parameter |
Type |
Location |
Required |
Description |
|||||||||||
|
model_name |
String |
body |
Yes |
The name of the model to deploy. This corresponds to the model ID in My Models . You can also get this ID from the output of the Create Training Job or Create Import Job operations. |
|||||||||||
|
plan |
String |
body |
Yes |
The deployment plan. The following billing methods are supported:
You can quickly find the supported deployment plans for a fine-tuned model in My Models . Note
Fine-tuned CosyVoice models currently only support |
|||||||||||
|
name |
String |
body |
Yes |
The display name of the model in the console. If you do not specify this parameter, the value of |
|||||||||||
|
capacity |
Integer |
body |
No |
Required only when Note
CosyVoice models currently provide the following two deployment templates with corresponding
|
|||||||||||
|
billing_method |
String |
body |
No |
Required only when |
|||||||||||
|
deploy_spec |
String |
body |
No |
This setting is applicable only when For details about feature support, see Feature support for model unit deployment. |
This parameter is required when Note
You can get this value from the |
||||||||||
|
enable_thinking |
Boolean |
body |
No |
Supported by some models. You can set this to |
|||||||||||
|
max_context_length |
Number |
body |
No |
Supported by some models. Example: |
|||||||||||
|
rpm_limit |
Number |
body |
No |
Supported by some models. Specifies the maximum number of requests per minute (RPM). |
|||||||||||
|
tpm_limit |
Number |
body |
No |
Supported by some models. Specifies the maximum number of tokens per minute (TPM). |
|||||||||||
|
ptu_capacity |
Object |
body |
No |
This setting is applicable only when For details about feature support, see Feature Support for PTU Deployment. If you do not specify this parameter, the system defaults to |
Example: Example: |
||||||||||
|
ptu_capacity.input_tpm |
Number |
body |
No |
Supported by all models. Specifies the maximum number of input tokens per minute (TPM). |
|||||||||||
|
ptu_capacity.output_tpm |
Number |
body |
No |
Supported by all models. Specifies the maximum number of output tokens per minute (TPM). |
|||||||||||
|
ptu_capacity.thinking_output_tpm |
Number |
body |
No |
Supported by some models. Specifies the maximum number of provisioned thinking output tokens per minute (TPM). |
|||||||||||
|
suffix |
String |
body |
No |
After a model is deployed, a new model name is generated. The suffix parameter specifies the suffix for this new name. It must be globally unique and have a maximum length of 8 characters. You can omit the suffix for the first deployment of a model. If you deploy the same model multiple times, you must specify a unique suffix for each deployment. See the deployed_model output parameter for more information. |
|||||||||||
|
aigc_config |
Object |
body |
No |
The prompt configuration for a LoRA-based video generation model. This parameter applies only to Wan video generation models (the wan series). This parameter is not supported by
|
|||||||||||
First frame
Replace <YOUR_MODEL_NAME> with the value of the finetuned_output output parameter from your training job.
curl --location 'https://dashscope.aliyuncs.com/api/v1/deployments' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model_name": "<YOUR_MODEL_NAME>",
"aigc_config": {
"use_input_prompt": false,
"prompt": "Provide a video description based on the image content. The description must include \"Then the s86b5p money rain effect begins, where countless huge US dollar bills (beige with a dark green pattern) pour down like a torrential rain, falling heavily on and surrounding them. The bills continue to fall as the camera slowly zooms in. They stretch their arms upward, neck slightly tilted back, with a surprised expression, completely immersed in this wild money rain.\"\nOutput Template:\nThe video begins with a shot of [subject description]. [Environment description]. Then the s86b5p money rain effect begins...\nExample:\nThe video begins with a shot of a young woman on a beach...",
"lora_prompt_default": "Then the s86b5p money rain effect begins, where countless huge US dollar bills (beige with a dark green pattern) pour down like a torrential rain, falling heavily on and surrounding the main character. The bills continue to fall as the camera slowly zooms in. The main character stretches their arms upward, neck slightly tilted back, with a surprised expression, completely immersed in this wild money rain."
},
"capacity": 1,
"plan": "lora"
}'
First and last frames
curl --location 'https://dashscope.aliyuncs.com/api/v1/deployments' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model_name": "<YOUR_MODEL_NAME>",
"aigc_config": {
"use_input_prompt": false,
"prompt": "Provide a video description based on the image content. The description must include \"Then she begins the s86b5p transformation.\"\nOutput Template:\nThe video begins with a shot of [subject description]. [Environment description]. Then she begins the s86b5p transformation.\nExample:\nThe video begins with a shot of a young woman in an outdoor setting...",
"lora_prompt_default": "Then she begins the s86b5p transformation."
},
"capacity": 1,
"plan": "lora"
}'
Image generation
The wan2.7-image-pro model does not support the aigc_config parameter during deployment.
curl --location 'https://dashscope.aliyuncs.com/api/v1/deployments' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model_name": "<YOUR_MODEL_NAME>",
"capacity": 1,
"plan": "lora"
}'
Deployment troubleshooting and performance tuning
The max-num-seqs parameter is not configurable
For both Billing by provisioned throughput units (PTU) and Billing by model unit, Model Studio presets throughput, concurrency, and generation speed. You cannot directly tune vLLM engine parameters such as max-num-seqs, and this operation does not expose such a parameter. Under Billing by model unit, you can indirectly control throughput by choosing a Model unit type (the deploy_spec request parameter) and adjusting the Deployment replica count (the capacity request parameter).
Deployment templates and resource isolation
Deployment templates currently support single-node deployment only (Single-node deployment - Enhanced general-purpose inference). Multi-GPU instance isolation is not supported. If you need isolated resources, use Billing by model unit, which provides dedicated compute resources.
Handling throttling errors
When concurrent requests exceed the rate limit, the operation returns HTTP 429 with the error code Throttling.RateQuota and the message Requests rate limit exceeded, please try again later. To resolve this issue:
-
Billing by provisioned throughput units (PTU): adjust
input_tpmandoutput_tpminptu_capacity(Input kTPM and Output kTPM in the console), or reduce the request rate. In this mode, the overflow policy can be Auto-overflow (switches to pay-as-you-go) or PTU capacity only, where requests beyond the provisioned capacity return429directly. -
Billing by model unit: adjust
rpm_limitandtpm_limit, or reduce the request rate.
Tuning the maximum context length
Under Billing by model unit, you can set the Maximum context length through the max_context_length request parameter, which accepts values from 1 to 262144. The actual upper limit depends on the deployed model. This parameter caps the context size of a single request, which limits per-request memory usage and reduces the risk of out-of-memory (OOM) errors. When you process large volumes of image tasks, set this parameter based on the image resolution and the number of images per request.
Response example
The command returns the following:
{
"request_id": "f2ae64f7-83cc-410c-bc0b-840443f7eb86",
"output": {
"deployed_model": "emo-35b3f106-sample01",
"gmt_create": "2025-06-17T11:00:38.68",
"gmt_modified": "2025-06-17T11:00:38.68",
"status": "PENDING",
"model_name": "emo",
"base_model": "emo",
"base_capacity": 1,
"capacity": 1,
"ready_capacity": 0,
"workspace_id": "llm-v71tlv3d***",
"charge_type": "post_paid",
"creator": "175805416***",
"modifier": "175805416***"
}
}
Response parameters
|
Parameter |
Type |
Description |
|
request_id |
String |
The ID of the request. |
|
output |
Object |
Details of the deployment task. |
|
deployed_model |
String |
A unique identifier for the deployed model. This ID is used for API operations, such as querying deployment details, modifying deployment rate limiting, deployment scaling, and deleting deployments, and is also passed as an SDK parameter when you invoke the model. |
|
gmt_create |
String |
The creation time of the deployment task. |
|
gmt_modified |
String |
The last modification time of the deployment task. |
|
status |
String |
The status of the deployment task.
|
|
model_name |
String |
The name of the model used in the deployment task. |
|
base_model |
String |
The ID of the base model used in the deployment task. |
|
base_capacity |
Number |
The minimum number of resource units required to run the base model. |
|
capacity |
Number |
The number of resource units used by the deployment task. |
|
ready_capacity |
Number |
The number of resource units that are ready to process requests immediately. Resource initialization speed or hardware status can limit this value. |
|
workspace_id |
String |
The ID of the deployment task's workspace. |
|
charge_type |
String |
The billing method for the deployment task.
|
|
creator |
String |
The UID of the user who created the deployment task. |
|
modifier |
String |
The UID of the user who last modified the deployment task. |
|
plan |
String |
The billing model for the deployment task. This parameter is not returned for some billing models. |
|
Returned only for Model Unit deployments. |
||
|
model_unit_spec |
String |
The model unit specification. |
|
enable_thinking |
Boolean |
Specifies if Thinking mode is enabled. This feature is only available for certain models. |
|
max_context_length |
Number |
The maximum context length. |
|
rpm_limit |
Number |
The maximum number of requests per minute (RPM). |
|
tpm_limit |
Number |
The maximum number of tokens per minute (TPM). |
|
Returned only for provisioned throughput (PTU) deployments |
||
|
ptu_capacity |
Object |
This parameter takes effect only when Example: |
|
ptu_capacity.input_tpm |
Number |
The maximum number of input tokens per minute (TPM) for the deployed model. This feature is supported by all models. |
|
ptu_capacity.output_tpm |
Number |
The maximum number of output tokens per minute (TPM) for the deployed model. This feature is supported by all models. |
|
ptu_capacity.thinking_output_tpm |
Number |
The maximum number of thinking output tokens per minute (TPM) for the deployed model. This feature is only available for certain models. |
Error response
Response example
{
"request_id": "ca218d57-b91b-46b2-bd35-c41c6287bcf4",
"message": "Model: qwen-plus-20230703-cx7f not found!",
"code": "NotFound"
}
Response parameters
|
Parameter |
Type |
Description |
|
request_id |
String |
The unique ID of the request. |
|
code |
String |
The error code. |
|
message |
String |
The error message. |
The following errors can occur when a request fails:
|
Error code |
Error message |
Reason |
|
NotFound |
Model: xxx not found! |
|
|
Conflict |
Deployed model xxx already exists, please specify a suffix. |
You are creating a deployment task with a suffix that is already in use. |
|
InvalidParameter |
Invalid capacity (xx), capacity must be larger than or equal to 0 and multiples of 1 and less than 1000! |
You are creating or updating a deployment task with an invalid number of capacity units. |
Next steps
When the deployment status is RUNNING, you can call the model for inference. To call a video generation model, see Call the model to generate a video or Call the model to generate an image.