KI-Humanizer-API: Humanizer API v2 und Detector API für Entwickler

Die KI-Humanizer-API von Academic Humanizer bietet Entwicklern und Institutionen zwei REST-Endpunkte: POST /api/v2/external/humanize, der humanisierten Text mit Änderungen auf Satzebene zurückgibt, und POST /api/v2/external/detector, der eine KI-Erkennungsbewertung für bis zu 100.000 Zeichen liefert. Beide nutzen einen serverseitigen API-Key und greifen auf dasselbe Credit-Guthaben zu wie Ihr Konto.

Dieser Beitrag erklärt, für wen die API gedacht ist, wie Authentifizierung und Zugriffskontrolle funktionieren, was jeder Endpunkt zurückgibt und wie Credits gezählt werden. Die vollständige Referenz finden Sie unter /docs.

Für wen die AI Humanizer API gedacht ist

Der Web-Editor passt zu einzelnen Forschenden. Die API passt zu Produkten und Teams, die wissenschaftliche Texte in großer Menge oder in ihrer eigenen Oberfläche verarbeiten:

• Schreibplattformen, die einen Humanisierungsschritt in ihrem eigenen Editor anbieten möchten.
• LMS- und Lernsoftware, die ein KI-Erkennungssignal als einen Baustein eines menschlichen Prüfprozesses benötigen, nicht als automatisches Urteil.
• Lektorats- und Korrekturdienste, die Kundenentwürfe einen einheitlichen ersten Durchgang durchlaufen lassen, bevor eine Lektorin sie liest.
• Forschungsreferate, die Antragstexte oder Berichte stapelweise prüfen möchten.

Wenn Ihr Einsatz Arbeiten von Studierenden betrifft, gestalten Sie ihn so, dass Menschen die endgültigen Entscheidungen treffen. Detektorergebnisse sind Belege, die geprüft werden müssen, und unser Beitrag dazu, was vor dem Infragestellen studentischer Autorschaft zu bedenken ist, erklärt, warum.

Authentifizierung, IP-Freigabelisten und Rate Limits

Erstellen Sie einen Key unter /api, während Sie angemeldet sind. Der Key wird nur einmal bei der Erstellung angezeigt, und Academic Humanizer speichert nur einen Hash davon. Kopieren Sie ihn also direkt in Ihren Secret Manager oder eine Umgebungsvariable auf dem Server. Liefern Sie ihn niemals in Browser- oder Mobile-Code aus.

Senden Sie den Key im Header X-API-Key. Diesen Header empfiehlt die Dokumentation; der Server akzeptiert den Key auch als Bearer-Token im Header Authorization.

Jede Anfrage durchläuft dann einige Prüfungen, bevor Text verarbeitet wird.

1. Key-PrüfungDer Key muss existieren und aktiv sein, und das zugehörige Konto muss aktiv sein.
2. IP-FreigabelisteIm eingeschränkten Modus werden nur Anfragen von den aufgeführten IPs oder CIDR-Bereichen angenommen.
3. Rate LimitAnfragen über dem Limit pro Sekunde für den Key werden mit HTTP 429 abgelehnt.
4. VerarbeitungDer Text wird humanisiert oder analysiert, und die Credits werden mit Ihrem Guthaben abgeglichen.
5. Gespeichertes ErgebnisDas Ergebnis wird in Ihrem Konto gespeichert und als JSON zurückgegeben.

Der IP-Zugriff hat zwei Modi: öffentlich, bei dem jede IP mit einem gültigen Key aufrufen darf, und eingeschränkt, bei dem nur aufgeführte IPs oder CIDR-Blöcke zugelassen sind. Für jeden Produktionsserver mit fester ausgehender Adresse lohnt es sich, den eingeschränkten Modus zu aktivieren. Das Standard-Rate-Limit liegt bei 10 Anfragen pro Sekunde.

Der Humanize-Endpunkt

Der Request-Body ist JSON mit einem Pflichtfeld, originalContent, und einem optionalen Feld, researchField. Wenn Sie ein Forschungsfeld senden, muss es einer der unterstützten Namen sein: Arts and Humanities, Social Sciences, Business and Economics, Engineering, Natural Sciences oder Medical and Health Sciences. Lassen Sie es weg oder senden Sie null, wenn Sie es nicht benötigen.

curl -X POST https://academichumanizer.ai/api/v2/external/humanize   -H "Content-Type: application/json"   -H "X-API-Key: YOUR_API_KEY"   -d '{"originalContent": "Paste the paragraph or abstract to humanize here.", "researchField": "Natural Sciences"}'

