Upload a file and get a temporary URL

When you call multimodal, image, video, or audio models, you often need to pass a file URL. QwenCloud provides free temporary storage: upload a local file, get a URL, and use that URL in the model call. The URL is valid for 48 hours.

Temporary storage is available in Singapore (ap-southeast-1), China North 2 (Beijing) (cn-beijing), and China (Hong Kong) (cn-hongkong).

Usage limits

Files are bound to a model: You must specify a model name when uploading, and the model must be the same model you call later. Different models cannot share a file. Each model also has its own file size limit; a file that exceeds the limit fails to upload.
Files are bound to an account: The API key used for upload and the API key used for the model call must belong to the same QwenCloud account. The uploaded file can be used only by that account and that model. Other accounts and other models cannot read it.
Files expire after 48 hours: Uploaded files are deleted automatically after 48 hours. Finish your model calls within that window.
Uploaded files are write-only: After upload, you cannot query, modify, or download the file. It can be used only as a URL parameter in a model call.
Upload policy rate limit: The upload policy endpoint is limited to 100 QPS per account and model. Requests above the limit fail.

A temporary URL expires after 48 hours and cannot be renewed. Do not use it in production.
The upload policy endpoint is limited to 100 QPS without quota increases. Do not use it for production workloads, high concurrency, or load testing.
For production, use durable storage such as Alibaba Cloud OSS so that files remain available and rate limits do not apply.

How it works

Get a temporary URL: Upload an image, video, or audio file as described in Step 1, and get a URL that starts with oss://.
Call the model: Pass the temporary URL as described in Step 2. This step is required; otherwise the request fails.

Step 1: Get a temporary URL

Option 1: Upload with code
Option 2: Upload with the CLI

The Python and Java samples below handle the upload for you. Specify the model and the file, and the sample returns the temporary URL.PrerequisitesGet an API key, then set the API key as an environment variable.

Sample code

Python
Java

Environment

Python 3.8 or later is recommended.
Install the dependencies:

pip install -U requests

Input parameters

api_key: QwenCloud API key.
model_name: The model that will use the file, such as qwen3-vl-plus.
file_path: Path to the local file to upload (image, video, or audio).

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

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
BASE_URL = "https://ap-southeast-1.maas.qwencloudapi.com"

def get_upload_policy(api_key, model_name):
  """Get an upload policy."""
  url = f"{BASE_URL}/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 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 a file and return its temporary URL."""
  # 1. Get an upload policy. This endpoint is rate-limited.
  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__":
  api_key = os.getenv("DASHSCOPE_API_KEY")
  if not api_key:
    raise Exception("Set the DASHSCOPE_API_KEY environment variable.")

  model_name = "qwen3-vl-plus"

  # Replace with the path to your file.
  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. It expires in 48 hours at {expire_time.strftime('%Y-%m-%d %H:%M:%S')}.")
    print(f"Temporary URL: {public_url}")
    print("When you use an oss:// URL over HTTP, add the X-DashScope-OssResourceResolve: enable request header.")

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

Output

File uploaded. It expires in 48 hours at 2026-10-24 17:36:15.
Temporary URL: oss://dashscope-instant/xxx/2026-10-22/xxx/cat.png
When you use an oss:// URL over HTTP, add the X-DashScope-OssResourceResolve: enable request header.

When you call a model over HTTP with a temporary URL, you must add the X-DashScope-OssResourceResolve: enable request header. See Call over HTTP.

Environment

JDK 1.8 or later is recommended.
Add these dependencies to your Maven 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>

Input parameters

