Skip to main content

Upload local files to get temporary URLs

Les modèles multimodaux tels que Qwen-VL nécessitent des URL de fichiers pour les entrées d'images, de vidéos et d'audio. Si vous ne disposez pas d'URL publiques, Model Studio met à votre disposition un espace de stockage temporaire gratuit : importez un fichier et obtenez une URL oss:// valide pendant 48 heures .

Les URL temporaires sont réservées au développement et aux tests. Elles ne conviennent ni à la production, ni aux scénarios à forte concurrence, ni aux tests de charge. Pour les charges de travail en production, utilisez Object Storage Service (OSS) afin de garantir une disponibilité permanente et d'éviter les limites de taux.
Cette fonctionnalité est disponible dans les régions de Singapour et de China (Beijing). Les exemples de code de ce document utilisent la région de Singapour par défaut. Pour utiliser la région de Beijing, suivez les commentaires des exemples afin de remplacer dashscope-intl.aliyuncs.com par dashscope.aliyuncs.com dans l'URL de la requête, et utilisez une clé API de la région de Beijing (les clés API des deux régions sont différentes ; consultez clé API).

Fonctionnement

  1. Importez un fichier et spécifiez le modèle cible. L'API renvoie une URL oss://.
  2. Transmettez cette URL lors de l'appel au modèle. Vous devez impérativement effectuer l'étape 2 pour utiliser l'URL temporaire ; son omission entraîne des erreurs. Pour les appels HTTP, ajoutez l'en-tête X-DashScope-OssResourceResolve: enable. Le SDK DashScope ajoute automatiquement cet en-tête.

Limites

Contrainte

Détails

Association fichier-modèle

Spécifiez le nom du modèle lors de l'importation. Utilisez ce même modèle pour les appels ultérieurs, car les fichiers ne peuvent pas être partagés entre différents modèles.

Limites de taille de fichier

La taille du fichier ne doit pas dépasser 1 Go et doit respecter les limites spécifiques du modèle sélectionné.

Association fichier-compte

Les clés API utilisées pour l'importation et les appels au modèle doivent appartenir au même compte Alibaba Cloud. Le partage de fichiers entre comptes est impossible.

Expiration après 48 heures

Les fichiers sont automatiquement supprimés au bout de 48 heures. Effectuez vos appels au modèle dans ce délai.

Absence de gestion post-importation

Les fichiers ne peuvent être ni interrogés, ni modifiés, ni téléchargés. Ils servent uniquement de paramètres d'URL lors des appels au modèle.

Limitation du débit

L'API d'identifiants d'importation est limitée à 100 QPS par compte et par modèle. Les requêtes excédentaires échouent. Le stockage temporaire ne prend pas en charge la mise à l'échelle horizontale.

Prérequis

Avant de commencer :
  • Une clé API configurée en tant que variable d'environnement
  • Le nom du modèle qui consommera le fichier (par exemple, qwen3-vl-plus)

Étape 1 : Obtenir une URL temporaire

Importez un fichier et récupérez son URL temporaire à l'aide de l'une des méthodes suivantes :
  • Upload with code
  • Upload with the CLI
  • Python
  • Java
Prérequis
  • Python 3.9 ou version ultérieure
  • Installez les dépendances :
pip install -U requests
Paramètres

Paramètre

Description

Exemple

api_key

Clé API Model Studio

Lecture depuis la variable d'environnement DASHSCOPE_API_KEY

model_name

Modèle qui consommera le fichier

qwen3-vl-plus

file_path

Chemin vers le fichier local

/tmp/cat.png

