Conclusión primero: SmartSlim Server proporciona una API RESTful con 4 interfaces principales — compresión por subida, compresión por lotes, consulta de estado y notificación por callback — soportando dos métodos de autenticación: API Key y Bearer Token. La compresión por subida de un PDF de 100 MB tarda unos 8 segundos, y la compresión por lotes de 100 archivos unos 12 segundos. La limitación por defecto es de 60 solicitudes por minuto, ampliable a 300 en la versión Enterprise. Este artículo presenta las tablas de parámetros de las 4 interfaces, ejemplos en Python/JavaScript/curl y un plan de manejo de errores. A continuación, empezando por el resumen de la API, se explica cada interfaz en detalle.
Si necesitas integración local mediante SDK en lugar de llamada HTTP API, te recomendamos leer primero la guía de integración del SDK de compresión: llamada multilenguaje Python/Java/C#.
1. Resumen de la interfaz API
La API RESTful de SmartSlim Server está desarrollada sobre el framework FastAPI. Todas las interfaces devuelven datos en formato JSON y soportan subida de archivos multipart/form-data. La ruta base de la API es /api/v1/ y todas las solicitudes deben llevar información de autenticación.
| Interfaz | Método | Ruta | Función | Síncrono/Asíncrono |
|---|---|---|---|---|
| Compresión por subida | POST | /api/v1/compress | Subir archivo individual y comprimir | Síncrono (menos de 50 MB)/Asíncrono |
| Compresión por lotes | POST | /api/v1/compress/batch | Subida por lotes y compresión de múltiples archivos | Asíncrono |
| Consulta de estado | GET | /api/v1/status/{task_id} | Consultar estado de la tarea de compresión | Síncrono |
| Notificación por callback | POST | URL de callback del cliente | Notificación proactiva al completar la compresión | Push asíncrono |
Existen dos métodos de autenticación: API Key para llamadas desde el servidor, y Bearer Token para llamadas desde el frontend. La siguiente tabla compara las características de ambos métodos.
| Método de autenticación | Cabecera | Validez | Escenario aplicable | Seguridad |
|---|---|---|---|---|
| API Key | X-API-Key: your-key | Permanente (revocable) | Llamada desde servidor | Media (requiere HTTPS) |
| Bearer Token | Authorization: Bearer token | 24 horas | Llamada desde frontend | Alta (validez corta) |
2. Detalle de los parámetros de cada interfaz
1. Interfaz de compresión por subida
La interfaz de compresión por subida recibe un archivo individual y devuelve el resultado de la compresión. Para archivos de menos de 50 MB devuelve síncronamente el enlace de descarga; para más de 50 MB devuelve asíncronamente un ID de tarea.
| Parámetro | Tipo | Obligatorio | Valor predeterminado | Descripción |
|---|---|---|---|---|
| file | multipart/file | Sí | - | Archivo a comprimir |
| format | string | No | Detección automática | Tipo de archivo (pdf/image/ofd) |
| level | string | No | medium | Nivel de compresión (low/medium/high/ultra) |
| quality | integer | No | 75 | Factor de calidad (1-100) |
| callback_url | string | No | - | URL de callback asíncrono |
2. Interfaz de compresión por lotes
La interfaz de compresión por lotes recibe múltiples archivos, los procesa asíncronamente y devuelve un ID de tarea por lotes. Soporta la especificación del número de concurrencia, con un máximo limitado por la licencia.
| Parámetro | Tipo | Obligatorio | Valor predeterminado | Descripción |
|---|---|---|---|---|
| files | multipart/file[] | Sí | - | Lista de archivos a comprimir (máx. 100) |
| level | string | No | medium | Nivel de compresión |
| quality | integer | No | 75 | Factor de calidad |
| workers | integer | No | 4 | Número de concurrencias (1-16) |
| callback_url | string | No | - | URL de callback al completar |
3. Interfaz de consulta de estado
La interfaz de consulta de estado permite consultar el estado y resultado actuales de una tarea de compresión asíncrona mediante el ID de tarea.
| Campo de retorno | Tipo | Descripción |
|---|---|---|
| task_id | string | Identificador único de tarea |
| status | string | Estado (pending/processing/completed/failed) |
| progress | integer | Porcentaje de progreso (0-100) |
| download_url | string | Enlace de descarga del resultado (al completar) |
| original_size | integer | Tamaño original del archivo (bytes) |
| compressed_size | integer | Tamaño comprimido (bytes) |
| error | string | Mensaje de error (en caso de fallo) |
3. Ejemplos de llamada en tres lenguajes
A continuación se presentan ejemplos de llamada en curl, Python y JavaScript, todos con el ejemplo de compresión por subida de un único archivo PDF.
| Lenguaje | Código central | Descripción |
|---|---|---|
| curl | curl -X POST -H "X-API-Key: key" -F "file=@doc.pdf" -F "level=medium" http://localhost:8000/api/v1/compress | Llamada por línea de comandos |
| Python | requests.post(url, headers={"X-API-Key":key}, files={"file":open("doc.pdf","rb")}, data={"level":"medium"}) | Biblioteca requests |
| JavaScript | fetch(url, {method:"POST", headers:{"X-API-Key":key}, body:formData}) | Fetch API |
4. Limitación de velocidad y manejo de errores
La API cuenta con un mecanismo completo de limitación de velocidad y manejo de errores. Comprender los códigos de estado HTTP y los códigos de error es esencial para escribir código de llamada robusto.
| Código HTTP | Código de error | Significado | Recomendación |
|---|---|---|---|
| 200 | - | Éxito | Analizar datos de respuesta |
| 400 | INVALID_PARAM | Parámetro inválido | Verificar parámetros de solicitud |
| 401 | UNAUTHORIZED | Fallo de autenticación | Verificar API Key/Token |
| 413 | FILE_TOO_LARGE | Archivo demasiado grande | Usar subida por bloques |
| 429 | RATE_LIMITED | Demasiadas solicitudes | Reintentar con backoff exponencial |
| 500 | INTERNAL_ERROR | Error del servidor | Reintentar o contactar soporte |
| 503 | SERVICE_UNAVAILABLE | Servicio no disponible | Esperar y reintentar |
Detalles de la limitación: por defecto 60 solicitudes por minuto y 10 concurrencias por segundo; la versión Enterprise eleva a 300 por minuto y 30 por segundo. Al superarse se devuelve 429, con cabeceras X-RateLimit-Remaining (solicitudes restantes) y X-RateLimit-Reset (timestamp de reinicio). Se recomienda implementar backoff exponencial: al recibir 429, esperar 1 segundo y reintentar; si falla, 2 segundos; si falla de nuevo, 4 segundos, con un máximo de 3 reintentos.
| Tipo de archivo | Tamaño original | Tamaño comprimido | Tiempo de compresión | Tasa de compresión |
|---|---|---|---|---|
| PDF (escaneado) | 80MB | 8.2MB | 6.5s | 89.8% |
| PDF (electrónico) | 15MB | 3.1MB | 1.2s | 79.3% |
| Imagen JPEG | 12MB | 2.8MB | 0.8s | 76.7% |
| Imagen PNG | 25MB | 6.5MB | 1.5s | 74.0% |
| Documento OFD | 30MB | 5.2MB | 2.0s | 82.7% |
Si necesitas conocer los principios de diseño subyacentes de la cola de tareas de compresión, puedes consultar el diseño de la cola de tareas de compresión. Si necesitas desplegar el servicio API mediante Docker, puedes consultar la guía de despliegue de servicio de compresión con Docker.
5. Preguntas frecuentes (FAQ)
Q1: ¿Cómo autenticar la llamada a la API de compresión?
La API de compresión de SmartSlim Server soporta dos métodos de autenticación: API Key (pasar la clave en la cabecera X-API-Key, adecuado para llamadas desde el servidor) y Bearer Token (pasar el JWT Token en la cabecera Authorization, adecuado para llamadas desde el frontend). La API Key es permanente pero se puede revocar en cualquier momento, el Token tiene una validez de 24 horas y necesita refrescarse periódicamente. Para entornos de producción se recomienda el método API Key, por ser sencillo y fiable.
Q2: ¿Qué formatos de archivo soporta la API de compresión?
La API de SmartSlim Server soporta PDF, imágenes (jpg/jpeg/tif) y formato OFD, con un límite de archivo de 1 GB. La API de SmartSlim Network soporta las 10 categorías y más de 40 formatos (incluyendo vídeo, audio, documentos Office, etc.), con un límite de archivo de 10 GB. Al llamar, se especifica el tipo de archivo mediante el parámetro format; si no se pasa, se detecta automáticamente. Nota: la versión de servidor solo soporta PDF/imágenes/OFD; para todos los formatos se necesita la versión de red.
Q3: ¿La API de compresión tiene límites de frecuencia de llamada?
Existe una estrategia de limitación de velocidad para proteger la estabilidad del servicio. Limitación por defecto: 60 solicitudes por minuto, 10 concurrencias por segundo. Al superarse se devuelve el código 429, con cabeceras X-RateLimit-Remaining y X-RateLimit-Reset. La versión Enterprise puede elevarse a 300 solicitudes por minuto y 30 concurrencias por segundo. Se recomienda que el cliente implemente un mecanismo de reintentos con backoff exponencial: al recibir 429, esperar 1-2-4 segundos con incrementos.
Q4: ¿Cómo maneja la API de compresión los archivos grandes?
Para archivos grandes (más de 50 MB) se recomienda usar la interfaz de subida por bloques, dividiendo el archivo en bloques de 5 MB; una vez subidos todos, se notifica la fusión y compresión. Al completarse, el resultado se obtiene mediante notificación por callback o consultando el estado. La compresión de archivos grandes es asíncrona y no bloquea la llamada a la API. Un PDF de 100 MB tarda unos 8 segundos y un vídeo de 1 GB unos 90 segundos; al completarse se genera automáticamente un enlace de descarga.
Resumen
La API RESTful de SmartSlim Server ofrece 4 interfaces principales — compresión por subida, compresión por lotes, consulta de estado y notificación por callback — cubriendo todos los escenarios desde archivos individuales hasta procesamiento por lotes. Dos métodos de autenticación: API Key para servidor, Bearer Token para frontend. Estrategia de limitación clara: 60 por minuto por defecto, 300 en Enterprise, con código 429 y backoff exponencial. Un PDF escaneado de 80 MB se comprime a 8,2 MB en solo 6,5 segundos, con una tasa de compresión del 89,8%.
Recuerda tres puntos: primero, para archivos de menos de 50 MB el resultado se devuelve síncronamente, para más de 50 MB se usa ID de tarea asíncrono; segundo, ante el código 429 implementa backoff exponencial, no insistas; tercero, para archivos grandes usa la interfaz de subida por bloques, con bloques de 5 MB. Si eliges bien la interfaz y los parámetros, la llamada a la API de compresión es muy sencilla. Si prefieres la integración local del SDK en lugar de la llamada HTTP, puedes consultar la guía de integración del SDK de compresión.
Artículos relacionados
¿Necesita comprimir archivos? Pruebe SmartSlim
Construido sobre un motor de compresión Rust propio, compatible con 10 categorías y más de 40 formatos, incluyendo PDF, imágenes, vídeo, Office y OFD, con compresión local que mantiene sus datos en sus instalaciones.