Model import - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

Overview

The model import API allows you to import fine-tuned model files stored in OSS into Model Studio. After import, you can deploy the model as a callable service through the create deployment API. Model import supports two model types: full-parameter fine-tuning (full) and LoRA fine-tuning (lora).

The complete model import workflow is as follows: create an import task → query import task details (poll task status) → create a deployment after the task succeeds → list and delete tasks that are no longer needed.

Prerequisites

You have configured your Model Studio API key. For more information, see Obtain an API key.
You have created an OSS bucket and authorized Model Studio to access OSS. For more information, see the prerequisites in Model Import.
Model files have been uploaded to the OSS bucket and comply with Import Requirements and Limitations.

Common request headers

All API operations require the following fields in the HTTP header:

Header	Description
Authorization	`Bearer ${DASHSCOPE_API_KEY}`. For more information about how to obtain an API key, see Obtain an API key.
Content-Type	`application/json`

Custom model object

A custom model object describes the complete information of an import task. It is created through the Create an import task API and can be retrieved through the Query import task details and List import tasks APIs. After import, you can deploy the model through the Create a deployment API. The following are the fields contained in a custom model object:

Object fields

Parameter	Type	Description
request_id	String	The request ID.
output.job_id	String	The import task ID, used to query the task status or delete the task.
output.model_name	String	The system-generated model identifier, in the format of the base model name followed by a timestamp suffix.
output.display_name	String	The display name of the imported model.
output.source	String	The import source. The return value is uppercase `OSS`.
output.weight_type	String	The fine-tuning type.
output.storage_info	Object	The storage information of the import source, including `bucket_name` and `object_key`.
output.status	String	The task status. For more information, see Task status.
output.gmt_create	String	The task creation time in ISO 8601 format. Example: `2024-01-01T12:00:00.000+00:00`.

Task status

An import task may have the following statuses during its lifecycle:

Status	Description
PENDING	The task has been submitted and is waiting to be processed.
RUNNING	The task is being executed. The system is validating and importing the model files.
SUCCESSED	The task has completed successfully. The model has been imported and can be deployed through the Create a deployment API.
FAILED	The task execution failed. You can query the task details to obtain the `error_code` for the failure reason.

Create an import task

Submit a model import task. The system validates the model files for structure and security to ensure they can be deployed properly.

Endpoint

POST https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import

Request example

curl -X POST "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
        "model_name": "qwen3-32b",
        "display_name": "My LoRA fine-tuned model",
        "source": "oss",
        "weight_type": "lora",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        }
    }'

Request parameters

Parameter	Type	Position	Required	Description
model_name	String	body	Yes	The name of the base model. Corresponds to the Base Model field in the console. For the supported models, see Supported Base Models. Example: `qwen3-32b`.
display_name	String	body	No	The display name of the imported model. Corresponds to the Model Name field in the console. Maximum 50 characters. If not specified, the base model name is used by default.
source	String	body	Yes	The import source. Corresponds to the Import Source field in the console. Currently, only `oss` (import from OSS) is supported. The response returns uppercase `OSS`.
weight_type	String	body	Yes	The fine-tuning type. `full` indicates a full-parameter fine-tuned model. `lora` indicates a LoRA fine-tuned model.
storage_info	Object	body	Yes	The storage information of the import source.
storage_info.bucket_name	String	body	Yes	The OSS bucket name. Corresponds to the Bucket field in the console.
storage_info.object_key	String	body	Yes	The OSS path prefix of the model files. Must end with `/`. Example: `models/qwen3-32b-lora/`.

Response example

