Télécharger une ressource dans la bibliothèque multimédia
/media_library/create
Utilisez cet endpoint pour ajouter une ressource à la bibliothèque multimédia de Braze à partir d’une URL hébergée en externe (
asset_url) ou de données de fichier binaire envoyées dans le corps de la requête (asset_file). Cet endpoint prend en charge les images, les documents et les fichiers ZIP qui les contiennent. Pour la liste complète, consultez Types de fichiers pris en charge.
Types de fichiers pris en charge
Cet endpoint accepte les types de fichiers suivants, que vous les téléchargiez via asset_url ou asset_file.
| Type de ressource | Types de fichiers pris en charge | Taille maximale |
|---|---|---|
| Image | GIF, ICO, JPEG, JPG, PNG, WebP | 5 Mo |
| Image vectorielle | SVG | 5 Mo |
| Document | DOC, DOCX, PDF, PPT, PPTX, XLS, XLSX | 5 Mo |
| Archive | ZIP | 50 Mo au total, 5 Mo par fichier dans le ZIP |
Si vous téléchargez un type de fichier qui ne figure pas dans cette liste, l’endpoint renvoie une erreur UNSUPPORTED_FILE_TYPE.
Pour les fichiers ZIP, chaque fichier de l’archive doit également correspondre à l’un des types de fichiers pris en charge listés ici, et tous les fichiers doivent se trouver à la racine du fichier ZIP (sans sous-répertoires). Tout fichier non pris en charge est ignoré et renvoyé dans le tableau errors de la réponse, tandis que le reste de l’archive est tout de même téléchargé.

Les fichiers de contact virtuels (.vcf) et les fichiers vidéo peuvent être téléchargés dans la bibliothèque multimédia, mais uniquement via l’interface du tableau de bord (Contenu > Bibliothèque multimédia), et non via cet endpoint API.

Vous pouvez également appeler cet endpoint via le serveur MCP de Braze à l’aide de la fonction create_media_library_asset. Des outils d’IA comme Claude et Cursor peuvent ainsi télécharger des ressources dans votre bibliothèque multimédia à partir d’instructions en langage naturel.
Prérequis
Pour utiliser cet endpoint, vous aurez besoin d’une clé API disposant de l’autorisation media_library.create.
Limite de débit
Cet endpoint a une limite de débit de 100 requêtes par heure, comme indiqué dans Limites de débit de l’API.
Corps de la requête
Lorsque vous incluez asset_url, l’endpoint télécharge le fichier à partir de l’URL. Lorsque vous incluez asset_file, l’endpoint utilise les données binaires présentes dans le corps de la requête.
Exemple de corps de requête pour asset_url :
{
"asset_url": "https://cdn.example.com/assets/cat.jpg",
"name": "Cat Graphic"
}
Exemple de corps de requête pour asset_file :
{
"asset_file": <BINARY FILE DATA>,
"name": "Cat Graphic"
}
Le corps de la requête comprend les paramètres suivants :
| Paramètre | Requis | Type de données | Description |
|---|---|---|---|
asset_url |
Facultatif | Chaîne de caractères | Une URL accessible publiquement pour la ressource à télécharger dans Braze. |
asset_file |
Facultatif | Binaire | Données de fichier binaire. |
name |
Facultatif | Chaîne de caractères | Le nom qui apparaîtra dans la bibliothèque multimédia pour cette ressource. |

