PiiBlur

'Cómo automatizar la redacción de PII con una API REST'

'PiiBlur Team'9 lectura mínima

Si su aplicación acepta fotografías cargadas por usuarios, imágenes de flotas, documentación de reclamos o cualquier otro medio visual, la redacción pertenece al proceso de carga. Rostros, matrículas, documentos, pantallas e insignias suelen aparecer en archivos que nunca estuvieron destinados a exponer datos personales.

Esta guía cubre la API REST PiiBlur: carga de medios, verificación del estado, descarga de resultados, configuración de webhooks y creación de una canalización por lotes. Todos los ejemplos utilizan cURL para permanecer independiente del idioma. Para obtener la referencia completa del punto final, consulte Documentación API. Para ver ejemplos más específicos, consulte las páginas API de desenfoque facial, API de desenfoque de matrícula, API de redacción de imágenes y API de redacción de vídeos.

Autenticación y URL base

Cada solicitud requiere un token de portador. Genere una clave API desde la sección API de su panel PiiBlur.

curl -X GET https://piiblur.com/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Una respuesta exitosa confirma su clave y devuelve el uso actual y los límites del plan. Todos los puntos finales se encuentran bajo https://piiblur.com/api/v1/.

Carga de medios para redacción de PII

Envíe una imagen o un vídeo con una solicitud POST de varias partes. Especifique al menos una categoría de PII para redactar.

curl -X POST https://piiblur.com/api/v1/media/redact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "categories[]=heads" \
  -F "categories[]=license_plates"

La respuesta devuelve un objeto de medios públicos con un estado queued:

{
    "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "status": "queued",
    "filename": "photo.jpg",
    "media_type": "image",
    "categories": ["heads", "license_plates"],
    "redaction_method": "blur",
    "file_size_bytes": 482391,
    "duration_seconds": null,
    "created_at": "2026-03-11T14:30:00+00:00",
    "processed_at": null,
    "failed_at": null
}

Especifique el método de redacción (blur o pixelation) por solicitud:

curl -X POST https://piiblur.com/api/v1/media/redact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "categories[]=heads" \
  -F "categories[]=documents" \
  -F "redaction_method=pixelation"

Las imágenes se procesan en segundos. El tiempo de procesamiento del video depende de la duración y la resolución.

Comprobar el estado del trabajo

Sondee el punto final de estado para verificar la finalización:

curl -X GET https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer YOUR_API_KEY"

Un trabajo completado devuelve un download_url:

{
    "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "status": "completed",
    "filename": "photo.jpg",
    "media_type": "image",
    "categories": ["heads", "license_plates"],
    "redaction_method": "blur",
    "file_size_bytes": 482391,
    "duration_seconds": null,
    "created_at": "2026-03-11T14:30:00+00:00",
    "processed_at": "2026-03-11T14:30:04+00:00",
    "failed_at": null,
    "download_url": "https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download"
}

El campo download_url aparece solo después de que se completa el procesamiento.

Descargando resultados redactados

Obtenga el archivo redactado con una solicitud GET a la URL de descarga:

curl -X GET https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o redacted_photo.jpg

Las descargas requieren su clave API. Guarde el archivo redactado en su propio almacenamiento como parte de su canalización.

Usar webhooks en lugar de realizar encuestas

El sondeo funciona para integraciones simples, pero los webhooks se adaptan mejor a los sistemas de producción. Registre un punto final de webhook en el panel y PiiBlur lo envía cuando se completa un trabajo, falla o cuando se elimina el archivo fuente original.

Configure puntos finales de webhook en la sección API de su panel. Los webhooks son a nivel de equipo y no se pasan por solicitud de carga.

Las cargas útiles del webhook incluyen un ID de evento, una marca de tiempo, un nombre de evento, un ID de medio, un estado y un objeto media anidado que utiliza los mismos campos públicos que el punto final de estado de los medios. Los medios redactados completos incluyen un media.download_url autenticado. Verifique el encabezado X-PiiBlur-Signature para confirmar que la solicitud se originó en PiiBlur. Los detalles de verificación de firma se encuentran en Documentación API.

Para obtener una arquitectura de producción con claves de idempotencia, deduplicación de eventos, trabajadores de descarga y colas de reintento, consulte Cómo crear un canal de redacción basado en webhooks.

Creación de una canalización de procesamiento por lotes

La mayoría de las cargas de trabajo de producción procesan muchos archivos, no uno a la vez. Una canalización por lotes envía trabajos en paralelo y recopila resultados a través de webhooks.

