API de medios
API para listar archivos multimedia
Obtén los archivos de la biblioteca de medios de tu espacio de trabajo con sus URL de descarga, del más reciente al más antiguo. Filtra por tipo o busca por nombre para encontrar un archivo que subiste antes y reutilizar su URL en un mensaje.
https://wbiztool.com/api/v1/media/list/Cuerpo: Query string, o un cuerpo JSON con POST
La lista incluye los archivos subidos con la API de subida de medios y en la página Directorio de Medios. Los archivos eliminados no se incluyen.
Ejemplo rápido#
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=20import requests
response = requests.get(
"https://wbiztool.com/api/v1/media/list/",
params={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"file_type": "image",
"page": 1,
"limit": 20,
},
timeout=60,
)
result = response.json()
if result["status"] == 1:
data = result["data"]
print(f"Page {data['page']} of {data['total_pages']} ({data['total_count']} files)")
for media in data["media_files"]:
print(media["id"], media["original_file_name"], media["file_url"])
else:
print("Failed:", result["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const url = new URL("https://wbiztool.com/api/v1/media/list/");
url.search = new URLSearchParams({
client_id: "12345",
api_key: "YOUR_API_KEY",
file_type: "image",
page: "1",
limit: "20",
});
const response = await fetch(url);
const result = await response.json();
if (result.status === 1) {
const { data } = result;
console.log(`Page ${data.page} of ${data.total_pages} (${data.total_count} files)`);
for (const media of data.media_files) {
console.log(media.id, media.original_file_name, media.file_url);
}
} else {
console.error("Failed:", result.message);
}<?php
$query = http_build_query([
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'file_type' => 'image',
'page' => 1,
'limit' => 20,
]);
$ch = curl_init('https://wbiztool.com/api/v1/media/list/?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
foreach ($result['data']['media_files'] as $media) {
echo $media['id'] . ' ' . $media['original_file_name'] . ' ' . $media['file_url'] . "\n";
}
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}Sustituye 12345 y YOUR_API_KEY por tus propios valores. Consulta Autenticación para saber dónde encontrarlos.
Parámetros de la solicitud#
Envía los parámetros en la query string de una solicitud GET, o como cuerpo JSON en una solicitud POST con Content-Type: application/json. No mezcles las dos opciones: si client_id está en la query string, el cuerpo JSON se ignora. Un POST con campos de formulario también funciona para client_id, api_key, file_type y search, pero page y limit se ignoran en los campos de formulario; envíalos en la query string o en JSON.
Autenticación
client_idintegerobligatorioTu ID de cliente de la API, de Configuración → Claves API.
api_keystringobligatorioTu clave API, de esa misma página.
Filtros y paginación
pageintegeropcionalNúmero de página, empezando en
1(valor predeterminado). Los valores menores que 1 se tratan como1.limitintegeropcionalArchivos por página, de 1 a 100. Valor predeterminado:
20. Los valores mayores que 100 se tratan como100, y los menores que 1 como20.file_typestringopcionalimagesolo para imágenes, ofilepara todo lo demás. Cualquier otro valor se ignora.searchstringopcionalDevuelve solo los archivos cuyo nombre original o nombre guardado contiene este texto. No distingue mayúsculas de minúsculas.
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
}'Respuesta#
{
"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]"
}
]
}
}
| Campo | Tipo | Descripción |
|---|---|---|
status | integer | 1 si todo va bien, 0 si la solicitud falló. |
message | string | Media files retrieved successfully; en caso contrario, el error. |
data.total_count | integer | Archivos que coinciden con tus filtros, en todas las páginas. |
data.page | integer | La página devuelta. |
data.limit | integer | El tamaño de página utilizado, tras el ajuste al rango de 1 a 100. |
data.total_pages | integer | Número de páginas. 0 cuando no hay archivos. |
data.has_next | boolean | true si hay una página después de esta. |
data.has_previous | boolean | true si page es mayor que 1. |
data.media_files | array | Los archivos de esta página, del más reciente al más antiguo. Vacío si la página está más allá del final. |
Campos de cada archivo multimedia#
| Campo | Tipo | Descripción |
|---|---|---|
id | integer | ID del archivo multimedia. Úsalo con Obtener archivo multimedia. |
file_name | string | Nombre con el que se guarda el archivo. |
original_file_name | string | El nombre que tenía el archivo cuando se subió. |
file_url | string | URL de descarga directa. Úsala como img_url o file_url al enviar. |
file_type | string | image o file. |
file_size | integer | Tamaño en bytes. |
file_size_display | string | Tamaño legible con un decimal, por ejemplo 512.0 KB. |
mime_type | string | Tipo MIME, por ejemplo image/jpeg. |
is_image | boolean | true cuando file_type es image. |
file_extension | string | Extensión en minúsculas de original_file_name, sin el punto. |
created_at | string | Fecha y hora de subida, en ISO 8601 en UTC con un desfase +00:00. |
uploaded_by | string or null | Nombre de usuario de inicio de sesión (normalmente la dirección de correo electrónico) del miembro del equipo que subió el archivo. |
Errores#
Los errores también devuelven HTTP 200, con status con valor 0:
{ "status": 0, "message": "Invalid API key" }
| Mensaje | Cómo solucionarlo |
|---|---|
client_id is required | Añade client_id. Si envías JSON, comprueba que el cuerpo sea JSON válido (un error de análisis se notifica con este mensaje). |
api_key is required | Añade api_key. |
client_id must be a valid integer | Envía client_id como número. |
Invalid API key | Comprueba que la clave existe y que no se ha eliminado ni desactivado. |
Invalid client_id for this API key | La clave pertenece a otro client_id. |
Error retrieving media files: … | Normalmente page o limit no es un número entero en la query string o en los campos de formulario. En un cuerpo JSON no hay error: si page no es un número entero, se ignoran page, limit, file_type y search, así que obtienes la página 1 con 20 archivos y sin filtros. Si solo limit no lo es, se ignoran limit, file_type y search. |
Leer todas las páginas#
Sigue pidiendo la página siguiente mientras data.has_next sea true.
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")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const files = [];
let page = 1;
while (true) {
const url = new URL("https://wbiztool.com/api/v1/media/list/");
url.search = new URLSearchParams({ client_id: "12345", api_key: "YOUR_API_KEY", page: String(page), limit: "100" });
const result = await (await fetch(url)).json();
if (result.status !== 1) throw new Error(result.message);
files.push(...result.data.media_files);
if (!result.data.has_next) break;
page += 1;
}
console.log(files.length, "files");Consejos#
- Usa el parámetro de envío adecuado: cuando
is_imageestrue, envía la URL comoimg_urlconmsg_type1; si no, comofile_urlconmsg_type2. Consulta Enviar mensaje. - Mantén tu clave API fuera de los registros: los proxies y los servidores suelen registrar las query strings. Si eso te preocupa, usa
POSTcon un cuerpo JSON.
