PiiBlur-API-Referenz

Die PiiBlur-API stellt asynchrone PII-Schwärzungsaufträge für Bilder und Videos in die Warteschlange. Laden Sie Medien hoch, fragen Sie den Status ab und laden Sie dann die redigierte Ausgabe herunter, wenn die Verarbeitung abgeschlossen ist.

Der OpenAPI 3.1-Vertrag ist verfügbar unter /openapi/v1.json.

Wie verwische ich Gesichter mit einer API?

1. Erstellen Sie einen API-Schlüssel im PiiBlur-Dashboard und senden Sie ihn als Bearer-Token.
2. Laden Sie das Bild oder Video hoch /media/redact with categories[]=heads.
3. Umfrage /media/{mediaId} oder Webhooks konfigurieren und dann die redigierte Datei herunterladen, wenn die Verarbeitung abgeschlossen ist.

Basis-URL

https://piiblur.com/api/v1

Authentifizierung

Für alle API-Anfragen ist ein Bearer-API-Schlüssel aus dem API-Bereich Ihres Dashboards erforderlich.

bash

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

Ratenbeschränkungen

Die Tarifbegrenzungen variieren je nach Plan. Bei Überschreitung kehrt die API zurück 429 Too Many Requests.

Planen	Anfragen/Minute
Frei	60
Anlasser	120
Profi	300
Skala	1,000
Unternehmen	Brauch

Getaktete Pläne enthalten Standard-Ratenbegrenzungsheader in API-Antworten:

X-RateLimit-Limit - Maximale Anfragen pro Minute
X-RateLimit-Remaining - Im aktuellen Fenster verbleibende Anfragen
X-RateLimit-Reset – Unix-Zeitstempel, wenn das Fenster zurückgesetzt wird
Retry-After – Sekunden, die nach einer Ratenbegrenzung vor einem erneuten Versuch gewartet werden müssen 429

Fehler

Alle API-JSON-Fehler verwenden denselben Umschlag und enthalten eine Anforderungs-ID für Support und Protokollkorrelation.

json

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

Status	Gemeinsamer Code
401	unauthorized
404	nicht_gefunden
409	conflict
422	validation_failed
429	quote_exceeded oder rate_limit_exceeded
500	server_error

POST /media/redact

Laden Sie eine Datei hoch und stellen Sie die Schwärzung in einer mehrteiligen Anfrage in die Warteschlange. Die Verarbeitung erfolgt asynchron.

Überschriften

Name	Type	Required	Beschreibung
`Authorization`	string	Required	Bearer YOUR_API_KEY
`Idempotency-Key`	string	Optional	Verwenden Sie denselben Schlüssel erneut, wenn Sie nach einem Netzwerkfehler denselben Upload erneut versuchen

Parameter

Name	Type	Required	Beschreibung
`file`	file	Required	Die zu redigierende Bild- oder Videodatei
`categories`	string[]	Required	Zu erkennende PII-Kategorien. Werte: Köpfe, Nummernschilder, Bildschirme, Schrift, Straßenschilder, Ausweise, Pässe, Kreditkarten, Namensschilder, QR-Codes, Barcodes, Dokumente, Tätowierungen
`redaction_method`	string	Optional	Unschärfe (Standard) oder Pixelierung

Anfrage

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"

Antwort

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
}

Die maximale Dateigröße beträgt 1 GB. Unterstützte Formate sind JPG, JPEG, PNG, WebP, MP4, MOV und WebM. Die maximale Videodauer beträgt 10 Minuten. Die Wiederverwendung eines Idempotenzschlüssels mit einer anderen Nutzlast führt zu Ergebnissen 409 conflict. Idempotenzschlüssel verfallen nach 24 Stunden.

GET /media/{mediaId}

Rufen Sie den Status und die öffentlichen Details für ein Medienelement ab.

bash

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

Antwort abgeschlossen

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 erscheint nur für abgeschlossene Medien mit einer redigierten Ausgabe.

GET /media/{mediaId}/download

Laden Sie die verarbeitete redigierte Datei herunter. Rückgaben 404 bis die Bearbeitung abgeschlossen ist.

bash

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

GET /media

Listen Sie Medien mit optionalen Filtern auf.

Name	Type	Required	Beschreibung
`status`	string	Optional	ausstehend, in der Warteschlange, in Bearbeitung, abgeschlossen, fehlgeschlagen oder quote_exceeded
`media_type`	string	Optional	Bild oder Video
`page`	integer	Optional	Seitenzahl
`per_page`	integer	Optional	Elemente pro Seite, maximal 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}

Löschen Sie ein Medienelement und alle damit verbundenen gespeicherten Dateien. Rückgaben 204 No Content.

GET /usage

Erhalten Sie die aktuelle Nutzung und Limits für den Abrechnungszeitraum.

json

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

Webhooks

Webhooks benachrichtigen Ihren Server, wenn die Medienverarbeitung abgeschlossen ist, fehlschlägt oder wenn aufbewahrte Quellmedien gelöscht werden. Konfigurieren Sie Endpunkte im API-Bereich Ihres Dashboards.

Ereignis	Beschreibung
Medien.verarbeitet	Medienverarbeitung abgeschlossen
Medien.fehlgeschlagen	Die Medienverarbeitung ist fehlgeschlagen
media.source_deleted	Das beibehaltene Quellmedium wurde gelöscht

Signaturüberprüfung

Jede Webhook-Anfrage enthält eine X-PiiBlur-Signature Header, der eine HMAC-SHA256-Signatur des rohen Anforderungstexts enthält.

text

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

Nutzlast: media.processed

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"
  }
}

Nutzlast: media.failed

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"
  }
}