Vai al contenuto
WbizTool

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.

POSThttps://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.pdf

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_idintegerobbligatorio

Il tuo ID Client API, da Impostazioni → Chiavi API.

api_keystringobbligatorio

La tua chiave API, dalla stessa pagina.

media_filefileobbligatorio

Il 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#

CategoriaEstensioni
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.

PianoSpazio per i media
Prova gratuita250 MB
Lite1 GB
Standard2 GB
Advanced5 GB
Enterprise10 GB
AppSumo Plan 1 e Plan 21 GB
AppSumo Plan 32 GB
AppSumo Plan 43 GB
AppSumo Plan 55 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"
  }
}
CampoTipoDescrizione
statusinteger1 se il file è stato caricato, 0 se la richiesta non è riuscita.
messagestringFile uploaded successfully, altrimenti l'errore.
data.idintegerID del file multimediale. Usalo con Ottieni file multimediale.
data.file_namestringNome 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_namestringIl nome del file che hai caricato.
data.file_urlstringURL 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_typestringimage o file.
data.file_sizeintegerDimensione in byte.
data.file_size_displaystringDimensione leggibile con un decimale, ad esempio 242.5 KB.
data.mime_typestringTipo MIME ricavato dall'estensione, ad esempio application/pdf.
data.is_imagebooleantrue quando file_type è image.
data.file_extensionstringEstensione in minuscolo di original_file_name, senza il punto.
data.created_atstringOrario 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" }
MessaggioCome risolvere
Only POST method is supportedInvia una richiesta POST.
client_id is requiredAggiungi client_id come campo del modulo. Verifica che il corpo sia multipart/form-data e non JSON.
api_key is requiredAggiungi api_key come campo del modulo.
media_file is requiredInvia il file in un campo chiamato media_file.
client_id must be a valid integerInvia client_id come numero.
Invalid API keyVerifica che la chiave esista e non sia stata eliminata o disattivata.
Invalid client_id for this API keyLa chiave appartiene a un altro client_id.
File is too large. Maximum size is 64MB. Your file: …MBCarica 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.

Carica un PDF e invialo
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)

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'id o il file_url e 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 per file_name durante l'invio.
  • Trova i caricamenti precedenti con Elenca file multimediali.