Upload local files to get temporary URLs

Python

• Python 3.9 or later is recommended.
• Install the required dependencies.

pip install -U requests

• api_key: The Alibaba Cloud Model Studio API key.
• model_name: The model that the file will be used with, such as qwen3-vl-plus.
• file_path: The path of the local file to upload (image, video, etc.).

import os
import requests
from pathlib import Path
from datetime import datetime, timedelta

def get_upload_policy(api_key, model_name):
    """Get the file upload credential"""
    # The API keys for the Beijing and Singapore regions are different. Use the key for the corresponding region.
    # The following is the Beijing region URL. For the Singapore region, replace the URL with: https://dashscope-intl.aliyuncs.com/api/v1/uploads
    url = "https://dashscope.aliyuncs.com/api/v1/uploads"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    params = {
        "action": "getPolicy",
        "model": model_name
    }

    response = requests.get(url, headers=headers, params=params)
    if response.status_code != 200:
        raise Exception(f"Failed to get upload policy: {response.text}")

    return response.json()['data']

def upload_file_to_oss(policy_data, file_path):
    """Upload the file to temporary storage OSS"""
    file_name = Path(file_path).name
    key = f"{policy_data['upload_dir']}/{file_name}"

    with open(file_path, 'rb') as file:
        files = {
            'OSSAccessKeyId': (None, policy_data['oss_access_key_id']),
            'Signature': (None, policy_data['signature']),
            'policy': (None, policy_data['policy']),
            'x-oss-object-acl': (None, policy_data['x_oss_object_acl']),
            'x-oss-forbid-overwrite': (None, policy_data['x_oss_forbid_overwrite']),
            'key': (None, key),
            'success_action_status': (None, '200'),
            'file': (file_name, file)
        }

        response = requests.post(policy_data['upload_host'], files=files)
        if response.status_code != 200:
            raise Exception(f"Failed to upload file: {response.text}")

    return f"oss://{key}"

def upload_file_and_get_url(api_key, model_name, file_path):
    """Upload the file and get the URL"""
    # 1. Get the upload credential. The credential API is rate-limited, and exceeding the rate limit causes requests to fail
    policy_data = get_upload_policy(api_key, model_name)
    # 2. Upload the file to OSS
    oss_url = upload_file_to_oss(policy_data, file_path)

    return oss_url

# Usage example
if __name__ == "__main__":
    # Get the API key from the environment variable, or set it in the code: api_key = "your_api_key"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    if not api_key:
        raise Exception("Please set the DASHSCOPE_API_KEY environment variable")

    # Set the model name
    model_name="qwen3-vl-plus"

    # Path of the file to upload
    file_path = "/tmp/cat.png"  # Replace with the actual file path

    try:
        public_url = upload_file_and_get_url(api_key, model_name, file_path)
        expire_time = datetime.now() + timedelta(hours=48)
        print(f"File uploaded successfully. The URL is valid for 48 hours. Expiration time: {expire_time.strftime('%Y-%m-%d %H:%M:%S')}")
        print(f"Temporary URL: {public_url}")
        print("Note: When you use a temporary URL in the oss:// format, you must explicitly add the parameter X-DashScope-OssResourceResolve: enable to the HTTP request header (Header). For more information, see https://help.aliyun.com/en/model-studio/get-temporary-file-url#http")

    except Exception as e:
        print(f"Error: {str(e)}")

File uploaded successfully. The URL is valid for 48 hours. Expiration time: 2024-07-18 17:36:15
Temporary URL: oss://dashscope-instant/xxx/2024-07-18/xxx/cat.png
Note: When you use a temporary URL in the oss:// format, you must explicitly add the parameter X-DashScope-OssResourceResolve: enable to the HTTP request header (Header). For more information, see https://help.aliyun.com/en/model-studio/get-temporary-file-url#http

Java

