TRACE / GESICHTSSUCHE API

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 · OpenAPI-Spezifikation · Code-Beispiele auf GitHub · Hugging Face Space · Apify Actor

  • Ergebnisse in rund einer Minute
  • Ein Credit pro Suche
  • REST + JSON, nichts zu installieren
  • Eigene Engine, kein Reseller
curl -X POST https://traceaifacescan.app/api/v1/scans \
  -H "Authorization: Bearer trk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -F image=@face.jpg
{
  "id": "01m0jr1j5cbhwqsnt5qjx3zyd8",
  "status": "queued",
  "progress": 0,
  "locked": false,
  "match_count": 0,
  "credits_remaining": 9
}
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.

  1. 01

    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.

    curl -X POST https://traceaifacescan.app/api/v1/scans \
      -H "Authorization: Bearer trk_live_..." \
      -H "Idempotency-Key: $(uuidgen)" \
      -F image=@face.jpg
    202 ACCEPTED
    {
      "id": "01m0jr1j5cbhwqsnt5qjx3zyd8",
      "status": "queued",
      "progress": 0,
      "locked": false,
      "match_count": 0,
      "credits_remaining": 9
    }
  2. 02

    Pollen, bis es fertig ist

    Eine Suche dauert etwa 25–45 Sekunden. Pollen alle ein bis zwei Sekunden, bis status done oder failed ist.

    curl https://traceaifacescan.app/api/v1/scans/01m0jr1j5cbhwqsnt5qjx3zyd8 \
      -H "Authorization: Bearer trk_live_..."
    200 OK
    {
      "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"
        }
      ]
    }
  3. 03

    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.

    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, die vollständige Referenz mit Response-Bodies steht in den Docs.

  • POST/v1/scansScan aus einem Foto starten.
  • GET/v1/scans/{id}Status, Fortschritt und Treffer.
  • GET/v1/scansDeine Scans, paginiert.
  • POST/v1/scans/{id}/revealCredit 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/accountDein 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.

  • 402insufficient_creditsKeine Credits mehr übrig. Es wurde nichts gesucht und nichts abgebucht.
  • 404no_face_detectedKein Gesicht im Bild. Ein anderes Foto, kein erneuter Versuch.
  • 429rate_limitedNur nach wiederholt fehlgeschlagener Authentifizierung. Retry-After sagt, wann.
  • 401unauthorizedFehlender, falscher oder widerrufener Key.
  • 503provider_unavailableUnsere 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. Mehr Volumen als das größte Paket? Schreib uns.

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, 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.