apiKey: QwenCloud API key.
modelName: The model that will use the file, such as qwen3-vl-plus.
filePath: Path to the local file to upload (image, video, or audio).

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 {

    // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
    // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
    private static final String API_URL = "https://ap-southeast-1.maas.qwencloudapi.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) {
        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);
        }
        String modelName = "qwen3-vl-plus";
        // Replace with the path to your file.
        String filePath = "src/main/resources/tmp/cat.png";

        try {
            File file = new File(filePath);
            if (!file.exists()) {
                System.err.println("File not found: " + 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. It expires in 48 hours at " + expireTime.format(formatter) + ".");
            System.out.println("Temporary URL: " + publicUrl);
            System.out.println("When you use an oss:// URL over HTTP, add the X-DashScope-OssResourceResolve: enable request header.");
        } catch (IOException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Output

File uploaded. It expires in 48 hours at 2026-10-24 17:36:15.
Temporary URL: oss://dashscope-instant/xxx/2026-10-22/xxx/cat.png
When you use an oss:// URL over HTTP, add the X-DashScope-OssResourceResolve: enable request header.

When you call a model over HTTP with a temporary URL, you must add the X-DashScope-OssResourceResolve: enable request header. See Call over HTTP.

If you prefer the command line, use the DashScope CLI to upload a file. The command prints the temporary URL.

Prerequisites

Python 3.8 or later is recommended.
Get an API key.
Install DashScope Python SDK version 1.24.0 or later:

pip install -U dashscope

Method 1: Use an environment variable (recommended)
Method 2: Pass the API key on the command line (temporary use)

This method keeps the API key out of your shell history and scripts.First, set the API key as an environment variable.Run the upload command:

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope oss upload --model qwen3-vl-plus --file cat.png --base-url https://ap-southeast-1.maas.qwencloudapi.com/api/v1

Output:

Start oss.upload: model=qwen3-vl-plus, file=cat.png, api_key=None
Uploaded oss url: oss://dashscope-instant/xxxx/2026-10-22/xxxx/cat.png

--base-url is required on QwenCloud. Without it, the CLI uses the default endpoint and returns InvalidApiKey.

When you call a model over HTTP with a temporary URL, you must add the X-DashScope-OssResourceResolve: enable request header. See Call over HTTP.

Run the upload command:

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope oss upload --model qwen3-vl-plus --file cat.png --base-url https://ap-southeast-1.maas.qwencloudapi.com/api/v1 --api-key sk-xxxxxxx

Output:

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

When you call a model over HTTP with a temporary URL, you must add the X-DashScope-OssResourceResolve: enable request header. See Call over HTTP.

CLI parameters

Parameter	Required	Description	Example
oss upload	Yes	The `dashscope` subcommand that uploads a file.	oss upload
--model	Yes	The model that will use the file.	qwen3-vl-plus
--file	Yes	Path to the local file. A relative or absolute path works.	cat.png, /data/img.jpg
--base-url	Yes	Regional API base URL.	https://ap-southeast-1.maas.qwencloudapi.com/api/v1
--api-key	No	QwenCloud API key. Omit it if the environment variable is set.	sk-ws-xxxx

Step 2: Call a model with the temporary URL

Requirements

File format: The URL must be generated as described above and must start with oss://.
File not expired: The URL must be used within 48 hours of upload.
Same model: The model you call must be exactly the model you specified during upload.
Same account: The API key used for the model call must belong to the same QwenCloud account as the API key used for upload.

Option 1: Call over HTTP

When you call the API with curl, Postman, or any other HTTP client, follow these rules:

With a temporary URL, you must add X-DashScope-OssResourceResolve: enable to the request headers.
Without this header, the service cannot resolve the oss:// URL and the request fails. For the error message, see Error codes.

Request example
Response example

This example calls qwen3-vl-plus to describe an image.

Replace oss://... with your temporary URL, or the request fails.

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-OssResourceResolve: enable' \
-d '{
  "model": "qwen3-vl-plus",
  "messages": [{
      "role": "user",
      "content":
      [{"type": "text","text": "What is in this image?"},
       {"type": "image_url","image_url": {"url": "oss://dashscope-instant/xxx/2026-10-22/xxxx/cat.png"}}]
    }]
}'

{
  "choices": [
    {
      "message": {
        "content": "The image shows a white cat with light brown patches running across a grassy field. Its blue eyes are clearly visible, and the blurred background keeps the focus on the cat.",
        "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": "qwen3-vl-plus",
  "id": "chatcmpl-cfc4f2aa-22a8-9a94-8243-44c5bd9899bc"
}

Option 2: Call with the DashScope SDK

You can also use the DashScope Python or Java SDK.

Pass the URL directly: Pass the oss:// URL as the file parameter in the SDK call.
No header handling: The SDK adds the required header automatically.

Not every model supports SDK calls. Check the model's API reference. The OpenAI SDK is not supported.

Python
Java

PrerequisitesInstall DashScope Python SDK version 1.24.0 or later.Sample codeThis example calls qwen3-vl-plus to describe an image. The code applies to the qwen-vl and omni model families.

Request example
Response example

Replace oss://... in the image parameter with your temporary URL, or the request fails.

import os
import dashscope

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = "https://ap-southeast-1.maas.qwencloudapi.com/api/v1"

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

# If the environment variable is not set, replace the next line with api_key="sk-xxx".
api_key = os.getenv('DASHSCOPE_API_KEY')

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

print(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": "The image shows a white cat with light brown patches running across a grassy field. Its blue eyes are clearly visible, and the blurred green background and trees keep the focus on the cat."
            }
          ]
        }
      }
    ]
  },
  "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
  }
}

