API file multimediali
API Carica file multimediali
Carica un'immagine, un documento, un file audio o un video nella Directory media del tuo spazio di lavoro e ricevi in cambio un URL di download. Passa quell'URL a Invia messaggio oppure a Crea promemoria come img_url, quando non hai un tuo hosting per i file.
https://wbiztool.com/api/v1/media/upload/Corpo: multipart/form-data
Il file viene salvato subito e la risposta include il suo file_url. I file caricati compaiono anche nella pagina Directory media della tua dashboard.
Esempio rapido#
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');
}Sostituisci 12345 e YOUR_API_KEY con i tuoi valori. Consulta Autenticazione per sapere dove trovarli.
Parametri della richiesta#
Invia la richiesta come multipart/form-data. Questo endpoint non legge né i corpi JSON né i parametri nella query string.
client_idintegerobbligatorioIl tuo ID Client API, da Impostazioni → Chiavi API.
api_keystringobbligatorioLa tua chiave API, dalla stessa pagina.
media_filefileobbligatorioIl file da caricare, fino a 64 MB, e deve rientrare nello spazio di archiviazione per i media dello spazio di lavoro. Il tipo viene determinato dall'estensione del nome del file, quindi il nome deve terminare con una delle estensioni supportate.
Tipi di file supportati#
| Categoria | Estensioni |
|---|---|
| Immagini | .jpg, .jpeg, .png, .gif, .webp, .bmp |
| Documenti | .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv |
| Audio | .mp3, .m4a, .wav, .ogg, .aac |
| Video | .mp4, .mov, .avi |
| Archivi | .zip, .rar |
Le immagini vengono salvate con file_type impostato su image; tutto il resto è file.
Spazio di archiviazione per spazio di lavoro#
Tutti i file nella Directory media di uno spazio di lavoro condividono un unico limite di spazio, stabilito dal piano dello spazio di lavoro. Contano sia i file caricati con questa API sia quelli caricati nella pagina Directory media, ed eliminare un file libera il suo spazio.
| Piano | Spazio per i media |
|---|---|
| Prova gratuita | 250 MB |
| Lite | 1 GB |
| Standard | 2 GB |
| Advanced | 5 GB |
| Enterprise | 10 GB |
| AppSumo Plan 1 e Plan 2 | 1 GB |
| AppSumo Plan 3 | 2 GB |
| AppSumo Plan 4 | 3 GB |
| AppSumo Plan 5 | 5 GB |
I piani più vecchi, e uno spazio di lavoro senza un piano attivo, hanno 1 GB. Un caricamento che non ci sta viene rifiutato con Storage full: … (vedi Errori). Uno spazio di lavoro che ha già superato il suo limite conserva i suoi file, ma non può aggiungerne di nuovi finché non ha spazio per loro.
Risposta#
Una richiesta riuscita restituisce 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"
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status | integer | 1 se il file è stato caricato, 0 se la richiesta non è riuscita. |
message | string | File uploaded successfully, altrimenti l'errore. |
data.id | integer | ID del file multimediale. Usalo con Ottieni file multimediale. |
data.file_name | string | Nome con cui viene salvato il file, generato da WbizTool: media_, l'ID del tuo spazio di lavoro, l'orario del caricamento e una parte casuale, con l'estensione del file. |
data.original_file_name | string | Il nome del file che hai caricato. |
data.file_url | string | URL di download diretto. Usalo come img_url o file_url durante l'invio. È pubblico e non scade, ma smette di funzionare quando il file viene eliminato. Può trovarsi su media.wbiztool.com (la nostra CDN) o su wbiztool-static.s3.ap-southeast-1.amazonaws.com; entrambi servono lo stesso file, quindi salvalo così com'è e non costruire tu questi URL. |
data.file_type | string | image o file. |
data.file_size | integer | Dimensione in byte. |
data.file_size_display | string | Dimensione leggibile con un decimale, ad esempio 242.5 KB. |
data.mime_type | string | Tipo MIME ricavato dall'estensione, ad esempio application/pdf. |
data.is_image | boolean | true quando file_type è image. |
data.file_extension | string | Estensione in minuscolo di original_file_name, senza il punto. |
data.created_at | string | Orario del caricamento, in formato ISO 8601 in UTC con l'offset +00:00. |
Errori#
Anche gli errori restituiscono HTTP 200, con status impostato su 0:
{ "status": 0, "message": "File is too large. Maximum size is 64MB. Your file: 71.3MB" }
| Messaggio | Come risolvere |
|---|---|
Only POST method is supported | Invia una richiesta POST. |
client_id is required | Aggiungi client_id come campo del modulo. Verifica che il corpo sia multipart/form-data e non JSON. |
api_key is required | Aggiungi api_key come campo del modulo. |
media_file is required | Invia il file in un campo chiamato media_file. |
client_id must be a valid integer | Invia client_id come numero. |
Invalid API key | Verifica che la chiave esista e non sia stata eliminata o disattivata. |
Invalid client_id for this API key | La chiave appartiene a un altro client_id. |
File is too large. Maximum size is 64MB. Your file: …MB | Carica un file di 64 MB o meno. |
File type not supported. Type detected: … | Usa una delle estensioni supportate. |
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. | Il file non rientra nello spazio di archiviazione per i media dello spazio di lavoro. Elimina i file che non ti servono più nella pagina Directory media, oppure contattaci per avere più spazio. |
Error uploading file: … | Non è stato possibile completare il caricamento. Riprova. Ricevi questo errore anche se la chiave API non è collegata a uno spazio di lavoro; crea una nuova chiave nello spazio di lavoro che vuoi usare. |
Carica e invia#
Carica il file, poi passa file_url a Invia messaggio: come img_url con msg_type 1 per le immagini, oppure come file_url con msg_type 2 per gli altri file.
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());Ogni tipo di file accettato da questa API mantiene la sua estensione quando viene inviato con msg_type 2, ad esempio brochure.doc o catalogue.zip. L'audio WAV e OGG arriva come documento anziché come audio riproducibile e, inviato come immagine (msg_type 1), non riesce con File type not supported. MP3, M4A e AAC arrivano come audio che si riproduce nella chat, con il testo come messaggio separato. Vedi Invio di immagini e file. Il nome viene inviato in minuscolo (Invoice-4821.PDF arriva come invoice-4821.pdf).
Le immagini inviate con msg_type 1 devono essere di 16 MB o meno. Le immagini più grandi si caricano senza problemi qui, ma l'invio non riesce con File exceeds WhatsApp size limit (16MB max). Comprimile prima, oppure inviale come file con msg_type 2.
Suggerimenti#
- Riutilizza i caricamenti. Salva l'
ido ilfile_urle invia lo stesso file più volte invece di caricarlo di nuovo. - Mantieni significativo il nome originale.
original_file_nameè ciò che vedi nella dashboard ed è un buon valore perfile_namedurante l'invio. - Trova i caricamenti precedenti con Elenca file multimediali.
