Vai al contenuto
Wbiztool

API file multimediali

API Elenca i file multimediali

Ottieni i file della libreria multimediale del tuo spazio di lavoro con i relativi URL di download, dal più recente. Filtra per tipo o cerca per nome per trovare un file caricato in precedenza e riutilizzarne l'URL in un messaggio.

GEThttps://wbiztool.com/api/v1/media/list/

Corpo: Query string, oppure un corpo JSON con POST

L'elenco include i file caricati con l'API Carica file multimediali e dalla pagina Directory Media. I file eliminati non sono inclusi.

Esempio rapido#

curl -G https://wbiztool.com/api/v1/media/list/ \
  --data-urlencode client_id=12345 \
  --data-urlencode api_key=YOUR_API_KEY \
  --data-urlencode file_type=image \
  --data-urlencode page=1 \
  --data-urlencode limit=20

Sostituisci 12345 e YOUR_API_KEY con i tuoi valori. Consulta Autenticazione per sapere dove trovarli.

Parametri della richiesta#

Invia i parametri nella query string di una richiesta GET, oppure come corpo JSON in una richiesta POST con Content-Type: application/json. Non combinare i due metodi: se client_id è nella query string, il corpo JSON viene ignorato. Anche una POST con dati di un modulo funziona per client_id, api_key, file_type e search, ma page e limit vengono ignorati nei campi del modulo; inviali nella query string o nel JSON.

Autenticazione

client_idintegerobbligatorio

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

api_keystringobbligatorio

La tua chiave API, dalla stessa pagina.

Filtri e paginazione

pageintegerfacoltativo

Numero di pagina, a partire da 1 (predefinito). I valori inferiori a 1 vengono trattati come 1.

limitintegerfacoltativo

File per pagina, da 1 a 100. Valore predefinito 20. I valori superiori a 100 vengono trattati come 100 e quelli inferiori a 1 come 20.

file_typestringfacoltativo

image per le sole immagini, oppure file per tutto il resto. Qualsiasi altro valore viene ignorato.

searchstringfacoltativo

Restituisce solo i file il cui nome originale o nome di salvataggio contiene questo testo. Non distingue tra maiuscole e minuscole.

POST con un corpo JSONcURL
curl -X POST https://wbiztool.com/api/v1/media/list/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "search": "invoice",
    "page": 1,
    "limit": 50
  }'

Risposta#

{
  "status": 1,
  "message": "Media files retrieved successfully",
  "data": {
    "total_count": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "media_files": [
      {
        "id": 5123,
        "file_name": "media_12345_17895806123456.jpg",
        "original_file_name": "diwali-sale.jpg",
        "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895806123456.jpg",
        "file_type": "image",
        "file_size": 524288,
        "file_size_display": "512.0 KB",
        "mime_type": "image/jpeg",
        "is_image": true,
        "file_extension": "jpg",
        "created_at": "2026-09-16T10:23:52.106447+00:00",
        "uploaded_by": "[email protected]"
      }
    ]
  }
}
CampoTipoDescrizione
statusinteger1 in caso di successo, 0 se la richiesta non è riuscita.
messagestringMedia files retrieved successfully, altrimenti l'errore.
data.total_countintegerFile che corrispondono ai tuoi filtri, su tutte le pagine.
data.pageintegerLa pagina restituita.
data.limitintegerLa dimensione della pagina utilizzata, dopo l'adeguamento all'intervallo da 1 a 100.
data.total_pagesintegerNumero di pagine. 0 quando non ci sono file.
data.has_nextbooleantrue se c'è una pagina successiva a questa.
data.has_previousbooleantrue se page è maggiore di 1.
data.media_filesarrayI file di questa pagina, dal più recente. Vuoto se la pagina è oltre la fine.

Campi del file multimediale#

CampoTipoDescrizione
idintegerID del file multimediale. Usalo con Ottieni file multimediale.
file_namestringNome con cui è salvato il file.
original_file_namestringIl nome che aveva il file quando è stato caricato.
file_urlstringURL di download diretto. Usalo come img_url o file_url durante l'invio.
file_typestringimage o file.
file_sizeintegerDimensione in byte.
file_size_displaystringDimensione leggibile con un decimale, ad esempio 512.0 KB.
mime_typestringTipo MIME, ad esempio image/jpeg.
is_imagebooleantrue quando file_type è image.
file_extensionstringEstensione in minuscolo di original_file_name, senza il punto.
created_atstringOrario del caricamento, in formato ISO 8601 in UTC con l'offset +00:00.
uploaded_bystring or nullNome utente di accesso (di solito l'indirizzo email) del membro del team che ha caricato il file.

Errori#

Anche gli errori restituiscono HTTP 200, con status impostato su 0:

{ "status": 0, "message": "Invalid API key" }
MessaggioCome risolvere
client_id is requiredAggiungi client_id. Se invii JSON, verifica che il corpo sia JSON valido (un errore di parsing viene segnalato con questo messaggio).
api_key is requiredAggiungi api_key.
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.
Error retrieving media files: …Di solito page o limit nella query string o nei campi del form non è un numero intero. In un corpo JSON non viene restituito alcun errore: se page non è un numero intero, page, limit, file_type e search vengono tutti ignorati, quindi ottieni la pagina 1 con 20 file e nessun filtro. Se solo limit non lo è, vengono ignorati limit, file_type e search.

Leggere tutte le pagine#

Continua a richiedere la pagina successiva finché data.has_next è true.

Recupera tutti i file multimediali
import requests

files, page = [], 1

while True:
    result = requests.get(
        "https://wbiztool.com/api/v1/media/list/",
        params={"client_id": 12345, "api_key": "YOUR_API_KEY", "page": page, "limit": 100},
        timeout=60,
    ).json()
    if result["status"] != 1:
        raise RuntimeError(result["message"])

    files += result["data"]["media_files"]
    if not result["data"]["has_next"]:
        break
    page += 1

print(len(files), "files")

Suggerimenti#

  • Usa il parametro di invio corretto: quando is_image è true, invia l'URL come img_url con msg_type 1; altrimenti come file_url con msg_type 2. Vedi Invia messaggio.
  • Tieni la chiave API fuori dai log: le query string vengono spesso registrate da proxy e server. Se per te è importante, usa invece POST con un corpo JSON.