• JDK 1.8 or later is recommended.
• Add the following dependencies to the pom.xml file of your Maven project.

 <dependencies>
        <dependency>
            <groupId>org.json</groupId>
            <artifactId>json</artifactId>
            <version>20230618</version>
        </dependency>
        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpclient</artifactId>
            <version>4.5.13</version>
        </dependency>
        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpmime</artifactId>
            <version>4.5.13</version>
        </dependency>
</dependencies>

• apiKey: The Alibaba Cloud Model Studio API key.
• modelName: The model that the file will be used with, such as qwen3-vl-plus.
• filePath: The path of the local file to upload (image, video, etc.).

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.entity.ContentType;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.HttpStatus;
import org.apache.http.util.EntityUtils;
import org.json.JSONObject;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class PublicUrlHandler {

    // The API keys for the Beijing and Singapore regions are different. Use the key for the corresponding region.
    // The following is the Beijing region URL. For the Singapore region, replace the URL with: https://dashscope-intl.aliyuncs.com/api/v1/uploads
    private static final String API_URL = "https://dashscope.aliyuncs.com/api/v1/uploads";

    public static JSONObject getUploadPolicy(String apiKey, String modelName) throws IOException {
        try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
            HttpGet httpGet = new HttpGet(API_URL);
            httpGet.addHeader("Authorization", "Bearer " + apiKey);
            httpGet.addHeader("Content-Type", "application/json");

            String query = String.format("action=getPolicy&model=%s", modelName);
            httpGet.setURI(httpGet.getURI().resolve(httpGet.getURI() + "?" + query));

            try (CloseableHttpResponse response = httpClient.execute(httpGet)) {
                if (response.getStatusLine().getStatusCode() != 200) {
                    throw new IOException("Failed to get upload policy: " +
                            EntityUtils.toString(response.getEntity()));
                }
                String responseBody = EntityUtils.toString(response.getEntity());
                return new JSONObject(responseBody).getJSONObject("data");
            }
        }
    }

    public static String uploadFileToOSS(JSONObject policyData, String filePath) throws IOException {
        Path path = Paths.get(filePath);
        String fileName = path.getFileName().toString();
        String key = policyData.getString("upload_dir") + "/" + fileName;

        HttpPost httpPost = new HttpPost(policyData.getString("upload_host"));
        MultipartEntityBuilder builder = MultipartEntityBuilder.create();

        builder.addTextBody("OSSAccessKeyId", policyData.getString("oss_access_key_id"));
        builder.addTextBody("Signature", policyData.getString("signature"));
        builder.addTextBody("policy", policyData.getString("policy"));
        builder.addTextBody("x-oss-object-acl", policyData.getString("x_oss_object_acl"));
        builder.addTextBody("x-oss-forbid-overwrite", policyData.getString("x_oss_forbid_overwrite"));
        builder.addTextBody("key", key);
        builder.addTextBody("success_action_status", "200");
        byte[] fileContent = Files.readAllBytes(path);
        builder.addBinaryBody("file", fileContent, ContentType.DEFAULT_BINARY, fileName);

        httpPost.setEntity(builder.build());

        try (CloseableHttpClient httpClient = HttpClients.createDefault();
             CloseableHttpResponse response = httpClient.execute(httpPost)) {
            if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
                throw new IOException("Failed to upload file: " +
                        EntityUtils.toString(response.getEntity()));
            }
            return "oss://" + key;
        }
    }

    public static String uploadFileAndGetUrl(String apiKey, String modelName, String filePath) throws IOException {
        JSONObject policyData = getUploadPolicy(apiKey, modelName);
        return uploadFileToOSS(policyData, filePath);
    }

    public static void main(String[] args) {
        // Get the API key from the environment variable
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            System.err.println("Please set the DASHSCOPE_API_KEY environment variable");
            System.exit(1);
        }
        // Model name
        String modelName = "qwen3-vl-plus";
        // Replace with the actual file path
        String filePath = "src/main/resources/tmp/cat.png";

        try {
            // Check whether the file exists
            File file = new File(filePath);
            if (!file.exists()) {
                System.err.println("File does not exist: " + filePath);
                System.exit(1);
            }

            String publicUrl = uploadFileAndGetUrl(apiKey, modelName, filePath);
            LocalDateTime expireTime = LocalDateTime.now().plusHours(48);
            DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

            System.out.println("File uploaded successfully. The URL is valid for 48 hours. Expiration time: " + expireTime.format(formatter));
            System.out.println("Temporary URL: " + publicUrl);
            System.out.println("Note: When you use a temporary URL in the oss:// format, you must explicitly add the parameter X-DashScope-OssResourceResolve: enable to the HTTP request header (Header). For more information, see https://help.aliyun.com/en/model-studio/get-temporary-file-url#http");
        } catch (IOException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

File uploaded successfully. The URL is valid for 48 hours. Expiration time: 2024-07-18 17:36:15
Temporary URL: oss://dashscope-instant/xxx/2024-07-18/xxx/cat.png
Note: When you use a temporary URL in the oss:// format, you must explicitly add the parameter X-DashScope-OssResourceResolve: enable to the HTTP request header (Header). For more information, see https://help.aliyun.com/en/model-studio/get-temporary-file-url#http

DashScope SDK (Python)

Install the DashScope Python SDK with a version number >= 2.0.1.

The DashScope SDK provides a client.files resource that encapsulates file upload, query, and delete operations, so you do not need to manually construct upload credentials and OSS forms.

import os
import dashscope

# The API keys for the Beijing and Singapore regions are different. Use the key for the corresponding region.
# If the environment variable is not configured, replace the following line with your Alibaba Cloud Model Studio API key: api_key="sk-xxx"
client = dashscope.Client(api_key=os.getenv('DASHSCOPE_API_KEY'))

# Upload a file (purpose=fine_tune for fine-tuning training files, purpose=inference for inference temporary files)
result = client.files.upload(
    file_path='train_data.jsonl',
    purpose='fine_tune',
)

print(result)

{"request_id": "xxx", "code": "", "message": "", "output": {"uploaded_files": [{"name": "train_data.jsonl", "file_id": "file-xxx"}], "failed_uploads": []}}

dashscope CLI

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, and cn-beijing with the corresponding region (Singapore: ap-southeast-1, US East: us-east-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
# List uploaded files
dashscope files list

# Upload a local file
dashscope oss upload -f train_data.jsonl -m qwen-plus

For the complete region table, see Base URL overview.

Method 1: Use environment variables (recommended)

This method is more secure and prevents the API key from being exposed in plain text in command history or scripts.

Prerequisite: Make sure you have configured the API key as an environment variable.

Run the upload command:

# Uses the Beijing region by default. To use the Singapore region, run the following command first: export DASHSCOPE_HTTP_BASE_URL="https://dashscope-intl.aliyuncs.com/api/v1" (the Singapore region uses a different API key)
dashscope oss.upload --model qwen3-vl-plus --file cat.png

Sample output:

Start oss.upload: model=qwen3-vl-plus, file=cat.png, api_key=None
Uploaded oss url: oss://dashscope-instant/xxxx/2025-08-01/xxxx/cat.png

Method 2: Specify the API key as a command-line parameter (temporary use)

Run the upload command:

# Uses the Beijing region by default. To use the Singapore region, run the following command first: export DASHSCOPE_HTTP_BASE_URL="https://dashscope-intl.aliyuncs.com/api/v1" (the Singapore region uses a different API key)
dashscope oss.upload --model qwen3-vl-plus --file cat.png --api_key sk-xxxxxxx

Sample output:

Start oss.upload: model=qwen3-vl-plus, file=cat.png, api_key=sk-xxxxxxx
Uploaded oss url: oss://dashscope-instant/xxx/2025-08-01/xxx/cat.png

Sample request

import os
import dashscope

# The API keys for the Beijing and Singapore regions are different. Use the key for the corresponding region.
# If the environment variable is not configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
client = dashscope.Client(api_key=os.getenv('DASHSCOPE_API_KEY'))

messages = [
    {
        "role": "system",
        "content": [{"text": "You are a helpful assistant."}]
    },
    {
        "role": "user",
        "content": [
            {"image": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"},
            {"text": "What is this?"}]
    }]

response = client.multimodal.chat.create(
    model='qwen3-vl-plus',
    messages=messages
)

print(response.output_text)

Sample response

{
    "request_id": "ccd9dcfb-98f0-92bc-xxxxxx",
    "choices": [
        {
            "index": 0,
            "finish_reason": "stop",
            "message": {
                "role": "assistant",
                "content": "This is a photo of a cat running on the grass. The cat's fur is mainly white with light brown spots, and its eyes are blue, making it look very cute. The background is a blurry green meadow with some trees, and the sunlight adds a warm feeling to the whole picture. The cat's posture shows that it is moving quickly, possibly chasing something or just enjoying the outdoors. Overall, this is a vibrant and lively picture."
            }
        }
    ],
    "usage": {
        "input_tokens": 1112,
        "output_tokens": 91,
        "total_tokens": 1203,
        "input_tokens_details": {
            "text_tokens": 21,
            "image_tokens": 1091
        },
        "output_tokens_details": {
            "text_tokens": 91
        }
    }
}

Sample request

import com.alibaba.dashscope.aigc.multimodalconversation.*;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

import java.util.Arrays;

public class MultiModalConversationUsage {

    private static final String modelName = "qwen3-vl-plus";

    // The API keys for the Beijing and Singapore regions are different. Use the key for the corresponding region.
    // If the environment variable is not configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void simpleMultiModalConversationCall() throws ApiException, NoApiKeyException, UploadFileException {
        // The following is the Beijing region URL. For the Singapore region, replace the URL with: https://dashscope-intl.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessageItemText systemText = new MultiModalMessageItemText("You are a helpful assistant.");
        MultiModalConversationMessage systemMessage = MultiModalConversationMessage.builder()
                .role(Role.SYSTEM.getValue()).content(Arrays.asList(systemText)).build();
        MultiModalMessageItemImage userImage = new MultiModalMessageItemImage(
                "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png");
        MultiModalMessageItemText userText = new MultiModalMessageItemText("What is this?");
        MultiModalConversationMessage userMessage =
                MultiModalConversationMessage.builder().role(Role.USER.getValue())
                        .content(Arrays.asList(userImage, userText)).build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                .model(MultiModalConversationUsage.modelName)
                .apiKey(apiKey)
                .message(systemMessage)
                .vlHighResolutionImages(true)
                .vlEnableImageHwOutput(true)
//                .incrementalOutput(true)
                .message(userMessage).build();
        MultiModalConversationResult result = conv.call(param);
        System.out.print(JsonUtils.toJson(result));

    }

    public static void main(String[] args) {
        try {
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException /*| IOException*/ e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }

}

Sample response

{
    "requestId": "b6d60f91-4a7f-9257-xxxxxx",
    "usage": {
        "input_tokens": 1112,
        "output_tokens": 91,
        "total_tokens": 1203,
        "image_tokens": 1091,
        "input_tokens_details": {
            "text_tokens": 21,
            "image_tokens": 1091
        },
        "output_tokens_details": {
            "text_tokens": 91
        }
    },
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "text": "This is a photo of a cat running on the grass. The cat's fur is mainly white with light brown spots, and its eyes are blue, making it look very cute. The background is a blurry green meadow with some trees, and the sunlight adds a warm feeling to the whole picture. The cat's posture shows that it is moving quickly, possibly chasing something or just enjoying the outdoors. Overall, this is a vibrant and lively picture."
                        },
                        {
                            "image_hw": [
                                [
                                    "924",
                                    "924"
                                ]
                            ]
                        }
                    ]
                }
            }
        ]
    }
}