Model import

Overview

Import fine-tuned model files from OSS into Model Studio, then deploy them as callable services through the create deployment API. Two model types are supported: full-parameter fine-tuning (full) and LoRA fine-tuning (lora).

Workflow: create an import task → poll task status → deploy the model after import succeeds. Use the list and delete APIs to manage completed tasks.

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 Model Import.

Common request headers

All operations require these HTTP headers:

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 represents an import task. Create one with the Create an import task API, retrieve it with Query import task details or List import tasks, and deploy the model with the Create a deployment API.

Object fields

Parameter	Type	Description
request_id	String	The request ID.
output.job_id	String	Import task ID. Use it to query or delete the task.
output.model_name	String	System-generated model identifier: base model name + timestamp suffix.
output.display_name	String	The display name of the imported model.
output.source	String	Import source. Returns uppercase `OSS`.
output.weight_type	String	The fine-tuning type.
output.storage_info	Object	Import source storage info, including `bucket_name` and `object_key`.
output.status	String	Task status. Valid values: 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

Import task statuses:

Status	Description
PENDING	Submitted, waiting to be processed.
RUNNING	Validating and importing model files.
SUCCESSED	Import succeeded. Deploy the model through the Create a deployment API.
FAILED	Import failed. Query task details for the `error_code`.

Create an import task

Submit a model import task. The system validates model files for structure and security before import.

Endpoint

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

Request example

curl -X POST "https://dashscope.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	Base model name. Corresponds to Base Model in the console. For the supported models, see Model Import. Example: `qwen3-32b`.
display_name	String	body	No	Display name of the imported model. Corresponds to Model Name in the console. Maximum 50 characters. Defaults to the base model name.
source	String	body	Yes	Import source. Corresponds to Import Source in the console. Only `oss` is supported. The response returns uppercase `OSS`.
weight_type	String	body	Yes	Fine-tuning type. `full`: full-parameter fine-tuned model. `lora`: LoRA fine-tuned model.
storage_info	Object	body	Yes	Import source storage information.
storage_info.bucket_name	String	body	Yes	OSS bucket name. Corresponds to Bucket in the console.
storage_info.object_key	String	body	Yes	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	Import task ID. Use with the Query import task details, List import tasks, and Delete an import task APIs.
output.model_name	String	System-generated model identifier: base model name + timestamp suffix.
output.display_name	String	The display name of the imported model.
output.source	String	Import source. Returns uppercase `OSS`.
output.weight_type	String	The fine-tuning type.
output.storage_info	Object	Import source storage info, including `bucket_name` and `object_key`.
output.status	String	Task status. Valid values: 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 status and details of an import task.

Endpoint

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

Request example

curl "https://dashscope.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	Import task ID. Obtain from 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

Same response parameters as Create an import task, except weight_type is omitted. Failed tasks include an additional error_code field.

List import tasks

List import tasks in the current workspace with pagination.

Endpoint

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

Request example

curl "https://dashscope.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.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	Page number. Default: 1.
page_size	Integer	query	No	Entries per page. Default: 10. Maximum: 100.
status	String	query	No	Filter by task status. Valid values: Task status.
model_name	String	query	No	Filter by model name (exact match on the system-generated name).

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	Total number of matching tasks.
output.page_no	Integer	The current page number.
output.page_size	Integer	The number of entries per page.
output.list	Array	List of import tasks. Each element has the same fields as the Create an import task response, except `weight_type` is omitted. Failed tasks include an additional `error_code` field.

Delete an import task

Delete an import task and its associated model files. Only SUCCESSED or FAILED tasks can be deleted. Returns the deleted task details.

Endpoint

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

Request example

curl -X DELETE "https://dashscope.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	Import task ID. Obtain from 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	Deleted task details. Same fields as the Create an import task response, except `weight_type` is omitted.

Error responses

Error response 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: missing required field, incorrect format, or invalid value.
NotFound	Resource not found: invalid job_id, insufficient access, or unsupported base model.
OperationDenied	Operation denied. Example: deleting a RUNNING task.
InvalidApiKey	Invalid or missing API key.
InternalError	Internal system error. Try again later.