API des médias
API de téléversement de médias
Téléversez une image, un document, un fichier audio ou une vidéo dans le Répertoire média de votre espace de travail et obtenez en retour une URL de téléchargement. Transmettez cette URL à Envoyer un message ou à Créer un rappel comme img_url, lorsque vous ne disposez pas de votre propre hébergement de fichiers.
https://wbiztool.com/api/v1/media/upload/Corps: multipart/form-data
Le fichier est stocké immédiatement et la réponse inclut son file_url. Les fichiers téléversés apparaissent aussi sur la page Répertoire média de votre tableau de bord.
Exemple rapide#
curl -X POST https://wbiztool.com/api/v1/media/upload/ \
-F client_id=12345 \
-F api_key=YOUR_API_KEY \
-F media_file=@./invoice-4821.pdfimport requests
with open("invoice-4821.pdf", "rb") as f:
response = requests.post(
"https://wbiztool.com/api/v1/media/upload/",
data={"client_id": 12345, "api_key": "YOUR_API_KEY"},
files={"media_file": f},
timeout=120,
)
try:
result = response.json()
except ValueError:
# A proxy can reject a very large upload with an HTML page before it reaches WbizTool.
raise SystemExit(f"HTTP {response.status_code}: not JSON. Check the file size.")
if result["status"] == 1:
print("Uploaded:", result["data"]["file_url"])
else:
print("Failed:", result["message"])// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("media_file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
// Don't set Content-Type yourself; fetch adds the multipart boundary.
const response = await fetch("https://wbiztool.com/api/v1/media/upload/", { method: "POST", body: form });
const result = await response.json();
if (result.status === 1) {
console.log("Uploaded:", result.data.file_url);
} else {
console.error("Failed:", result.message);
}<?php
$ch = curl_init('https://wbiztool.com/api/v1/media/upload/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
// An array body (not json_encode) makes cURL send multipart/form-data.
CURLOPT_POSTFIELDS => [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'media_file' => new CURLFile('/path/to/invoice-4821.pdf', 'application/pdf', 'invoice-4821.pdf'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
echo 'Uploaded: ' . $result['data']['file_url'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}Remplacez 12345 et YOUR_API_KEY par vos propres valeurs. Consultez Authentification pour savoir où les trouver.
Paramètres de la requête#
Envoyez la requête en multipart/form-data. Cet endpoint ne lit ni les corps JSON ni les paramètres de la chaîne de requête.
client_idintegerobligatoireVotre ID client API, dans Paramètres → Clés API.
api_keystringobligatoireVotre clé API, sur cette même page.
media_filefileobligatoireLe fichier à téléverser, jusqu'à 64 Mo, et il doit tenir dans le stockage des médias de l'espace de travail. Son type est déterminé par l'extension du nom de fichier : le nom doit donc se terminer par l'une des extensions prises en charge.
Types de fichiers pris en charge#
| Catégorie | Extensions |
|---|---|
| Images | .jpg, .jpeg, .png, .gif, .webp, .bmp |
| Documents | .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv |
| Audio | .mp3, .m4a, .wav, .ogg, .aac |
| Vidéo | .mp4, .mov, .avi |
| Archives | .zip, .rar |
Les images sont stockées avec file_type défini sur image ; tout le reste est défini sur file.
Stockage par espace de travail#
Tous les fichiers du Répertoire média d'un espace de travail partagent une même limite de stockage, fixée par le forfait de l'espace de travail. Les fichiers téléversés avec cette API et ceux importés sur la page Répertoire média comptent tous, et supprimer un fichier libère sa place.
| Forfait | Stockage des médias |
|---|---|
| Essai gratuit | 250 Mo |
| Lite | 1 Go |
| Standard | 2 Go |
| Advanced | 5 Go |
| Enterprise | 10 Go |
| AppSumo Plan 1 et Plan 2 | 1 Go |
| AppSumo Plan 3 | 2 Go |
| AppSumo Plan 4 | 3 Go |
| AppSumo Plan 5 | 5 Go |
Les anciens forfaits, et un espace de travail sans forfait actif, ont 1 Go. Un téléversement qui ne tient pas est refusé avec Storage full: … (voir Erreurs). Un espace de travail qui dépasse déjà sa limite garde ses fichiers, mais ne peut pas en ajouter de nouveaux tant qu'il n'a pas la place.
Réponse#
Une requête réussie renvoie le code HTTP 200 :
{
"status": 1,
"message": "File uploaded successfully",
"data": {
"id": 5122,
"file_name": "media_12345_17895804001234_3f9a1c7e.pdf",
"original_file_name": "invoice-4821.pdf",
"file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895804001234_3f9a1c7e.pdf",
"file_type": "file",
"file_size": 248312,
"file_size_display": "242.5 KB",
"mime_type": "application/pdf",
"is_image": false,
"file_extension": "pdf",
"created_at": "2026-09-16T10:20:31.512934+00:00"
}
}
| Champ | Type | Description |
|---|---|---|
status | integer | 1 si le fichier a été téléversé, 0 si la requête a échoué. |
message | string | File uploaded successfully, sinon l'erreur. |
data.id | integer | ID du fichier multimédia. Utilisez-le avec Obtenir un fichier multimédia. |
data.file_name | string | Nom sous lequel le fichier est stocké, généré par WbizTool : media_, l'ID de votre espace de travail, l'heure du téléversement et une partie aléatoire, avec l'extension du fichier. |
data.original_file_name | string | Le nom du fichier que vous avez téléversé. |
data.file_url | string | URL de téléchargement direct. Utilisez-la comme img_url ou file_url lors de l'envoi. Elle est publique et n'expire pas, mais cesse de fonctionner quand le fichier est supprimé. Elle peut être sur media.wbiztool.com (notre CDN) ou sur wbiztool-static.s3.ap-southeast-1.amazonaws.com ; les deux servent le même fichier : stockez-la telle quelle et ne construisez pas ces URL vous-même. |
data.file_type | string | image ou file. |
data.file_size | integer | Taille en octets. |
data.file_size_display | string | Taille lisible avec une décimale, par exemple 242.5 KB. |
data.mime_type | string | Type MIME déduit de l'extension, par exemple application/pdf. |
data.is_image | boolean | true lorsque file_type vaut image. |
data.file_extension | string | Extension de original_file_name en minuscules, sans le point. |
data.created_at | string | Date du téléversement, au format ISO 8601 en UTC avec un décalage +00:00. |
Erreurs#
Les erreurs renvoient aussi le code HTTP 200, avec status à 0 :
{ "status": 0, "message": "File is too large. Maximum size is 64MB. Your file: 71.3MB" }
| Message | Comment corriger |
|---|---|
Only POST method is supported | Envoyez une requête POST. |
client_id is required | Ajoutez client_id comme champ de formulaire. Vérifiez que le corps est en multipart/form-data et non en JSON. |
api_key is required | Ajoutez api_key comme champ de formulaire. |
media_file is required | Envoyez le fichier dans un champ nommé media_file. |
client_id must be a valid integer | Envoyez client_id sous forme de nombre. |
Invalid API key | Vérifiez que la clé existe et n'a pas été supprimée ni désactivée. |
Invalid client_id for this API key | La clé appartient à un autre client_id. |
File is too large. Maximum size is 64MB. Your file: …MB | Téléversez un fichier de 64 Mo maximum. |
File type not supported. Type detected: … | Utilisez l'une des extensions prises en charge. |
Storage full: this workspace uses … of its … of media storage, and this file is …. Delete files you no longer need in the Media directory, or contact us if you need more space. | Le fichier ne tient pas dans le stockage des médias de l'espace de travail. Supprimez les fichiers dont vous n'avez plus besoin sur la page Répertoire média, ou contactez-nous pour plus d'espace. |
Error uploading file: … | Le téléversement n'a pas pu aboutir. Réessayez. Vous obtenez aussi cette erreur si la clé API n'est liée à aucun espace de travail ; créez une nouvelle clé dans l'espace de travail que vous souhaitez utiliser. |
Téléverser puis envoyer#
Téléversez le fichier, puis transmettez file_url à Envoyer un message : comme img_url avec msg_type 1 pour les images, ou comme file_url avec msg_type 2 pour les autres fichiers.
import requests
BASE = "https://wbiztool.com/api/v1"
AUTH = {"client_id": 12345, "api_key": "YOUR_API_KEY"}
with open("invoice-4821.pdf", "rb") as f:
upload = requests.post(f"{BASE}/media/upload/", data=AUTH, files={"media_file": f}, timeout=120).json()
if upload["status"] != 1:
raise SystemExit("Upload failed: " + upload["message"])
media = upload["data"]
message = {
**AUTH,
"whatsapp_client": 678,
"country_code": "91",
"phone": "9876543210",
"msg": "Your invoice for order #4821 is attached.",
}
if media["is_image"]:
message.update(msg_type=1, img_url=media["file_url"])
else:
message.update(msg_type=2, file_url=media["file_url"], file_name=media["original_file_name"])
sent = requests.post(f"{BASE}/send_msg/", json=message, timeout=60).json()
print(sent)// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const BASE = "https://wbiztool.com/api/v1";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("media_file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
const upload = await (await fetch(`${BASE}/media/upload/`, { method: "POST", body: form })).json();
if (upload.status !== 1) throw new Error(`Upload failed: ${upload.message}`);
const media = upload.data;
const message = {
client_id: 12345,
api_key: "YOUR_API_KEY",
whatsapp_client: 678,
country_code: "91",
phone: "9876543210",
msg: "Your invoice for order #4821 is attached.",
...(media.is_image
? { msg_type: 1, img_url: media.file_url }
: { msg_type: 2, file_url: media.file_url, file_name: media.original_file_name }),
};
const sent = await fetch(`${BASE}/send_msg/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(message),
});
console.log(await sent.json());Tous les types de fichiers acceptés par cette API gardent leur extension quand ils sont envoyés avec msg_type 2, par exemple brochure.doc ou catalogue.zip. Les audios WAV et OGG arrivent comme documents et non comme audio lisible, et échouent avec File type not supported quand ils sont envoyés comme image (msg_type 1). Les MP3, M4A et AAC arrivent comme audio lisible dans la discussion, avec le texte dans un message séparé. Consultez Envoyer des images et des fichiers. Le nom est envoyé en minuscules (Invoice-4821.PDF arrive sous le nom invoice-4821.pdf).
Les images envoyées avec msg_type 1 doivent faire 16 Mo ou moins. Les images plus volumineuses se téléversent sans problème ici, mais leur envoi échoue avec File exceeds WhatsApp size limit (16MB max). Compressez-les d'abord, ou envoyez-les comme fichier avec msg_type 2.
Conseils#
- Réutilisez vos téléversements. Conservez l'
idou lefile_urlet envoyez le même fichier autant de fois que nécessaire au lieu de le téléverser à nouveau. - Gardez un nom d'origine explicite.
original_file_nameest le nom affiché dans le tableau de bord et une bonne valeur pourfile_namelors de l'envoi. - Retrouvez vos anciens téléversements avec Lister les médias.
