Upload Local Files for Multimodal Model Calls via Temporary URLs - Model Studio

Multimodal models such as Qwen-VL require file URLs for image, video, and audio inputs. Model Studio provides free temporary storage if you lack public URLs: upload a file and get an oss:// URL valid for 48 hours.

Important

Temporary URLs are for development and testing only -- not for production, high-concurrency scenarios, or stress tests. For production workloads, use Object Storage Service (OSS) for long-term availability and to avoid rate limits.

Important

This feature is available only in the China (Beijing) region. Use an API key from this region.

How it works

Upload a file and specify the target model. The API returns an oss:// URL.
Pass that URL in your model call. You must complete Step 2 to use the temporary URL -- skipping it causes errors. For HTTP calls, add the header X-DashScope-OssResourceResolve: enable. The DashScope SDK adds this header automatically.

Limitations

Constraint	Detail
File-model binding	Specify the model name at upload. Use the same model in subsequent calls -- files cannot be shared across models. Each model enforces its own file size limit.
File-account binding	API keys for upload and model calls must belong to the same Alibaba Cloud account -- files cannot be shared across accounts.
48-hour expiry	Files are automatically deleted after 48 hours. Complete model calls within this period.
No post-upload management	Files cannot be queried, modified, or downloaded -- they serve only as URL parameters in model calls.
Rate limiting	The upload credential API is limited to 100 QPS per account per model. Excess requests fail. The temporary storage does not support scale-out.

Prerequisites

Before you begin:

An API key configured as an environment variable
The model name that will consume the file (e.g., qwen-vl-plus)

Step 1: Get a temporary URL

Upload a file and get its temporary URL using one of these methods:

Upload with code

Python

Prerequisites

Python 3.8 or later
Install dependencies:

pip install -U requests

Parameters

Parameter	Description	Example
`api_key`	Model Studio API key	Read from `DASHSCOPE_API_KEY` environment variable
`model_name`	The model that will consume the file	`qwen-vl-plus`
`file_path`	Path to the local file	`/tmp/cat.png`

Example code

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."""
    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 the temporary OSS storage."""
    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 (rate-limited to 100 QPS)
    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

# Example
if __name__ == "__main__":
    # Read the API key from the environment variable
    api_key = os.getenv("DASHSCOPE_API_KEY")
    if not api_key:
        raise Exception("Set the DASHSCOPE_API_KEY environment variable.")

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

    # Replace with the actual file path
    file_path = "/tmp/cat.png"

    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. URL valid for 48 hours.")
        print(f"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 with the oss:// prefix, you must add the X-DashScope-OssResourceResolve: enable parameter to the HTTP request header. For more information, see https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call")

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

Example output

File uploaded successfully. URL 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 with the oss:// prefix, you must add the X-DashScope-OssResourceResolve: enable parameter to the HTTP request header. For more information, see https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call

Important

After obtaining the temporary URL, add the X-DashScope-OssResourceResolve: enable header to HTTP requests when making a call. For more information, see Call using HTTP.

Java

Prerequisites

JDK 1.8 or later
Add the following dependencies to pom.xml:

 <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>

Parameters

Parameter	Description	Example
`apiKey`	Model Studio API key	Read from `DASHSCOPE_API_KEY` environment variable
`modelName`	The model that will consume the file	`qwen-vl-plus`
`filePath`	Path to the local file	`src/main/resources/tmp/cat.png`