PrerequisitesInstall DashScope Java SDK version 2.21.0 or later.Sample codeThis example calls qwen3-vl-plus to describe an image. The code applies to the qwen-vl and omni model families.

Request example
Response example

Replace oss://... with your temporary URL, or the request fails.

import com.alibaba.dashscope.aigc.multimodalconversation.*;
import com.alibaba.dashscope.common.Constants;
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 = "qwen3-vl-plus";

    // If the environment variable is not set, replace the next line with apiKey="sk-xxx".
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void simpleMultiModalConversationCall() throws ApiException, NoApiKeyException, UploadFileException {
        // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
        // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
        Constants.baseHttpApiUrl = "https://ap-southeast-1.maas.qwencloudapi.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/2026-10-22/xxxx/cat.png");
        MultiModalMessageItemText userText = new MultiModalMessageItemText("What is in this image?");
        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)
                .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);
    }

}

{
  "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": "The image shows a white cat with light brown patches running across a grassy field. Its blue eyes are clearly visible, and the blurred green background and trees keep the focus on the cat."
            },
            {
              "image_hw": [
                [
                  "924",
                  "924"
                ]
              ]
            }
          ]
        }
      }
    ]
  }
}

Appendix: API details

The code samples and CLI above perform the following three steps for you. This section documents each step.

Step 1: Get an upload policy

Prerequisites Get an API key and set it as an environment variable. Request The following uses the Singapore (ap-southeast-1) endpoint. For another region, replace ap-southeast-1 and use an API key from that region. See Regions and endpoints.

GET https://ap-southeast-1.maas.qwencloudapi.com/api/v1/uploads

The upload policy endpoint is limited to 100 QPS per QwenCloud account and model, and temporary storage cannot be expanded. For production or high-concurrency workloads, use a storage service such as Alibaba Cloud OSS.

Request parameters

Location	Field	Type	Required	Description	Example
Header	Content-Type	string	Yes	Request content type: `application/json`.	application/json
Header	Authorization	string	Yes	QwenCloud API key, prefixed with `Bearer`.	Bearer sk-ws-xxx
Query	action	string	Yes	Action to perform. Use `getPolicy`.	getPolicy
Query	model	string	Yes	Name of the model that will use the file.	qwen3-vl-plus

Response parameters

Field	Type	Description	Example
request_id	string	Unique request identifier.	7574ee8f-...-11c33ab46e51
data	object	Upload policy.	-
data.policy	string	Upload policy.	eyJl...1ZSJ9XX0=
data.signature	string	Signature of the upload policy.	g5K...d40=
data.upload_dir	string	Directory for the uploaded file.	dashscope-instant/xxx/2026-10-22/xxxx
data.upload_host	string	Host to which the file is uploaded.	`https://dashscope-file-mgr-prod.oss-ap-southeast-1.aliyuncs.com`
data.expire_in_seconds	string	Policy validity in seconds. After it expires, call this endpoint again for a new policy.	300
data.max_file_size_mb	string	Maximum file size in MB. The value depends on the model.	1024
data.capacity_limit_mb	string	Daily upload capacity for the account, in MB.	999999999
data.oss_access_key_id	string	Access key used for the upload.	LTAxxx
data.x_oss_object_acl	string	Access control for the uploaded file. `private` means private.	private
data.x_oss_forbid_overwrite	string	Whether a file with the same name can be overwritten. `true` means it cannot.	true

Request example

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl --location 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1/uploads?action=getPolicy&model=qwen3-vl-plus' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json'

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

Response example

{
  "request_id": "52f4383a-c67d-9f8c-xxxxxx",
  "data": {
    "policy": "eyJl...1ZSJ=",
    "signature": "eWy...=",
    "upload_dir": "dashscope-instant/xxx/2026-10-22/xxx",
    "upload_host": "https://dashscope-file-mgr-prod.oss-ap-southeast-1.aliyuncs.com",
    "expire_in_seconds": 300,
    "max_file_size_mb": 1024,
    "capacity_limit_mb": 999999999,
    "oss_access_key_id": "LTA...",
    "x_oss_object_acl": "private",
    "x_oss_forbid_overwrite": "true"
  }
}

Step 2: Upload the file to temporary storage

Prerequisites

You have an upload policy.
The upload policy has not expired. If it has, call Step 1 again for a new policy.
To check the validity period, read data.expire_in_seconds in the Step 1 response.

