Cargar archivos locales para obtener URL temporales

Las URL temporales son solo para desarrollo y pruebas, no para producción, escenarios de alta concurrencia ni pruebas de estrés. Para cargas de trabajo de producción, utilice Object Storage Service (OSS) para garantizar disponibilidad a largo plazo y evitar límites de velocidad.

Esta función está disponible en las regiones de Singapur y China (Beijing). Los ejemplos de código de este documento utilizan la región de Singapur de forma predeterminada. Para usar la región de Beijing, siga los comentarios de los ejemplos para reemplazar dashscope-intl.aliyuncs.com por dashscope.aliyuncs.com en la URL de la solicitud y utilice una clave de API de la región de Beijing (las claves de API de ambas regiones son diferentes; consulte clave de API).

Funcionamiento

Cargue un archivo y especifique el modelo de destino. La API devuelve una URL oss://.
Pase esa URL en su llamada al modelo. Debe completar el Paso 2 para usar la URL temporal; omitirlo provoca errores. Para llamadas HTTP, agregue el encabezado X-DashScope-OssResourceResolve: enable. El SDK de DashScope agrega este encabezado automáticamente.

Limitaciones

Restricción	Detalle
Vinculación archivo-modelo	Especifique el nombre del modelo durante la carga. Utilice el mismo modelo en llamadas posteriores; los archivos no se pueden compartir entre modelos.
Límites de tamaño de archivo	El tamaño del archivo no debe exceder 1 GB y también debe cumplir con los límites específicos del modelo seleccionado.
Vinculación archivo-cuenta	Las claves de API para la carga y las llamadas al modelo deben pertenecer a la misma cuenta de Alibaba Cloud; los archivos no se pueden compartir entre cuentas.
Caducidad de 48 horas	Los archivos se eliminan automáticamente después de 48 horas. Complete las llamadas al modelo dentro de este período.
Sin gestión posterior a la carga	Los archivos no se pueden consultar, modificar ni descargar; solo sirven como parámetros de URL en las llamadas al modelo.
Limitación de tasa	La API de credenciales de carga está limitada a 100 QPS por cuenta y por modelo. Las solicitudes excedentes fallarán. El almacenamiento temporal no admite escalado horizontal.

Requisitos previos

Antes de comenzar:

Una clave de API configurada como variable de entorno
El nombre del modelo que consumirá el archivo (por ejemplo, qwen3-vl-plus)

Paso 1: Obtener una URL temporal

Cargue un archivo y obtenga su URL temporal mediante uno de estos métodos:

Cargar con código
Cargar con la CLI

Python
Java
CLI de dashscope

Requisitos previos

Python 3.9 o posterior
Instale las dependencias:

pip install -U requests

Parámetros

Parámetro	Descripción	Ejemplo
`api_key`	Clave de API de Model Studio	Leído de la variable de entorno `DASHSCOPE_API_KEY`
`model_name`	El modelo que consumirá el archivo	`qwen3-vl-plus`
`file_path`	Ruta al archivo local	`/tmp/cat.png`

Código de ejemplo

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 Singapore and Beijing regions are different. Use the key for the corresponding region.
    # The URL below is for the Singapore region. For the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1/uploads
    url = "https://dashscope-intl.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="qwen3-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/model-studio/get-temporary-file-url#http-call")

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

Salida de ejemplo

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/model-studio/get-temporary-file-url#http-call

Después de obtener la URL temporal, agregue el encabezado X-DashScope-OssResourceResolve: enable a las solicitudes HTTP al realizar una llamada. Para obtener más información, consulte Llamada mediante HTTP.

Requisitos previos

JDK 1.8 o posterior
Agregue las siguientes dependencias a 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>

Parámetros

Parámetro	Descripción	Ejemplo
`apiKey`	Clave de API de Model Studio	Leído de la variable de entorno `DASHSCOPE_API_KEY`
`modelName`	El modelo que consumirá el archivo	`qwen3-vl-plus`
`filePath`	Ruta al archivo local	`src/main/resources/tmp/cat.png`