asset_url et asset_file sont mutuellement exclusifs : vous ne devez inclure que l’un des deux dans votre requête API.
Noms des fichiers téléchargés
Cette section explique comment l’endpoint attribue des noms aux fichiers téléchargés selon que vous incluez ou non le paramètre name.
Téléchargements de fichiers individuels
| Scénario | Résultat |
|---|---|
name fourni |
La valeur name est utilisée comme nom de la ressource dans la bibliothèque multimédia. |
name exclu |
Le nom de fichier d’origine provenant de l’URL ou du fichier téléchargé est utilisé. |
Téléchargements de fichiers ZIP
| Scénario | Résultat |
|---|---|
name fourni |
La valeur name est utilisée comme préfixe, suivie d’un numéro incrémentiel ajouté en suffixe (par exemple, « Mon fichier 1 », « Mon fichier 2 », « Mon fichier 3 »). |
name exclu |
Chaque fichier conserve le nom d’origine qu’il avait dans le fichier ZIP. |
Exemple de requête
Cette section présente deux exemples de requêtes curl : l’une pour ajouter une ressource à partir d’une URL, l’autre à partir de données de fichier binaire.
Cette requête montre comment ajouter une ressource à la bibliothèque multimédia à l’aide d’un asset_url.
curl -X POST --location 'https://rest.iad-01.braze.com/media_library/create' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--header 'Content-Type: application/json' \
--data '{"asset_url": "https://cdn.example.com/assets/cat.jpg", "name": "Cat Graphic"}'
Cette requête montre comment ajouter une ressource à la bibliothèque multimédia à l’aide d’un asset_file.
curl -X POST --location 'https://rest.iad-01.braze.com/media_library/create' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--header 'Content-Type: application/json' \
--data '{"asset_file":<BINARY FILE DATA>, "name":"Cat Graphic"}'
Réponses d’erreur
Cette section répertorie les erreurs possibles, ainsi que les messages et descriptions correspondants.
Erreurs de validation
Les erreurs de validation renvoient une structure semblable à celle-ci :
{
"message": (String) Human-readable error description
}
Ce tableau répertorie les erreurs de validation possibles.
| Statut HTTP | Message | Description |
|---|---|---|
| 400 | “Either asset_url or asset_file must be provided.” | Aucun paramètre de ressource n’a été fourni dans la requête. |
| 400 | “Both asset_url and asset_file cannot be provided. Please provide only one.” | Les deux paramètres de ressource ont été fournis ; un seul est autorisé. |
| 403 | “Media Library Public APIs are not enabled for this company.” | La fonctionnalité de bibliothèque multimédia n’est pas activée pour cet espace de travail. |
Erreurs de traitement
Les erreurs de traitement renvoient une réponse différente, avec des codes d’erreur :
{
"message": (String) Human-readable error description,
"error_code": (String) error code,
"meta": { }
}
Ce tableau répertorie les erreurs de traitement possibles.
| Code d’erreur | Statut HTTP | Description |
|---|---|---|
UNSUPPORTED_FILE_TYPE |
400 | Le type de fichier téléchargé n’est pas pris en charge. Consultez Types de fichiers pris en charge. L’objet meta contient le file_type qui a été rejeté. |
ASSET_SIZE_EXCEEDS_LIMIT |
400 | Le fichier dépasse la taille maximale autorisée de 5 Mo. |
MEDIA_LIBRARY_LIMIT_REACHED |
400 | L’espace de travail a atteint son nombre maximal de ressources (200 par défaut pour les entreprises en essai gratuit, illimité dans les autres cas). L’objet meta contient la limit actuelle. |
ASSET_UPLOAD_FAILED |
400 | Le téléchargement de la ressource a échoué en raison de problèmes de traitement. |
CORRUPT_FILE |
400 | Le fichier image est endommagé ou n’a pas pu être décodé. L’objet meta contient le file_name. |
INVALID_ASSET_URL |
400 | La valeur asset_url est mal formée ou n’est pas une URL HTTP ou HTTPS. L’objet meta contient asset_url. |
FAILED_TO_DOWNLOAD_ASSET |
400 | Braze n’a pas pu télécharger le fichier situé à l’adresse asset_url (par exemple, l’hôte n’a pas pu être résolu, la connexion a échoué ou le serveur distant a renvoyé une erreur). L’objet meta contient asset_url et original_error. |
ZIP_UPLOAD_ERROR |
400 | Le fichier ZIP est endommagé ou n’a pas pu être ouvert. L’objet meta contient le message original_error. |
ZIP_FILE_TOO_LARGE |
400 | La taille totale non compressée du fichier ZIP dépasse la limite de 50 Mo. L’objet meta contient le zip_file_name et le zip_file_size. |
ZIP_TOO_MANY_ENTRIES |
400 | Le fichier ZIP contient trop de fichiers. Le nombre d’entrées autorisées dans un fichier ZIP est limité. L’objet meta contient max_entries. |
ZIPPED_ENTITY_HAS_NO_NAME |
400 | Une entrée de fichier dans le ZIP n’a pas de nom. Assurez-vous que le fichier ZIP n’est pas endommagé et attribuez un nom à toute entrée de fichier qui n’en a pas. |
ZIPPED_ENTITY_CANNOT_HAVE_NESTED_DIRECTORY |
400 | Le fichier ZIP contient des répertoires imbriqués, qui ne sont pas pris en charge. Tous les fichiers doivent se trouver à la racine du ZIP. |
GENERIC_ERROR |
500 | Une erreur inattendue s’est produite pendant le téléchargement. L’objet meta contient le message original_error pour faciliter le débogage. Réessayez ou contactez l’assistance. |
Réponse
Cet endpoint peut renvoyer cinq codes de statut : 200, 400, 403, 429 et 500.
Le JSON suivant présente la structure attendue de la réponse.
{
"new_assets": [
{
"name": (String) the name of the asset,
"size": (Integer) the byte size of the asset,
"url": (String) the URL to access the asset,
"ext": (String) the file extension (e.g., "png", "jpg", "gif")
}
],
"errors": [
{
"name": (String) the name of the asset,
"size": (Integer) the byte size of the asset,
"ext": (String) the file extension (e.g., "png", "jpg", "gif"),
"error": (String) the error that occurred
}
],
"dashboard_url": (String) the URL to view this asset in the Braze dashboard
}