Request

POST {data.upload_host}

Replace {data.upload_host} with the data.upload_host value from Step 1.

Request parameters

Location	Field	Type	Required	Description	Example
Header	Content-Type	string	No	Form submissions use `multipart/form-data`. The browser or HTTP client adds `boundary` automatically.	multipart/form-data; boundary=9431149156168
form-data	OSSAccessKeyId	text	Yes	The `data.oss_access_key_id` value from Step 1.	LTAm5xxx
form-data	policy	text	Yes	The `data.policy` value from Step 1.	g5K...d40=
form-data	Signature	text	Yes	The `data.signature` value from Step 1.	Sm/tv7DcZuTZftFVvt5yOoSETsc=
form-data	key	text	Yes	The `data.upload_dir` value from Step 1, followed by `/<file name>`.	dashscope-instant/xxx/2026-10-22/xxx/cat.png
form-data	x-oss-object-acl	text	Yes	The `data.x_oss_object_acl` value from Step 1.	private
form-data	x-oss-forbid-overwrite	text	Yes	The `data.x_oss_forbid_overwrite` value from Step 1.	true
form-data	success_action_status	text	No	Use `200` so the endpoint returns HTTP 200 after a successful upload.	200
form-data	file	file	Yes	The file or text content. Upload one file per request. `file` must be the last form field; the other fields can appear in any order.	file=@"/tmp/cat.png"

Response A successful call returns no content. Request example

curl --location 'https://dashscope-file-mgr-prod.oss-ap-southeast-1.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/2026-10-22/xxx/cat.png"' \
--form 'success_action_status="200"' \
--form 'file=@"/tmp/cat.png"'

Step 3: Build the file URL

The file URL is oss:// followed by the key you used in Step 2. The URL is valid for 48 hours.

oss://dashscope-instant/xxx/2026-10-22/xxxx/cat.png

Error codes

If a call fails, see Error messages. The following status codes are specific to this feature.

HTTP status	Error code	Error message	Meaning
400	invalid_parameter_error	InternalError.Algo.InvalidParameter: The provided URL does not appear to be valid. Ensure it is correctly formatted.	Invalid URL. Check the URL. For a temporary file URL, make sure the request includes the `X-DashScope-OssResourceResolve: enable` header.
400	InvalidParameter.DataInspection	The media format is not supported or incorrect for the data inspection.	Possible causes: (1) the request header is missing `X-DashScope-OssResourceResolve: enable`; (2) the image format does not meet the model's requirements. For details, see Error messages.
403	AccessDenied	Invalid according to Policy: Policy expired.	The upload policy expired. Call the upload policy endpoint again for a new policy.
429	Throttling.RateQuota	Requests rate limit exceeded, please try again later.	The request rate exceeded the limit. The upload policy endpoint allows 100 QPS per account and model. Lower the request rate or move to your own storage service such as OSS.

FAQ

Why does a call with an `oss://` URL fail?

Check the following:

Request header: If you call the API over HTTP (curl, Postman), you must add X-DashScope-OssResourceResolve: enable to the headers. Without it, the service cannot resolve the OSS internal protocol. See Call over HTTP.
URL validity: An oss:// URL is temporary. Make sure it was created within the last 48 hours. If it expired, upload the file again.

Can I use different API keys for the upload and the model call?

File storage and access are managed at the QwenCloud account level, and API keys are only credentials for that account. Different API keys under the same account work. API keys from different accounts cannot read the file because accounts are isolated. Make sure the API key used for upload and the API key used for the model call belong to the same QwenCloud account.

​Usage limits

​How it works

​Step 1: Get a temporary URL

Sample code

​Step 2: Call a model with the temporary URL

​Requirements

​Option 1: Call over HTTP

​Option 2: Call with the DashScope SDK

​Appendix: API details

​Step 1: Get an upload policy

​Step 2: Upload the file to temporary storage

​Step 3: Build the file URL

​Error codes

​FAQ

​Why does a call with an oss:// URL fail?

​Can I use different API keys for the upload and the model call?

Usage limits

How it works

Step 1: Get a temporary URL

Step 2: Call a model with the temporary URL

Requirements

Option 1: Call over HTTP

Option 2: Call with the DashScope SDK

Appendix: API details

Step 1: Get an upload policy

Step 2: Upload the file to temporary storage

Step 3: Build the file URL

Error codes

FAQ

Why does a call with an `oss://` URL fail?

Can I use different API keys for the upload and the model call?