El flujo de trabajo:

  1. Archivos en cola. Su aplicación recopila archivos (desde cargas de usuarios, un depósito de almacenamiento o un análisis programado) y los coloca en una cola de procesamiento.
  2. Enviar trabajos en paralelo. PUBLICAR cada archivo en el punto final de medios. La API acepta solicitudes simultáneas dentro de los límites de tarifas de su plan.
  3. Recibir devoluciones de llamadas de webhook. A medida que se completa cada trabajo, PiiBlur envía el resultado al punto final de su webhook.
  4. Almacenar el resultado redactado. Su controlador de webhook descarga el archivo redactado y lo escribe en el almacenamiento.
  5. Manejar fallas. Si un trabajo falla, use el estado del webhook fallido para activar reintentos o revisión manual.

Este patrón se adapta a cualquier volumen. Una canalización que procesa 10.000 imágenes por día sigue la misma lógica que una que procesa 10: solo difieren la simultaneidad y la gestión de colas.

Para integraciones de alto rendimiento, consulte Documentación API para conocer los límites de tarifas por plan y los encabezados de respuesta.

Elección de categorías de PII para su caso de uso

PiiBlur detecta 13 categorías de PII: cabezas, matrículas, pantallas, escritura, señales de tráfico, tarjetas de identificación, pasaportes, tarjetas de crédito, placas de identificación, códigos QR, códigos de barras, documentos y tatuajes. No todos los casos de uso los requieren todos.

Seleccione categorías según sus datos, criterios de revisión y programa de privacidad:

  • Fotos subidas por el usuario - las cabezas y los documentos suelen ser la prioridad
  • Imágenes a nivel de calle: cabezas, matrículas y señales de tráfico
  • Imágenes de la cámara del tablero de la flota: cabezales, matrículas y pantallas
  • Fotografía inmobiliaria - cabezales, pantallas e identificaciones
  • Imágenes del centro de atención médica: cabezas, tarjetas de identificación, credenciales y documentos

Especificar solo las categorías que necesita mantiene el procesamiento rápido y evita la redacción excesiva.

Para flujos de trabajo por lotes grandes, la selección de categorías también afecta el costo: menos categorías significan un procesamiento más rápido y un menor cálculo por imagen.

Manejo de errores

La API devuelve códigos de estado HTTP estándar. Maneje estos en su integración:

  • 401 - clave API no válida o caducada
  • 409: la clave de idempotencia se reutilizó con una carga útil diferente o aún hay una solicitud coincidente en curso.
  • 422 - error de validación (falta archivo, formato no compatible, categoría no válida o vídeo de más de 10 minutos)
  • 429 - límite de cuota o tasa excedido; las respuestas de límite de velocidad incluyen Retry-After
  • 500 - error del servidor; reintentar con retroceso exponencial

Todos los errores JSON utilizan el sobre estándar { "error": ..., "request_id": ... }. Verifique el estado de la respuesta antes de asumir el éxito y registre request_id con el cuerpo de la respuesta para ayudar en la depuración.

Revisar puertas

No todos los trabajos completados deberían ir directamente a la publicación. Agregue una puerta de revisión cuando los medios estén destinados a su divulgación pública, divulgación legal, atención médica, educación, aplicación de la ley o cualquier flujo de trabajo que involucre a niños o personas vulnerables.

Para flujos de trabajo internos de menor riesgo, muestree los resultados completados en lugar de revisarlo todo. Realice un seguimiento de los errores por tipo de fuente y categoría. Si los revisores encuentran repetidamente placas en imágenes nocturnas o texto en pantalla en recorridos de oficina, conviértalo en una regla de flujo de trabajo en lugar de una prueba de memoria del revisor.

Utilice lista de verificación de control de calidad de redacción automatizada como punto de partida para la política de revisión.

Límites de precios y tarifas

El nivel gratuito de PiiBlur incluye 100 imágenes y 5 minutos de vídeo por mes, suficiente para crear y probar su integración. Los planes pagos comienzan en $49/mes y escalan hasta $499/mes para operaciones de gran volumen. Cada nivel aumenta los límites de tarifas y las cuotas mensuales.

Los detalles completos del plan se encuentran en página de precios.

Empezar a construir

La forma más rápida de evaluar la API: procesar algunas de sus propias imágenes. Tome una clave API del panel, ejecute el ejemplo de carga de cURL anterior e inspeccione el resultado. Luego conecte webhooks, cree su cola por lotes e impleméntela. Documentación API cubre todos los puntos finales, parámetros y formatos de respuesta.