Saltar al contenido
Wbiztool

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.

GEThttps://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=20

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_idintegerobligatorio

Tu ID de cliente de la API, de Configuración → Claves API.

api_keystringobligatorio

Tu clave API, de esa misma página.

Filtros y paginación

pageintegeropcional

Número de página, empezando en 1 (valor predeterminado). Los valores menores que 1 se tratan como 1.

limitintegeropcional

Archivos por página, de 1 a 100. Valor predeterminado: 20. Los valores mayores que 100 se tratan como 100, y los menores que 1 como 20.

file_typestringopcional

image solo para imágenes, o file para todo lo demás. Cualquier otro valor se ignora.

searchstringopcional

Devuelve solo los archivos cuyo nombre original o nombre guardado contiene este texto. No distingue mayúsculas de minúsculas.

POST con un cuerpo 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
  }'

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]"
      }
    ]
  }
}
CampoTipoDescripción
statusinteger1 si todo va bien, 0 si la solicitud falló.
messagestringMedia files retrieved successfully; en caso contrario, el error.
data.total_countintegerArchivos que coinciden con tus filtros, en todas las páginas.
data.pageintegerLa página devuelta.
data.limitintegerEl tamaño de página utilizado, tras el ajuste al rango de 1 a 100.
data.total_pagesintegerNúmero de páginas. 0 cuando no hay archivos.
data.has_nextbooleantrue si hay una página después de esta.
data.has_previousbooleantrue si page es mayor que 1.
data.media_filesarrayLos 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#

CampoTipoDescripción
idintegerID del archivo multimedia. Úsalo con Obtener archivo multimedia.
file_namestringNombre con el que se guarda el archivo.
original_file_namestringEl nombre que tenía el archivo cuando se subió.
file_urlstringURL de descarga directa. Úsala como img_url o file_url al enviar.
file_typestringimage o file.
file_sizeintegerTamaño en bytes.
file_size_displaystringTamaño legible con un decimal, por ejemplo 512.0 KB.
mime_typestringTipo MIME, por ejemplo image/jpeg.
is_imagebooleantrue cuando file_type es image.
file_extensionstringExtensión en minúsculas de original_file_name, sin el punto.
created_atstringFecha y hora de subida, en ISO 8601 en UTC con un desfase +00:00.
uploaded_bystring or nullNombre 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" }
MensajeCómo solucionarlo
client_id is requiredAñ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 requiredAñade api_key.
client_id must be a valid integerEnvía client_id como número.
Invalid API keyComprueba que la clave existe y que no se ha eliminado ni desactivado.
Invalid client_id for this API keyLa 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.

Obtener todos los archivos multimedia
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")

Consejos#

  • Usa el parámetro de envío adecuado: cuando is_image es true, envía la URL como img_url con msg_type 1; si no, como file_url con msg_type 2. 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 POST con un cuerpo JSON.