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 .
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
- Importez un fichier et spécifiez le modèle cible. L'API renvoie une URL
oss://. - 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
- Python 3.9 ou version ultérieure
- Installez les dépendances :
Paramètre | Description | Exemple |
|---|---|---|
| Clé API Model Studio | Lecture depuis la variable d'environnement |
| Modèle qui consommera le fichier |
|
| Chemin vers le fichier local |
|
É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.
HTTP
Lorsque vous appelez l'API via HTTP (curl, Postman, etc.), ajoutez cet en-tête :
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.
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
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.
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
Paramètres de la requête
Emplacement | Champ | Type | Obligatoire | Description | Exemple |
|---|---|---|---|---|---|
Header | Content-Type | _string_ | Oui | Type de requête. |
|
Header | Authorization | _string_ | Oui | Clé API Model Studio. |
|
Params | action | _string_ | Oui | Type d'opération. Définissez sur |
|
Params | model | _string_ | Oui | Nom du modèle cible. |
|
Paramètres de la réponse
Champ | Type | Description | Exemple |
|---|---|---|---|
request_id | _string_ | ID unique de la requête. |
|
data | _object_ | - | - |
data.policy | _string_ | Identifiant d'importation. |
|
data.signature | _string_ | Signature de l'identifiant. |
|
data.upload_dir | _string_ | Chemin du répertoire d'importation. |
|
data.upload_host | _string_ | Hôte OSS pour l'importation. | |
data.expire_in_seconds | _string_ | Validité de l'identifiant en secondes. Obtenez un nouvel identifiant après expiration. |
|
data.max_file_size_mb | _string_ | Taille maximale du fichier à importer en Mo. Varie selon le modèle. |
|
data.capacity_limit_mb | _string_ | Capacité d'importation quotidienne par compte Alibaba Cloud en Mo. |
|
data.oss_access_key_id | _string_ | Clé d'accès pour l'importation. |
|
data.x_oss_object_acl | _string_ | Autorisation d'accès au fichier importé. La valeur |
|
data.x_oss_forbid_overwrite | _string_ | Indique si l'écrasement des fichiers portant le même nom est bloqué. La valeur |
|
Exemple de requête
Si la clé API n'est pas configurée en tant que variable d'environnement, remplacez$DASHSCOPE_API_KEYpar votre clé API :--header "Authorization: Bearer sk-xxx".
Exemple de réponse
Importer le fichier vers le stockage temporaire
Remplacez{data.upload_host}par la valeurdata.upload_hostissue 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 |
|
form-data | OSSAccessKeyId | _text_ | Oui |
|
|
form-data | policy | _text_ | Oui |
|
|
form-data | Signature | _text_ | Oui |
|
|
form-data | key | _text_ | Oui |
|
|
form-data | x-oss-object-acl | _text_ | Oui |
|
|
form-data | x-oss-forbid-overwrite | _text_ | Oui |
|
|
form-data | success_action_status | _text_ | Non | Code d'état HTTP renvoyé en cas de succès. Généralement |
|
form-data | file | _file_ | Oui | Fichier à importer. Un seul fichier par requête. Le champ |
|
Exemple de requête
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.
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 |
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 |
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 :
- 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 protocoleoss://. Le SDK DashScope ajoute automatiquement cet en-tête. - 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.