Código de ejemplo

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 Singapore and Beijing regions are different. Use the key for the corresponding region.
    // The URL below is for the Singapore region. For the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1/uploads
    private static final String API_URL = "https://dashscope-intl.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 = "qwen3-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/model-studio/get-temporary-file-url#http-call");
        } catch (IOException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Salida de ejemplo

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/model-studio/get-temporary-file-url#http-call

Llamada a través de la línea de comandos dashscope.

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.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

El asistente interactivo SDK Expert puede realizar las mismas tareas de desarrollo y solución de problemas mediante lenguaje natural; consulte DashScope SDK Expert.

Para la tabla completa de regiones, consulte Resumen de URL base.

La CLI de DashScope carga un archivo con un solo comando y devuelve la URL temporal.Requisitos previos

Python 3.9 o posterior
SDK de Python de DashScope versión 2.0.1 o posterior:

pip install -U dashscope

Parámetros de CLI

Parámetro	Obligatorio	Descripción	Ejemplo
`oss.upload`	Sí	Subcomando de DashScope para carga de archivos	`oss.upload`
`--model`	Sí	Modelo de destino para el archivo	`qwen3-vl-plus`
`--file`	Sí	Ruta del archivo local (relativa o absoluta)	`cat.png`, `/data/img.jpg`
`--api_key`	No	Clave de API. No es necesaria si la variable de entorno `DASHSCOPE_API_KEY` está configurada.	`sk-xxxx`

Carga con la variable de entorno (recomendado)Requisito previo: Configure la clave de API como variable de entorno:

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

Salida de ejemplo:

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

Carga con una clave de API en línea

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

Salida de ejemplo:

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

Paso 2: Llamar al modelo con la URL temporal

Después de cargar un archivo, utilice la URL oss:// en su llamada al modelo. Se aplican dos reglas:

Consistencia del modelo: Utilice el mismo modelo que especificó durante la carga.
Consistencia de cuenta: Utilice una clave de API que pertenezca a la misma cuenta de Alibaba Cloud.

Elija uno de estos métodos:

HTTP

Al llamar a la API a través de HTTP (curl, Postman, etc.), agregue este encabezado:

X-DashScope-OssResourceResolve: enable

Sin este encabezado, la API no puede resolver las URL oss:// y las solicitudes fallan. Solicitud de ejemplo Este ejemplo llama a qwen3-vl-plus para describir una imagen cargada.

Reemplace oss://... con su URL temporal real.

# The URL below is for the Singapore region. For the Beijing region, replace it with: https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
curl -X POST https://dashscope-intl.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": "qwen3-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"}}]
    }]
}'

Ejemplo de respuesta

{
  "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": "qwen3-vl-plus",
  "id": "chatcmpl-cfc4f2aa-22a8-9a94-8243-44c5bd9899bc"
}

SDK de DashScope

El SDK de DashScope maneja el encabezado X-DashScope-OssResourceResolve automáticamente; pase la URL oss:// directamente como parámetro de archivo.

El SDK de OpenAI no es compatible. No todos los modelos admiten llamadas mediante SDK; consulte la referencia de API del modelo específico para obtener más detalles.

Python
Java

Requisito previo: SDK de Python de DashScope 2.0.1 o posterior.Este ejemplo llama a qwen3-vl-plus para describir una imagen cargada. Este código se aplica a los modelos qwen-vl y omni.

Reemplace oss://... en el parámetro de imagen con su URL temporal real.

import os
import dashscope

# The API keys for the Singapore and Beijing regions are different. Use the key for the corresponding region.
# Si no se ha configurado como variable de entorno, sustitúyala por: 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)

Ejemplo de respuesta

{
    "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
        }
    }
}

Requisito previo: SDK de Java de DashScope 2.21.0 o posterior.Este ejemplo llama a qwen3-vl-plus para describir una imagen cargada. Este código se aplica a los modelos qwen-vl y omni.

Reemplace oss://... con su URL temporal real.

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 Singapore and Beijing regions are different. Use the key for the corresponding region.
    // 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 {
        // The URL below is for the Singapore region. For the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.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 e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }

}

Ejemplo de respuesta

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

Referencia de API

Los ejemplos de código y la CLI en el Paso 1 encapsulan estas tres operaciones de API internamente. Utilice esta referencia para implementar el flujo de carga manualmente.

Obtener una credencial de carga de archivos

Singapore: GET https://dashscope-intl.aliyuncs.com/api/v1/uploads
Beijing: GET https://dashscope.aliyuncs.com/api/v1/uploads