Ein erfolgreicher Aufruf gibt HTTP 201 mit einem JSON-Body zurück, der Folgendes enthält:

• humanizedText: der vollständige umgeschriebene Text.
• changedCount: wie viele Sätze geändert wurden.
• sentences: ein Array mit Einträgen auf Satzebene, jeweils mit Start- und End-Offset in Ihrem Originaltext, dem Ausgangssatz, dem humanisierten Satz und einem changed-Flag. Das Array kann leer sein.

Die ID des gespeicherten Ergebnisses kommt im Response-Header X-Humanizer-Id zurück, sodass Sie eine Anfrage in Ihrem System mit dem gespeicherten Ergebnis im Konto des Nutzers verknüpfen können. Beachten Sie, dass changed angibt, ob ein Satz umgeschrieben wurde; es ist kein KI-Erkennungsurteil. Dafür nutzen Sie den Detector-Endpunkt.

Mit den Satz-Offsets lässt sich in Ihrer eigenen Oberfläche leicht ein Diff darstellen: Heben Sie die geänderten Abschnitte hervor und lassen Sie Nutzer jeden einzeln annehmen oder bearbeiten. Nutzer sollten jede Ausgabe vor der Verwendung prüfen, da KI-Umformulierungen Fehler einführen oder die Bedeutung verschieben können.

Der Detector-Endpunkt

Der Detector-Endpunkt nimmt ein einziges Pflichtfeld, text, mit bis zu 100.000 Zeichen entgegen. Er gibt den Analysestatus, die Zeichenzahl, die benötigte Zeit, eine Gesamtbewertung des Dokuments, die Detektorergebnisse und creditUsed zurück. Forschungsfelder werden hier nicht verwendet.

Ein typisches Muster: zuerst Detector aufrufen, dem Nutzer zeigen, welche Passagen Signale auslösen, und Humanize nur für die Abschnitte aufrufen, die er auswählt. So bleiben Kosten und Änderungen minimal.

Wie API-Credits gezählt werden

Beide Endpunkte verbrauchen Credits des Kontos, dem der Key gehört. Die beiden Endpunkte zählen unterschiedlich.

Humanize kostet 1 Credit pro 500 Zeichen, aufgerundet pro Anfrage, und wird nur berechnet, wenn ein vollständiges Ergebnis gespeichert wird. Detector kostet 1 Credit pro 5.000 Zeichen, aufgerundet. Reicht das Guthaben nicht aus, schlägt die Anfrage mit einem Fehler wegen unzureichender Credits fehl, statt ein Teilergebnis zu liefern. Abos und Pakete werden in So funktionieren Credits und Preise beschrieben, die aktuellen Preise stehen unter /pricing.

Fehler, die Sie behandeln sollten

Fehler-Bodys enthalten einen kurzen maschinenlesbaren Code. Verzweigen Sie daher anhand des Codes, nicht anhand des Meldungstextes.

Häufige Fragen

Wie erhalte ich einen API-Key?

Melden Sie sich an und öffnen Sie /api. Erstellen Sie einen Key, kopieren Sie ihn sofort (er wird nur einmal angezeigt) und speichern Sie ihn auf Ihrem Server.

Kann ich einschränken, welche Server meinen Key verwenden?

Ja. Stellen Sie den IP-Zugriff auf den eingeschränkten Modus um und führen Sie die IPs oder CIDR-Bereiche auf, die die API aufrufen dürfen. Anfragen von anderswo werden mit HTTP 403 abgelehnt.

Gibt es ein kostenloses Kontingent für die API?

Die API nutzt dieselben Credits wie die Web-App. Neue Konten erhalten einmalig 10 Gratis-Credits, genug, um den Humanize-Endpunkt mit einigen kurzen Passagen zu testen.

Gegen welche Detektoren wird die Ausgabe geprüft?

Academic Humanizer wird gegen Turnitin, GPTZero, ZeroGPT, Copyleaks, Sapling und Originality.ai validiert. Wie bei jedem Tool variieren die Ergebnisse je nach Detektor, und kein Ergebnis ist garantiert.

Mit Academic Humanizer entwickeln

Wenn Ihr Produkt bereits Manuskripte, Abstracts oder Studienarbeiten verarbeitet, können Sie mit der API einen Humanisierungsschritt oder eine Erkennungsprüfung ergänzen, ohne Nutzer anderswohin zu schicken. Beginnen Sie mit einem Test-Key, lassen Sie einige echte Absätze durch beide Endpunkte laufen und lesen Sie die vollständige Referenz unter /docs, bevor Sie in Produktion gehen.