Example code

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 {

    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) {
        // Read the API key from the environment variable
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            System.err.println("Set the DASHSCOPE_API_KEY environment variable.");
            System.exit(1);
        }
        // Model name
        String modelName = "qwen-vl-plus";
        // Replace with the actual file path
        String filePath = "src/main/resources/tmp/cat.png";

        try {
            // Check if 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. URL valid for 48 hours.");
            System.out.println("Expiration time: " + expireTime.format(formatter));
            System.out.println("Temporary URL: " + publicUrl);
            System.out.println("Note: When you use a temporary URL with the oss:// prefix, you must add the X-DashScope-OssResourceResolve: enable parameter to the HTTP request header. For more information, see https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call");
        } catch (IOException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Example output

File uploaded successfully. URL 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 with the oss:// prefix, you must add the X-DashScope-OssResourceResolve: enable parameter to the HTTP request header. For more information, see https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call

Important

After obtaining the temporary URL, add the X-DashScope-OssResourceResolve: enable header to HTTP requests when making a call. For more information, see Call using HTTP.

Upload with the CLI

The DashScope CLI uploads a file with a single command and returns the temporary URL.

Prerequisites

Python 3.8 or later
DashScope Python SDK version 1.24.0 or later:

pip install -U dashscope

CLI parameters

Parameter	Required	Description	Example
`oss.upload`	Yes	DashScope subcommand for file upload	`oss.upload`
`--model`	Yes	Target model for the file	`qwen-vl-plus`
`--file`	Yes	Local file path (relative or absolute)	`cat.png`, `/data/img.jpg`
`--api_key`	No	API key. Not required if the `DASHSCOPE_API_KEY` environment variable is set.	`sk-xxxx`

Upload with the environment variable (recommended)

Prerequisite: Configure the API key as an environment variable:

dashscope oss.upload --model qwen-vl-plus --file cat.png

Sample output:

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

Upload with an inline API key

dashscope oss.upload --model qwen-vl-plus --file cat.png --api_key sk-xxxxxxx

Sample output:

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

Important

After obtaining the temporary URL, add the X-DashScope-OssResourceResolve: enable header to HTTP requests when making a call. For more information, see Call using HTTP.

Step 2: Call the model with the temporary URL

After uploading a file, use the oss:// URL in your model call. Two rules apply:

Model consistency: Use the same model you specified during upload.
Account consistency: Use an API key that belongs to the same Alibaba Cloud account.

Choose one of these methods:

HTTP

When calling the API over HTTP (curl, Postman, etc.), add this header:

X-DashScope-OssResourceResolve: enable

Without this header, the API cannot resolve oss:// URLs and requests fail.

Example request

This example calls qwen-vl-plus to describe an uploaded image.

Replace oss://... with your actual temporary URL.

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-OssResourceResolve: enable' \
-d '{
  "model": "qwen-vl-plus",
  "messages": [{
      "role": "user",
      "content":
      [{"type": "text","text": "What is this?"},
       {"type": "image_url","image_url": {"url": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"}}]
    }]
}'

Example response

{
  "choices": [
    {
      "message": {
        "content": "This is a picture of a white cat running on the grass. The cat has blue eyes and looks very cute and lively. The background is a blurred natural landscape, which emphasizes the subject: the small cat dashing forward. This photographic technique is called shallow depth of field (or a large aperture effect). It makes the cat in the foreground sharp and clear while blurring the background to highlight the subject and create a dreamlike effect. Overall, this photo feels relaxed and pleasant, and it captures a great moment of the animal's behavior.",
        "role": "assistant"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 1253,
    "completion_tokens": 104,
    "total_tokens": 1357
  },
  "created": 1739349052,
  "system_fingerprint": null,
  "model": "qwen-vl-plus",
  "id": "chatcmpl-cfc4f2aa-22a8-9a94-8243-44c5bd9899bc"
}

DashScope SDK

The DashScope SDK handles the X-DashScope-OssResourceResolve header automatically -- pass the oss:// URL directly as the file parameter.

The OpenAI SDK is not supported. Not all models support SDK calls -- see the specific model's API reference for details.

Python

Prerequisite: DashScope Python SDK 1.24.0 or later.

This example calls qwen-vl-plus to describe an uploaded image. This code applies to qwen-vl and omni models.

Replace oss://... in the image parameter with your actual temporary URL.

import os
import dashscope

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?"}]
    }]

# If not configured as environment variable, replace with: api_key="sk-xxx"
api_key = os.getenv('DASHSCOPE_API_KEY')

response = dashscope.MultiModalConversation.call(
    api_key=api_key,
    model='qwen-vl-plus',
    messages=messages
)

print(response)

Example response

{
    "status_code": 200,
    "request_id": "ccd9dcfb-98f0-92bc-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "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."
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 1112,
        "output_tokens": 91,
        "input_tokens_details": {
            "text_tokens": 21,
            "image_tokens": 1091
        },
        "prompt_tokens_details": {
            "cached_tokens": 0
        },
        "total_tokens": 1203,
        "output_tokens_details": {
            "text_tokens": 91
        },
        "image_tokens": 1091
    }
}

Java

Prerequisite: DashScope Java SDK 2.21.0 or later.

This example calls qwen-vl-plus to describe an uploaded image. This code applies to qwen-vl and omni models.

Replace oss://... with your actual temporary URL.

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.JsonUtils;

import java.util.Arrays;

public class MultiModalConversationUsage {

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

    // If not configured as environment variable, replace with: api_key="sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void simpleMultiModalConversationCall() throws ApiException, NoApiKeyException, UploadFileException {
        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 e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }

}

Example 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"
                                ]
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

API reference

The code samples and CLI in Step 1 wrap these three API operations internally. Use this reference to implement the upload flow manually.

Get a file upload credential

GET https://dashscope.aliyuncs.com/api/v1/uploads

Important

The credential API is rate-limited to 100 QPS per account per model. The temporary storage cannot be scaled out. For production or high-concurrency workloads, use Alibaba Cloud OSS.

Request parameters

Location	Field	Type	Required	Description	Example
Header	Content-Type	_string_	Yes	Request type.	`application/json`
Header	Authorization	_string_	Yes	Model Studio API key.	`Bearer sk-xxx`
Params	action	_string_	Yes	Operation type. Set to `getPolicy`.	`getPolicy`
Params	model	_string_	Yes	Target model name.	`qwen-vl-plus`

Response parameters

Field	Type	Description	Example
request_id	_string_	Unique request ID.	`7574ee8f-...-11c33ab46e51`
data	_object_	-	-
data.policy	_string_	Upload credential.	`eyJl...1ZSJ9XX0=`
data.signature	_string_	Credential signature.	`g5K...d40=`
data.upload_dir	_string_	Upload directory path.	`dashscope-instant/xxx/2024-07-18/xxxx`
data.upload_host	_string_	OSS host for uploading.	`https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com`
data.expire_in_seconds	_string_	Credential validity in seconds. Get a new credential after expiry.	`300`
data.max_file_size_mb	_string_	Maximum upload file size in MB. Varies by model.	`100`
data.capacity_limit_mb	_string_	Daily upload capacity per Alibaba Cloud account in MB.	`999999999`
data.oss_access_key_id	_string_	Access key for the upload.	`LTAxxx`
data.x_oss_object_acl	_string_	Uploaded file access permission. `private` means the file is private.	`private`
data.x_oss_forbid_overwrite	_string_	Whether overwriting files with the same name is blocked. `true` means overwriting is blocked.	`true`

Sample request

curl --location 'https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model=qwen-vl-plus' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json'

If the API key is not configured as an environment variable, replace $DASHSCOPE_API_KEY with your API key: --header "Authorization: Bearer sk-xxx".

Sample response

{
    "request_id": "52f4383a-c67d-9f8c-xxxxxx",
    "data": {
        "policy": "eyJl...1ZSJ=",
        "signature": "eWy...=",
        "upload_dir": "dashscope-instant/xxx/2024-07-18/xxx",
        "upload_host": "https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com",
        "expire_in_seconds": 300,
        "max_file_size_mb": 100,
        "capacity_limit_mb": 999999999,
        "oss_access_key_id": "LTA...",
        "x_oss_object_acl": "private",
        "x_oss_forbid_overwrite": "true"
    }
}

Upload the file to temporary storage

POST {data.upload_host}

Replace {data.upload_host} with the data.upload_host from the credential response.

Request parameters

Location	Field	Type	Required	Description	Example
Header	Content-Type	_string_	No	Submit the form as `multipart/form-data`. The boundary is automatically generated by your HTTP client.	`multipart/form-data; boundary=9431149156168`
form-data	OSSAccessKeyId	_text_	Yes	`data.oss_access_key_id` from the credential response.	`LTAm5xxx`
form-data	policy	_text_	Yes	`data.policy` from the credential response.	`g5K...d40=`
form-data	Signature	_text_	Yes	`data.signature` from the credential response.	`Sm/tv7DcZuTZftFVvt5yOoSETsc=`
form-data	key	_text_	Yes	`data.upload_dir` from the credential response, appended with `/<filename>`.	`dashscope-instant/xxx/2024-07-18/xxx/cat.png`
form-data	x-oss-object-acl	_text_	Yes	`data.x_oss_object_acl` from the credential response.	`private`
form-data	x-oss-forbid-overwrite	_text_	Yes	`data.x_oss_forbid_overwrite` from the credential response.	`true`
form-data	success_action_status	_text_	No	HTTP status code returned on success. Typically `200`.	`200`
form-data	file	_file_	Yes	The file to upload. Only one file per request. The `file` field must be the last form field.	`file=@"/tmp/cat.png"`

On success, the API returns HTTP 200 with no response body.

Sample request

curl --location 'https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com' \
--form 'OSSAccessKeyId="LTAm5xxx"' \
--form 'Signature="Sm/tv7DcZuTZftFVvt5yOoSETsc="' \
--form 'policy="eyJleHBpcmF0aW9 ... ... ... dHJ1ZSJ9XX0="' \
--form 'x-oss-object-acl="private"' \
--form 'x-oss-forbid-overwrite="true"' \
--form 'key="dashscope-instant/xxx/2024-07-18/xxx/cat.png"' \
--form 'success_action_status="200"' \
--form 'file=@"/tmp/cat.png"'

Construct the file URL

Concatenate oss:// with the key from the upload request. This URL is valid for 48 hours.

oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png

Error codes

If API calls fail, see Error messages for general troubleshooting.

These error codes are specific to temporary file uploads:

HTTP status	Error code	Error message	Cause and resolution
400	invalid_parameter_error	InternalError.Algo.InvalidParameter: The provided URL does not appear to be valid. Ensure it is correctly formatted.	The URL is malformed. Verify the URL format. If using an `oss://` URL over HTTP, add the `X-DashScope-OssResourceResolve: enable` header.
400	InvalidParameter.DataInspection	The media format is not supported or incorrect for the data inspection.	The request header is missing `X-DashScope-OssResourceResolve: enable`, or the file format is not supported by the model. See Error messages.
403	AccessDenied	Invalid according to Policy: Policy expired.	The upload credential has expired. Call the credential API again to get a new one.
429	Throttling.RateQuota	Requests rate limit exceeded, please try again later.	The request rate exceeds 100 QPS. Reduce the request frequency, or migrate to OSS for production workloads.

FAQ

What should I do if an `oss://` URL returns an error?

Follow these steps:

Check the request header. If calling the API over HTTP (curl, Postman, etc.), add X-DashScope-OssResourceResolve: enable to the request header. Without this header, the server cannot resolve the oss:// protocol. The DashScope SDK adds this header automatically.
Check URL validity. The oss:// URL expires 48 hours after upload. If expired, upload the file again to get a new URL.

Can I use different API keys for file upload and model calls?

Yes, as long as both API keys belong to the same Alibaba Cloud account. File access is managed at the account level, not the API key level.

API keys from different Alibaba Cloud accounts cannot access each other's uploaded files.

How it works

Limitations

Prerequisites

Step 1: Get a temporary URL

Upload with code

Python

Java

Upload with the CLI

Step 2: Call the model with the temporary URL

HTTP

DashScope SDK

Python

Java

API reference

Get a file upload credential

Request parameters

Response parameters

Sample request

Sample response

Upload the file to temporary storage

Request parameters

Sample request

Construct the file URL

Error codes

FAQ

What should I do if an oss:// URL returns an error?

Can I use different API keys for file upload and model calls?

What should I do if an `oss://` URL returns an error?