La API de credenciales tiene un límite de 100 QPS por cuenta y por modelo. El almacenamiento temporal no se puede escalar horizontalmente. Para cargas de trabajo de producción o de alta concurrencia, utilice Alibaba Cloud OSS.

Parámetros de solicitud

Location	Campo	Tipo	Obligatorio	Descripción	Ejemplo
Header	Content-Type	_string_	Sí	Tipo de solicitud.	`application/json`
Header	Authorization	_string_	Sí	Clave de API de Model Studio.	`Bearer sk-xxx`
Params	action	_string_	Sí	Tipo de operación. Establezca en `getPolicy`.	`getPolicy`
Params	model	_string_	Sí	Nombre del modelo objetivo.	`qwen3-vl-plus`

Parámetros de respuesta

Campo	Tipo	Descripción	Ejemplo
request_id	_string_	ID único de solicitud.	`7574ee8f-...-11c33ab46e51`
data	_object_	-	-
data.policy	_string_	Credencial de carga.	`eyJl...1ZSJ9XX0=`
data.signature	_string_	Firma de credencial.	`g5K...d40=`
data.upload_dir	_string_	Ruta del directorio de carga.	`dashscope-instant/xxx/2024-07-18/xxxx`
data.upload_host	_string_	Host de OSS para la carga.	`https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com`
data.expire_in_seconds	_string_	Validez de la credencial en segundos. Obtenga una nueva credencial después de la caducidad.	`300`
data.max_file_size_mb	_string_	Tamaño máximo de archivo de carga en MB. Varía según el modelo.	`100`
data.capacity_limit_mb	_string_	Capacidad de carga diaria por cuenta de Alibaba Cloud en MB.	`999999999`
data.oss_access_key_id	_string_	Clave de acceso para la carga.	`LTAxxx`
data.x_oss_object_acl	_string_	Permiso de acceso al archivo cargado. `private` significa que el archivo es privado.	`private`
data.x_oss_forbid_overwrite	_string_	Indica si se bloquea la sobrescritura de archivos con el mismo nombre. `true` significa que la sobrescritura está bloqueada.	`true`

Solicitud de ejemplo

# The URL below is for the Singapore region. For the Beijing region, replace it with: https://dashscope.aliyuncs.com/api/v1/uploads
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/uploads?action=getPolicy&model=qwen3-vl-plus' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json'

Si la clave de API no está configurada como variable de entorno, reemplace $DASHSCOPE_API_KEY con su clave de API: --header "Authorization: Bearer sk-xxx".

Respuesta de ejemplo

{
    "request_id": "52f4383a-c67d-9f8c-xxxxxx",
    "data": {
        "policy": "eyJl...1ZSJ=",
        "signature": "YOUR_SIGNATURE",
        "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"
    }
}

Cargar el archivo en el almacenamiento temporal

POST {data.upload_host}

Reemplace {data.upload_host} con el data.upload_host de la respuesta de credencial.

Parámetros de solicitud

Location	Campo	Tipo	Obligatorio	Descripción	Ejemplo
Header	Content-Type	_string_	No	Envíe el formulario como `multipart/form-data`. El límite es generado automáticamente por su cliente HTTP.	`multipart/form-data; boundary=9431149156168`
form-data	OSSAccessKeyId	_text_	Sí	`data.oss_access_key_id` de la respuesta de credencial.	`LTAm5xxx`
form-data	política	_text_	Sí	`data.policy` de la respuesta de credencial.	`g5K...d40=`
form-data	Signature	_text_	Sí	`data.signature` de la respuesta de credencial.	`Sm/tv7DcZuTZftFVvt5yOoSETsc=`
form-data	key	_text_	Sí	`data.upload_dir` de la respuesta de credencial, con `/<filename>` anexado.	`dashscope-instant/xxx/2024-07-18/xxx/cat.png`
form-data	x-oss-object-acl	_text_	Sí	`data.x_oss_object_acl` de la respuesta de credencial.	`private`
form-data	x-oss-forbid-overwrite	_text_	Sí	`data.x_oss_forbid_overwrite` de la respuesta de credencial.	`true`
form-data	success_action_status	_text_	No	Código de estado HTTP devuelto en caso de éxito. Normalmente `200`.	`200`
form-data	file	_file_	Sí	El archivo a cargar. Solo se permite un archivo por solicitud. El campo `file` debe ser el último campo del formulario.	`file=@"/tmp/cat.png"`

