Referencia de la API de PiiBlur

La API PiiBlur pone en cola trabajos de redacción de PII asíncronos para imágenes y vídeos. Cargue medios, sondee el estado y luego descargue el resultado redactado cuando se complete el procesamiento.

El contrato OpenAPI 3.1 está disponible en /openapi/v1.json.

¿Cómo desenfoco caras con una API?

1. Cree una clave API en el panel de PiiBlur y envíela como token de portador.
2. Sube la imagen o el vídeo a /media/redact with categories[]=heads.
3. Encuesta /media/{mediaId} o configure webhooks y luego descargue el archivo redactado cuando se complete el procesamiento.

URL básica

https://piiblur.com/api/v1

Autenticación

Todas las solicitudes de API requieren una clave de API de portador de la sección API de su panel de control.

bash

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

Límites de tarifas

Los límites de tarifas varían según el plan. Cuando se excede, la API devuelve 429 Too Many Requests.

Plan	Solicitudes / minuto
Gratis	60
Motor de arranque	120
Pro	300
Escala	1,000
Empresa	Costumbre

Los planes medidos incluyen encabezados de límite de tarifa estándar en las respuestas de API:

X-RateLimit-Limit - Solicitudes máximas por minuto
X-RateLimit-Remaining - Solicitudes restantes en la ventana actual
X-RateLimit-Reset - Marca de tiempo de Unix cuando la ventana se reinicia
Retry-After - Segundos de espera antes de volver a intentarlo después de un límite de velocidad 429

Errores

Todos los errores de API JSON utilizan el mismo sobre e incluyen una identificación de solicitud para soporte y correlación de registros.

json

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": {
      "file": ["The file field is required."]
    }
  },
  "request_id": "req_abc123"
}

Estado	código común
401	unauthorized
404	extraviado
409	conflict
422	validación_fallida
429	cuota_excedida o tasa_limit_exceeded
500	error_servidor

POST /media/redact

Cargue un archivo y ponga en cola la redacción en una solicitud de varias partes. El procesamiento es asincrónico.

Encabezados

Nombre	Type	Required	Descripción
`Authorization`	string	Required	Bearer YOUR_API_KEY
`Idempotency-Key`	string	Optional	Reutilice la misma clave cuando vuelva a intentar la misma carga después de una falla de red

Parámetros

Nombre	Type	Required	Descripción
`file`	file	Required	El archivo de imagen o vídeo a redactar.
`categories`	cadena[]	Required	Categorías de PII a detectar. Valores: cabezas, matrículas, pantallas, escritura, letreros de calles, tarjetas de identificación, pasaportes, tarjetas de crédito, credenciales, códigos qr, códigos de barras, documentos, tatuajes
`redaction_method`	string	Optional	desenfoque (predeterminado) o pixelación

Pedido

bash

curl -X POST https://piiblur.com/api/v1/media/redact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: upload-2026-03-17-001" \
  -F "[email protected]" \
  -F "categories[]=heads" \
  -F "categories[]=license_plates" \
  -F "redaction_method=blur"

Respuesta

json

{
  "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-17T10:30:00+00:00",
  "processed_at": null,
  "failed_at": null
}

El tamaño máximo de archivo es 1 GB. Los formatos admitidos son jpg, jpeg, png, webp, mp4, mov y webm. La duración máxima del vídeo es de 10 minutos. Reutilizar una clave de idempotencia con una carga útil diferente regresa 409 conflict. Las claves de idempotencia caducan después de 24 horas.

GET /media/{mediaId}

Obtenga el estado y los detalles públicos de un elemento multimedia.

bash

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

Respuesta completa

json

{
  "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-17T10:30:00+00:00",
  "processed_at": "2026-03-17T10:30:15+00:00",
  "failed_at": null,
  "download_url": "https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download"
}

download_url aparece solo para medios completos con una salida redactada.

GET /media/{mediaId}/download

Descargue el archivo redactado procesado. Devoluciones 404 hasta que se complete el procesamiento.

bash

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

GET /media

Enumere los medios con filtros opcionales.

Nombre	Type	Required	Descripción
`status`	string	Optional	pendiente, en cola, procesando, completado, fallido o cuota_excedida
`media_type`	string	Optional	imagen o vídeo
`page`	integer	Optional	Número de página
`per_page`	integer	Optional	Artículos por página, máximo 100

json

{
  "data": [
    {
      "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-17T10:30:00+00:00",
      "processed_at": "2026-03-17T10:30:15+00:00",
      "failed_at": null,
      "download_url": "https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 98,
    "total_pages": 5
  },
  "links": {
    "next": "https://piiblur.com/api/v1/media?page=2",
    "previous": null
  }
}

DELETE /media/{mediaId}

Elimine un elemento multimedia y cualquier archivo almacenado asociado a él. Devoluciones 204 No Content.

GET /usage

Obtenga el uso y los límites del período de facturación actual.

json

{
  "plan": "pro",
  "period_start": "2026-03-01",
  "period_end": "2026-03-31",
  "images": {
    "used": 1250,
    "limit": 25000
  },
  "video_minutes": {
    "used": 45,
    "limit": 60
  }
}

Ganchos web

Los webhooks notifican a su servidor cuando el procesamiento de medios se completa, falla o cuando se elimina el medio de origen retenido. Configure puntos finales en la sección API de su panel.

Evento	Descripción
medios.procesados	Procesamiento de medios completado
medios.fallidos	Error en el procesamiento de medios
media.source_deleted	Se han eliminado los medios de origen retenidos.

Verificación de firma

Cada solicitud de webhook incluye un X-PiiBlur-Signature encabezado que contiene una firma HMAC-SHA256 del cuerpo de la solicitud sin formato.

text

X-PiiBlur-Signature: sha256=HMAC_SHA256(payload, secret)

Carga útil: medios.procesados

json

{
  "id": "evt_2f6ad0f3-52a1-4ce6-b2e2-0f9bd07d4422",
  "event": "media.processed",
  "timestamp": "2026-03-17T10:30:15+00:00",
  "media_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "completed",
  "processed_at": "2026-03-17T10:30:15+00:00",
  "failed_at": null,
  "media": {
    "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-17T10:30:00+00:00",
    "processed_at": "2026-03-17T10:30:15+00:00",
    "failed_at": null,
    "download_url": "https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download"
  }
}

Carga útil: medios.fallidos

json

{
  "id": "evt_52fd9716-1181-4a2f-b719-261b2ec3cb47",
  "event": "media.failed",
  "timestamp": "2026-03-17T10:30:15+00:00",
  "media_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "failed",
  "processed_at": null,
  "failed_at": "2026-03-17T10:30:15+00:00",
  "media": {
    "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "status": "failed",
    "filename": "photo.jpg",
    "media_type": "image",
    "categories": ["heads", "license_plates"],
    "redaction_method": "blur",
    "file_size_bytes": 482391,
    "duration_seconds": null,
    "created_at": "2026-03-17T10:30:00+00:00",
    "processed_at": null,
    "failed_at": "2026-03-17T10:30:15+00:00"
  }
}