{
    "request_id": "6c6b****-3fea-****-bc26-c9e2********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "weight_type": "lora",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "PENDING",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

Response parameters

Parameter	Type	Description
request_id	String	The request ID.
output.job_id	String	The import task ID, which can be used with the Query import task details, List import tasks, and Delete an import task APIs.
output.model_name	String	The system-generated model identifier, in the format of the base model name followed by a timestamp suffix.
output.display_name	String	The display name of the imported model.
output.source	String	The import source. The return value is uppercase `OSS`.
output.weight_type	String	The fine-tuning type.
output.storage_info	Object	The storage information of the import source, including `bucket_name` and `object_key`.
output.status	String	The task status. For more information, see Task status.
output.gmt_create	String	The task creation time in ISO 8601 format. Example: `2024-01-01T12:00:00.000+00:00`.

Query import task details

Query the current status and details of a specified import task.

Endpoint

GET https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/{job_id}

Request example

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/937b****-2a4f-****-8abe-c2fa********" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

Request parameters

Parameter	Type	Position	Required	Description
job_id	String	path	Yes	The import task ID, which can be obtained through the Create an import task or List import tasks API.

Response example

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "RUNNING",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

Response parameters

The response parameters are mostly the same as those of the Create an import task API, except that the weight_type field is not included. When the task fails, the response includes an additional error_code field indicating the failure reason.

List import tasks

Query the list of import tasks in the current workspace with pagination.

Endpoint

GET https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import

Request example

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import?page_no=1&page_size=10" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

Filter by status:

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import?page_no=1&page_size=10&status=SUCCESSED" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

Request parameters

Parameter	Type	Position	Required	Description
page_no	Integer	query	No	The page number. Default value: 1.
page_size	Integer	query	No	The number of entries per page. Default value: 10. Maximum value: 100.
status	String	query	No	Filter by task status. For more information, see Task status.
model_name	String	query	No	Filter by model name. You must pass the system-generated name returned in the response (exact match).

Response example

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "output": {
        "total": 2,
        "page_no": 1,
        "page_size": 10,
        "list": [
            {
                "job_id": "937b****-2a4f-****-8abe-c2fa********",
                "model_name": "qwen3-32b-offline-20240101-abc1",
                "display_name": "My LoRA fine-tuned model",
                "status": "SUCCESSED",
                "source": "OSS",
                "storage_info": {
                    "bucket_name": "my-model-bucket",
                    "object_key": "models/qwen3-32b-lora/"
                },
                "gmt_create": "2024-01-01T12:00:00.000+00:00"
            },
            {
                "job_id": "edb0****-39ac-****-9859-8b1e********",
                "model_name": "qwen3-32b-offline-20240102-xyz4",
                "display_name": "My full-parameter fine-tuned model",
                "status": "FAILED",
                "source": "OSS",
                "storage_info": {
                    "bucket_name": "my-model-bucket",
                    "object_key": "models/qwen3-32b-full/"
                },
                "error_code": "Failed to retrieve files from OSS. Please check the files in OSS.",
                "gmt_create": "2024-01-02T09:00:00.000+00:00"
            }
        ]
    }
}

Response parameters

Parameter	Type	Description
request_id	String	The request ID.
output.total	Integer	The total number of tasks that match the query criteria.
output.page_no	Integer	The current page number.
output.page_size	Integer	The number of entries per page.
output.list	Array	The list of import tasks. Each element has the same fields as the Create an import task response parameters, except that the `weight_type` field is not included. An additional `error_code` field is included when the task fails.

Delete an import task

Delete a specified import task and its associated model files. Only tasks with the status SUCCESSED or FAILED can be deleted. After successful deletion, the details of the deleted task are returned.

Endpoint

DELETE https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/{job_id}

Request example

curl -X DELETE "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/937b****-2a4f-****-8abe-c2fa********" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

Request parameters

Parameter	Type	Position	Required	Description
job_id	String	path	Yes	The import task ID, which can be obtained through the Create an import task or List import tasks API.

Response example

{
    "request_id": "e22b****-b20a-****-bf23-9b53********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "SUCCESSED",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

Response parameters

Parameter	Type	Description
request_id	String	The request ID.
output	Object	The details of the deleted task. The fields are mostly the same as those of the Create an import task response parameters, except that the `weight_type` field is not included.

Error responses

When an error occurs, the API returns an error response in the following format:

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "code": "OperationDenied",
    "message": "The import job is currently running and cannot be deleted."
}

Error codes

Error code	Description
InvalidParameter	Invalid request parameter. For example, a required parameter is missing, the parameter format is incorrect, or the parameter value is invalid.
NotFound	The specified resource does not exist. For example, the job_id does not exist, the user does not have access, or the base model does not support import.
OperationDenied	The operation is denied. For example, attempting to delete a task that is in the RUNNING status.
InvalidApiKey	The API key is invalid or not provided.
InternalError	An internal system error occurred. Please try again later.