Exemple de 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."""
    # 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/en/model-studio/get-temporary-file-url#http-call")

    except Exception as e:
        print(f"Error: {str(e)}")
Exemple de sortie
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/en/model-studio/get-temporary-file-url#http-call
Une fois l'URL temporaire obtenue, ajoutez l'en-tête X-DashScope-OssResourceResolve: enable aux requêtes HTTP lors de l'appel. Pour plus d'informations, consultez Appel via HTTP.

Étape 2 : Appeler le modèle avec l'URL temporaire

Après avoir importé un fichier, utilisez l'URL oss:// dans votre appel au modèle. Deux règles s'appliquent :
  • Cohérence du modèle : Utilisez le même modèle que celui spécifié lors de l'importation.
  • Cohérence du compte : Utilisez une clé API appartenant au même compte Alibaba Cloud.
Choisissez l'une des méthodes suivantes :

HTTP

Lorsque vous appelez l'API via HTTP (curl, Postman, etc.), ajoutez cet en-tête :
X-DashScope-OssResourceResolve: enable
Sans cet en-tête, l'API ne peut pas résoudre les URL oss:// et les requêtes échouent. Exemple de requête Cet exemple appelle qwen3-vl-plus pour décrire une image importée.
Remplacez oss://... par votre URL temporaire réelle.
# 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"}}]
    }]
}'
Exemple de réponse
{
  "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 DashScope

Le SDK DashScope gère automatiquement l'en-tête X-DashScope-OssResourceResolve. Transmettez directement l'URL oss:// comme paramètre de fichier.
Le SDK OpenAI n'est pas pris en charge. Tous les modèles ne prennent pas en charge les appels SDK ; consultez la référence API du modèle concerné pour plus de détails.
  • Python
  • Java
Prérequis : SDK Python DashScope 2.0.1 ou version ultérieure.Cet exemple appelle qwen3-vl-plus pour décrire une image importée. Ce code s'applique aux modèles qwen-vl et omni.
Remplacez oss://... dans le paramètre d'image par votre URL temporaire réelle.
import os
import dashscope

# The API keys for the Singapore and Beijing regions are different. Use the key for the corresponding region.
# Si la variable d'environnement n'est pas configurée, remplacez par : 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)
Exemple de réponse
{
    "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
        }
    }
}

Référence API

Les exemples de code et la CLI de l'étape 1 encapsulent ces trois opérations API. Utilisez cette référence pour mettre en œuvre manuellement le flux d'importation.

Obtenir un identifiant d'importation de fichier

Singapore: GET https://dashscope-intl.aliyuncs.com/api/v1/uploads
Beijing: GET https://dashscope.aliyuncs.com/api/v1/uploads
L'API d'identifiants est limitée à 100 QPS par compte et par modèle. Le stockage temporaire ne peut pas être mis à l'échelle horizontalement. Pour les charges de travail en production ou à forte concurrence, utilisez Alibaba Cloud OSS.

Paramètres de la requête

Emplacement

Champ

Type

Obligatoire

Description

Exemple

Header

Content-Type

_string_

Oui

Type de requête.

application/json

Header

Authorization

_string_

Oui

Clé API Model Studio.

Bearer sk-xxx

Params

action

_string_

Oui

Type d'opération. Définissez sur getPolicy.

getPolicy

Params

model

_string_

Oui

Nom du modèle cible.

qwen3-vl-plus

Paramètres de la réponse

Champ

Type

Description

Exemple

request_id

_string_

ID unique de la requête.

7574ee8f-...-11c33ab46e51

data

_object_

-

-

data.policy

_string_

Identifiant d'importation.

eyJl...1ZSJ9XX0=

data.signature

_string_

Signature de l'identifiant.

g5K...d40=

data.upload_dir

_string_

Chemin du répertoire d'importation.

dashscope-instant/xxx/2024-07-18/xxxx

data.upload_host

_string_

Hôte OSS pour l'importation.

https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com

data.expire_in_seconds

_string_

Validité de l'identifiant en secondes. Obtenez un nouvel identifiant après expiration.

300

data.max_file_size_mb

_string_

Taille maximale du fichier à importer en Mo. Varie selon le modèle.

100

data.capacity_limit_mb

_string_

Capacité d'importation quotidienne par compte Alibaba Cloud en Mo.

999999999

data.oss_access_key_id

_string_

Clé d'accès pour l'importation.

LTAxxx

data.x_oss_object_acl

_string_

Autorisation d'accès au fichier importé. La valeur private indique que le fichier est privé.

private

data.x_oss_forbid_overwrite

_string_

Indique si l'écrasement des fichiers portant le même nom est bloqué. La valeur true signifie que l'écrasement est bloqué.

true

Exemple de requête

# 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 clé API n'est pas configurée en tant que variable d'environnement, remplacez $DASHSCOPE_API_KEY par votre clé API : --header "Authorization: Bearer sk-xxx" .

Exemple de réponse

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

Importer le fichier vers le stockage temporaire

POST {data.upload_host}
Remplacez {data.upload_host} par la valeur data.upload_host issue de la réponse d'identifiant.

Paramètres de la requête

Emplacement

Champ

Type

Obligatoire

Description

Exemple

Header

Content-Type

_string_

Non

Soumettez le formulaire en tant que multipart/form-data. La limite est générée automatiquement par votre client HTTP.

multipart/form-data; boundary=9431149156168

form-data

OSSAccessKeyId

_text_

Oui

data.oss_access_key_id issu de la réponse d'identifiant.

LTAm5xxx

form-data

policy

_text_

Oui

data.policy issu de la réponse d'identifiant.

g5K...d40=

form-data

Signature

_text_

Oui

data.signature issu de la réponse d'identifiant.

Sm/tv7DcZuTZftFVvt5yOoSETsc=

form-data

key

_text_

Oui

data.upload_dir issu de la réponse d'identifiant, suivi de /<filename>.

dashscope-instant/xxx/2024-07-18/xxx/cat.png

form-data

x-oss-object-acl

_text_

Oui

data.x_oss_object_acl issu de la réponse d'identifiant.

private

form-data

x-oss-forbid-overwrite

_text_

Oui

data.x_oss_forbid_overwrite issu de la réponse d'identifiant.

true

form-data

success_action_status

_text_

Non

Code d'état HTTP renvoyé en cas de succès. Généralement 200.

200

form-data

file

_file_

Oui

Fichier à importer. Un seul fichier par requête. Le champ file doit être le dernier champ du formulaire.

file=@"/tmp/cat.png"

En cas de succès, l'API renvoie un code HTTP 200 sans corps de réponse.

Exemple de requête

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

Construire l'URL du fichier

Concaténez oss:// avec la valeur key issue de la requête d'importation. Cette URL est valide pendant 48 heures.
oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png

Codes d'erreur

Si les appels API échouent, consultez la rubrique Messages d'erreur pour le dépannage général. Les codes d'erreur suivants sont spécifiques aux importations de fichiers temporaires :

État HTTP

Code d'erreur

Message d'erreur

Cause et résolution

400

invalid_parameter_error

InternalError.Algo.InvalidParameter: The provided URL does not appear to be valid. Ensure it is correctly formatted.

L'URL est mal formée. Vérifiez le format de l'URL. Si vous utilisez une URL oss:// via HTTP, ajoutez l'en-tête X-DashScope-OssResourceResolve: enable.

400

InvalidParameter.DataInspection

The media format is not supported or incorrect for the data inspection.

L'en-tête de requête ne contient pas X-DashScope-OssResourceResolve: enable, ou le format de fichier n'est pas pris en charge par le modèle. Consultez la rubrique Messages d'erreur.

403

AccessDenied

Invalid according to Policy: Policy expired.

L'identifiant d'importation a expiré. Appelez à nouveau l'API d'identifiants pour en obtenir un nouveau.

429

Throttling.RateQuota

Requests rate limit exceeded, please try again later.

Le taux de requêtes dépasse 100 QPS. Réduisez la fréquence des requêtes ou migrez vers OSS pour les charges de travail en production.

FAQ

Que faire si une URL oss:// renvoie une erreur ?

Suivez ces étapes :
  1. Vérifiez l'en-tête de la requête. Si vous appelez l'API via HTTP (curl, Postman, etc.), ajoutez X-DashScope-OssResourceResolve: enable à l'en-tête de la requête. Sans cet en-tête, le serveur ne peut pas résoudre le protocole oss://. Le SDK DashScope ajoute automatiquement cet en-tête.
  2. Vérifiez la validité de l'URL. L'URL oss:// expire 48 heures après l'importation. Si elle a expiré, importez à nouveau le fichier pour obtenir une nouvelle URL.

Puis-je utiliser différentes clés API pour l'importation de fichiers et les appels au modèle ?

Oui, à condition que les deux clés API appartiennent au même compte Alibaba Cloud. L'accès aux fichiers est géré au niveau du compte, et non au niveau de la clé API. Les clés API provenant de comptes Alibaba Cloud différents ne peuvent pas accéder aux fichiers importés par les autres comptes.