En caso de éxito, la API devuelve HTTP 200 sin cuerpo de respuesta.

Solicitud de ejemplo

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

Construya la URL del archivo

Concatene oss:// con la key de la solicitud de carga. Esta URL es válida durante 48 horas.

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

Códigos de error

Si las llamadas a la API fallan, consulte Mensajes de error para la resolución general de problemas. Estos códigos de error son específicos de las cargas de archivos temporales:

Estado HTTP	Código de error	Mensaje de error	Causa y solución
400	invalid_parameter_error	InternalError.Algo.InvalidParameter: La URL proporcionada no parece ser válida. Asegúrese de que tenga el formato correcto.	La URL tiene un formato incorrecto. Verifique el formato de la URL. Si utiliza una URL `oss://` a través de HTTP, agregue el encabezado `X-DashScope-OssResourceResolve: enable`.
400	InvalidParameter.DataInspection	El formato multimedia no es compatible o es incorrecto para la inspección de datos.	Falta el encabezado de solicitud `X-DashScope-OssResourceResolve: enable` o el modelo no admite el formato de archivo. Consulte Mensajes de error.
403	AccessDenied	Inválido según la política: La política ha caducado.	La credencial de carga ha caducado. Llame nuevamente a la API de credenciales para obtener una nueva.
429	Throttling.RateQuota	Se ha excedido el límite de tasa de solicitudes; inténtelo de nuevo más tarde.	La tasa de solicitudes supera los 100 QPS. Reduzca la frecuencia de solicitudes o migre a OSS para cargas de trabajo de producción.

FAQ

¿Qué debo hacer si una URL `oss://` devuelve un error?

Siga estos pasos:

Verifique el encabezado de la solicitud. Si llama a la API mediante HTTP (curl, Postman, etc.), agregue X-DashScope-OssResourceResolve: enable al encabezado de la solicitud. Sin este encabezado, el servidor no puede resolver el protocolo oss://. El SDK de DashScope agrega este encabezado automáticamente.
Verifique la validez de la URL. La URL oss:// caduca 48 horas después de la carga. Si ha caducado, cargue el archivo nuevamente para obtener una nueva URL.

¿Puedo usar diferentes claves de API para la carga de archivos y las llamadas al modelo?

Sí, siempre que ambas claves de API pertenezcan a la misma cuenta de Alibaba Cloud. El acceso a los archivos se gestiona a nivel de cuenta, no a nivel de clave de API. Las claves de API de diferentes cuentas de Alibaba Cloud no pueden acceder a los archivos cargados por otras cuentas.

​Funcionamiento

​Limitaciones

​Requisitos previos

​Paso 1: Obtener una URL temporal

​Paso 2: Llamar al modelo con la URL temporal

​HTTP

​SDK de DashScope

​Referencia de API

​Obtener una credencial de carga de archivos

​Parámetros de solicitud

​Parámetros de respuesta

​Solicitud de ejemplo

​Respuesta de ejemplo

​Cargar el archivo en el almacenamiento temporal

​Parámetros de solicitud

​Solicitud de ejemplo

​Construya la URL del archivo

​Códigos de error

​FAQ

​¿Qué debo hacer si una URL oss:// devuelve un error?

​¿Puedo usar diferentes claves de API para la carga de archivos y las llamadas al modelo?

Funcionamiento

Limitaciones

Requisitos previos

Paso 1: Obtener una URL temporal

Paso 2: Llamar al modelo con la URL temporal

HTTP

SDK de DashScope

Referencia de API

Obtener una credencial de carga de archivos

Parámetros de solicitud

Parámetros de respuesta

Solicitud de ejemplo

Respuesta de ejemplo

Cargar el archivo en el almacenamiento temporal

Parámetros de solicitud

Solicitud de ejemplo

Construya la URL del archivo

Códigos de error

FAQ

¿Qué debo hacer si una URL `oss://` devuelve un error?

¿Puedo usar diferentes claves de API para la carga de archivos y las llamadas al modelo?