> Gesichtssuche API für Reverse-Gesichtssuche: Foto per POST senden, öffentliche Profile mit Konfidenz-Score erhalten. Ein Credit pro Suche, kein Abo. **GESICHTSSUCHE API** # GESICHTSSUCHE, AUS DEINEM EIGENEN CODE. Eine **Reverse-Gesichtssuche-API** über das öffentliche Web. Sende ein Foto eines Gesichts und erhalte die Seiten und Profile zurück, auf denen es auftaucht, jeweils mit Konfidenz-Score und Link. Ein Credit pro Suche, in Dollar abgerechnet, ohne Abo und ohne Mindestumsatz. Kein Verkaufsgespräch · Kein Mindestumsatz · Credits verfallen nie Auch auf [RapidAPI](https://rapidapi.com/muratcankuruoffical/api/trace-reverse-face-search-api) · [OpenAPI-Spezifikation](https://traceaifacescan.app/openapi.json) · [Code-Beispiele auf GitHub](https://github.com/muratcankuruoffical/reverse-face-search-api) · [Hugging Face Space](https://huggingface.co/spaces/muratcankuru/reverse-face-search) · [Apify Actor](https://apify.com/muratcankuru/reverse-face-search) - Ergebnisse in rund einer Minute - Ein Credit pro Suche - REST + JSON, nichts zu installieren - Eigene Engine, kein Reseller **WAS DIE API MACHT** ## EIN FOTO REIN. JEDER ÖFFENTLICHE TREFFER RAUS. Dieselbe Engine, auf der auch das Panel läuft, mit denselben Ergebnissen. Die API ist keine abgespeckte Stufe. **REVERSE-GESICHTSSUCHE** ### Gesichter abgleichen, nicht Dateien. Eine normale Rückwärtssuche nach Bildern findet Kopien desselben Bildes. Hier wird das Gesicht abgeglichen — ein anderes Foto derselben Person, anderes Outfit, anderes Jahr, zählt trotzdem als Treffer. **KONFIDENZ-SCORE** ### Jeder Treffer trägt eine Zahl. Jedes Ergebnis hat einen Ähnlichkeitswert von 50 bis 100 und eine Stufe: möglich ab 70, stark ab 80, nahezu sicher ab 90. Nichts wird als Urteil ausgegeben. **SOCIAL-HANDLES** ### Der Account, nicht nur die Seite. Gehört die URL zu einem Account, kommen Handle und Plattform als eigene Felder zurück — du musst keine URLs selbst parsen. **EIGENE ENGINE** ### Kein Reseller. Trace betreibt seinen eigenen Gesichtssuche-Dienst. Deshalb kostet eine Suche Cents statt Dollar, und deshalb müssen wir deine Anfragen nicht drosseln. **QUICKSTART** ## DREI AUFRUFE, VON ANFANG BIS ENDE. Authentifizierung ist ein Header. Kein SDK zu installieren, kein Handshake. ### Scan starten Multipart, Feldname `image`. JPEG, PNG oder WebP, bis zu 8 MB, mindestens 200px auf der kurzen Seite. `Idempotency-Key` ist optional und macht einen erneuten Versuch sicher. ```bash curl -X POST https://traceaifacescan.app/api/v1/scans \ -H "Authorization: Bearer trk_live_..." \ -H "Idempotency-Key: $(uuidgen)" \ -F image=@face.jpg ``` **202 ACCEPTED** ```json { "id": "01m0jr1j5cbhwqsnt5qjx3zyd8", "status": "queued", "progress": 0, "locked": false, "match_count": 0, "credits_remaining": 9 } ``` ### Pollen, bis es fertig ist Eine Suche dauert etwa 25–45 Sekunden. Pollen alle ein bis zwei Sekunden, bis `status` `done` oder `failed` ist. ```bash curl https://traceaifacescan.app/api/v1/scans/01m0jr1j5cbhwqsnt5qjx3zyd8 \ -H "Authorization: Bearer trk_live_..." ``` **200 OK** ```json { "status": "done", "progress": 100, "locked": false, "match_count": 2, "matches": [ { "score": 88, "tier": "strong", "platform": "x", "handle": "@alexrivers88", "url": "https://x.com/alexrivers88", "preview_url": ".../scans/01m0.../previews/0" } ] } ``` ### Credit einlösen Ein Scan, der ohne verfügbare Credits erstellt wird, kommt `locked: true` ohne Treffer zurück — es wurde nichts gesucht. Das Aufdecken ist bewusst ein eigener Aufruf: Ein Skript, das eine Liste von Scans durchgeht, soll dein Guthaben nicht versehentlich leeren können. ```bash curl -X POST \ https://traceaifacescan.app/api/v1/scans/01m0.../reveal \ -H "Authorization: Bearer trk_live_..." ``` **ENDPUNKTE** ## DIE GESAMTE OBERFLÄCHE. Sieben Endpunkte. Die maschinenlesbare Definition liegt unter [openapi.json](https://traceaifacescan.app/openapi.json), die vollständige Referenz mit Response-Bodies steht in [den Docs](https://traceaifacescan.app/docs). - **POST** — `/v1/scans` — Scan aus einem Foto starten. - **GET** — `/v1/scans/{id}` — Status, Fortschritt und Treffer. - **GET** — `/v1/scans` — Deine Scans, paginiert. - **POST** — `/v1/scans/{id}/reveal` — Credit einlösen und die echte Suche ausführen. - **GET** — `/v1/scans/{id}/previews/{n}` — Das Gesichts-Thumbnail eines Treffers. - **DELETE** — `/v1/scans/{id}` — Scan, Bild und Vorschauen löschen. - **GET** — `/v1/account` — Dein Credit-Guthaben. **FEHLER UND LIMITS** ## VORHERSEHBARE FEHLER. Fehler kommen als `application/problem+json` mit einem stabilen `code`-String zurück. Auf den Code prüfen, nie auf die Meldung. - **402** — `insufficient_credits` — Keine Credits mehr übrig. Es wurde nichts gesucht und nichts abgebucht. - **404** — `no_face_detected` — Kein Gesicht im Bild. Ein anderes Foto, kein erneuter Versuch. - **429** — `rate_limited` — Nur nach wiederholt fehlgeschlagener Authentifizierung. `Retry-After` sagt, wann. - **401** — `unauthorized` — Fehlender, falscher oder widerrufener Key. - **503** — `provider_unavailable` — Unsere Seite. Ein für eine fehlgeschlagene Suche reservierter Credit wird immer zurückerstattet. ### Limits - **Kein Rate-Limit für Anfragen.** Lesevorgänge werden nicht gezählt, und es gibt keine Obergrenze pro Minute. - Dein eigentliches Limit ist dein **Credit-Guthaben**: Ein Scan kostet einen Credit, ein Lesevorgang kostet nichts. - Bilder bis zu **8 MB**, mindestens **200px** auf der kurzen Seite. - Scans und ihre Bilder werden nach **30 Tagen** gelöscht. `DELETE` macht das sofort. **PREISE** ## EIN CREDIT, EINE SUCHE. Dieselben Credits, die auch das Panel nutzt, aus demselben Guthaben. Kein Abo, kein Mindestumsatz, und sie verfallen nie. Das 100-Credit-Paket ist das, auf das die API zugeschnitten ist. Kaufbar per Karte, mit Telegram Stars oder mit Kryptowährung — siehe [die Credit-Pakete](https://traceaifacescan.app/de/#pricing). Mehr Volumen als das größte Paket? [Schreib uns](https://docs.google.com/forms/d/e/1FAIpQLSdVeyYm3BLWkEnmHToK5_JQynOHCctKTxMkBJp3PJf-pmaLYQ/viewform). **EHRLICHE GRENZEN** ## WAS DIESE API NICHT TUT. **Das ist kein Identitätsdienst.** Ein Treffer ist ein Ähnlichkeitswert zwischen zwei Bildern, keine Aussage darüber, wer jemand ist. In der Antwort steht kein Name, keine Adresse, keine Telefonnummer und kein Datensatz jeglicher Art — nur öffentliche URLs und eine Zahl. **Ein leeres Ergebnis ist kein Abwesenheitsbeweis.** Es bedeutet nur, dass im erreichbaren Teil des öffentlichen Webs nichts gefunden wurde. Hat die Person kein öffentliches Foto, gibt es nichts zu finden — das kann keine API ändern. **Nichts hinter einem Login wird berührt.** Jedes Ergebnis ist eine Seite, die bereits öffentlich war. **Sie darf nicht für Background-Checks, Einstellungsverfahren, Kreditvergabe, Versicherungen, Überwachung oder Strafverfolgung genutzt werden**, und nicht gegen Minderjährige. Sende nur Fotos, die du durchsuchen darfst. Das steht in den [Nutzungsbedingungen](https://traceaifacescan.app/de/nutzungsbedingungen/), und wir setzen es durch — ein so genutzter Key wird widerrufen. **FAQ** ## WAS ENTWICKLER ZUERST FRAGEN. ### Was ist eine Gesichtssuche API? Es ist eine HTTP-API, die ein Foto eines Gesichts entgegennimmt und die anderen Stellen im öffentlichen Internet zurückgibt, an denen dasselbe Gesicht auftaucht. Anders als eine Rückwärtssuche nach Bildern, die Bilddateien vergleicht, vergleicht eine Gesichtssuche die Gesichtsgeometrie — sie erkennt dieselbe Person also auch auf einem völlig anderen Foto. Trace bietet das als REST-API mit JSON-Antworten: ein POST, um einen Scan zu starten, ein GET, um die Treffer zu lesen. ### Was kostet eine Gesichtssuche über die API? Ein Credit pro Suche, und Credits werden in Paketen gekauft, die in US-Dollar bepreist sind — von $4 für fünf Credits bis $50 für 100. Es gibt kein Abo, keinen Mindestumsatz und kein Verfallsdatum. Die API greift auf dasselbe Guthaben zu wie das Panel. ### Gibt es eine kostenlose Stufe oder eine Testphase? Auf der API gibt es keine kostenlose Suche. Eine API-Anfrage von einem Account ohne Credits erstellt den Scan, durchsucht ihn aber nicht: Er kommt gesperrt und ohne Treffer zurück. Das Panel zeigt einem angemeldeten Besucher ein statisches Beispielergebnis, damit er die Form eines fertigen Falls sieht — die API liefert das bewusst nie, denn ein Platzhalter ist etwas, auf das ein Skript aufbauen würde. ### Wie schnell ist eine Suche? Etwa 25 bis 45 Sekunden von Anfang bis Ende, manchmal bis zu 90. Deshalb ist die API asynchron: POST liefert sofort 202 mit einer ID, und du pollst sie. Eine HTTP-Anfrage eine Minute lang offen zu halten, würde aus einer getrennten Verbindung eine abgebrochene Suche machen. ### Kann ich Bild-URLs statt eines Datei-Uploads nutzen? In v1 nicht. Eine URL zu akzeptieren würde die API zu einem SSRF-Proxy machen — wir würden beliebige Adressen im Auftrag eines Aufrufers aus unserem Netzwerk heraus abrufen. Falls es zurückkommt, dann mit einer Allowlist und abgelehnten privaten Adressbereichen. ### Ist die API rate-limitiert? Nein. Rufe sie so schnell auf, wie dein Code kann — Lesevorgänge werden nicht gezählt, und es gibt keine Obergrenze pro Minute. Das Einzige, was dich begrenzt, ist dein Credit-Guthaben, denn ein Scan kostet einen Credit und ein Lesevorgang kostet nichts. Eine Sicherheitsbremse bleibt, und ein gültiger Key bekommt sie nie zu sehen: wiederholt fehlgeschlagene Authentifizierungsversuche von derselben Adresse werden verzögert, damit das Raten von Keys teuer bleibt. ### Ist es legal, eine Gesichtssuche API zu nutzen? Das hängt ganz davon ab, wofür du sie nutzt und wo du bist. Zu prüfen, ob ein Foto auf deiner eigenen Plattform zu der Person gehört, die es nutzt, ist etwas anderes als eine Gesichtsdatenbank aufzubauen. Gesichtsdaten sind nach DSGVO und KVKK eine besondere Kategorie, und du bist der Verantwortliche für alles, was du uns schickst. Lies die Nutzungsbedingungen: Background-Checks, Einstellungsverfahren, Kreditvergabe, Versicherungen, Überwachung und Strafverfolgung sind alle ausgeschlossen. ### Ist das eine Gesichtserkennung API oder eine Rückwärtsbildsuche API? Es ist eine Gesichtssuche-API, eine spezielle Form der Gesichtserkennung. Sie vergleicht keine zwei von dir bereitgestellten Fotos, verifiziert kein Ausweisdokument und gibt nichts darüber zurück, wer eine Person ist. Sie nimmt ein Foto und durchsucht das öffentliche Web nach weiteren Bildern desselben Gesichts, wobei jeder Treffer als öffentliche URL mit Ähnlichkeitswert zurückkommt. Das unterscheidet sie auch von einer Rückwärtsbildsuche-API: Rückwärtsbildsuche vergleicht die Bilddatei und findet damit Kopien genau dieses Bildes, während hier die Gesichtsgeometrie verglichen wird und dasselbe Gesicht auf einem anderen Foto gefunden wird. **GESICHTSSUCHE API** ## STARTE MIT EINEM AUFRUF. Erstelle einen Key im Panel, und der erste curl-Aufruf funktioniert sofort.