Hexis API (1.0.0)

Einführung

Hexis API ist eine RESTful API, die Zugang zu den in unserem Labor entwickelten Sprachanalyse-Tools bietet. Zurzeit umfasst dies ein leistungsfähiges Klassifizierungsmodell zur automatischen Moderation von Textnachrichten.

Verwendung der API

Erste Schritte

Falls Sie noch kein Benutzerkonto erstellt haben, können Sie sich hier anmelden. Sobald Sie Ihre Email-Adresse verifiziert haben, sind Sie freigeschaltet für die Nutzung der API und können einen Zugangs-Token erstellen.

Die API ist einfach aufgebaut und folgt gängigen Standards des Datenaustauschs. Für die Interaktion mit der API können Sie eine Programmiersprache Ihrer Wahl verwenden. Zum Testen kann auch ein Werkzeug wie Postman, Insomnia oder cURL auf der Befehlszeile nützlich sein.

Für den Anfang bietet diese Dokumentation Code-Beispiele in Javascript, Python, PHP und Unix-Shell. Sie veranschaulichen, wie man Anfragen an den API-Endpunkt stellt und Antworten von dort erhält.

API-Endpunkt

Diese API verwendet einen Basispfad von https://api.hexis.ai. Sie ist nur über eine SSL-gesicherte HTTP-Verbindung verfügbar.

Austausch-Format

Der HTTP-Inhaltstyp ist application/json, und die zwischen einem Client und dem API-Endpunkt ausgetauschten Payloads sind valide JSON-Objekte. Für den Textinhalt ist zu beachten: Doppelte Anführungszeichen (") werden escaped (\") und Zeilenumbrüche durch |LBR| ersetzt.

Klassifizierungs-Score

Eine Score ist ein Indikator für Wahrscheinlichkeiten, nicht für Schweregrade. Höhere Zahlen stehen für eine höhere Wahrscheinlichkeit, dass die Muster im Text den Mustern in Kommentaren ähneln, die von Personen — Laien sowie Fachleuten — als beleidigend gekennzeichnet wurden. Die Scores sollen es den Entwicklern ermöglichen, Schwellenwerte zu bestimmen und Texte auf der Grundlage dieser Schwellenwerte automatisch zu akzeptieren, zu prüfen oder abzulehnen.

Rate Limiting

Die API erlaubt standardmäßig maximal 10 Anfragen pro Sekunde. Sobald dieses Limit erreicht ist, werden Fehlermeldungen mit einem HTTP-Statuscode von 429 zurückzugeben. Die maximale request body size beträgt 10 Kilobytes. Anfragen, die größer sind, lösen einen Statuscode von 413 aus. Bitte beachten Sie, dass die maximale Textlänge für das Klassifizierungsmodell 120 Wörter beträgt. Jede Anfrage, die darüber hinausgeht, wird in 120 Wörter große Teile aufgeteilt und separat gezählt.

Demo-Endpunkt

Für jedes Modell gibt es eine Demoversion, die kostenlos und anonym zu nutzen ist. Sie kann zum Testen von API-Integrationen oder für alles andere verwendet werden, solange das Volumen der Anfragen gering ist. Die Anzahl der Anfragen ist auf 20 Anfragen pro 1 Stunde begrenzt. Um zur Demoversion zu wechseln, stellen Sie /demo einem der unten dokumentierten Pfade voran, z.B. /demo/mod-x/de/v1. Benutzer der Demoversion erklären sich mit der Sammlung von anonymen Nutzungsdaten zur Verbesserung unserer Dienste einverstanden.

Verfügbare Modelle

Klassen Sprachen Model Card
Binär OFFENSE
OTHER
Englisch, Deutsch tba
Multi-Task ABUSE
INSULT
PROFANITY
SPAM
OTHER
Englisch, Deutsch tba

Anpassen der API

Wenn Sie mit uns ein individuelles Modell erstellen möchten, beachten Sie bitte folgende Spezifikation für die Trainingsdaten.

Annotationsschema

Derzeit sind zwei Arten von Modellen implementiert: Binäre Klassifizierung, bei der die Trainingsdaten entweder als OFFENSE oder OTHER gekennzeichnet sind, und Multi-Task-Klassifizierung, bei der die Daten im Falle von verletzender Sprache als PROFANITY, INSULT oder ABUSE und im Falle von harmlosen Texten als OTHER gekennzeichnet sind. Im Multi-Task-Kontext ist es auch möglich, andere Kategorien — z.B. als SPAM gekennzeichnete Daten — einzureichen, die dann in dasselbe Klassifizierungsmodell einbezogen werden.

Dateiformat

Die Daten sollten in einer UTF-8-kodierten Textdatei vorliegen. Ein Trainingsbeispiel pro Zeile, im folgenden Format:

<TEXT> tab <LABEL-BINARY> tab <LABEL-MULTITASK>

Zeilenumbrüche im Text werden durch |LBR| ersetzt.

Authentication

Bearer

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Binäre Klassifikation

Das binäre Klassifizierungsmodell ist die einfachste und unter Umständen effektivste Lösung, um anstößige Sprache zu filtern. Es kombiniert die Datenkategorien PROFANITY, INSULT und ABUSE zu einer positiven Klasse OFFENSE, die der negativen Klasse OTHER gegenübergestellt wird. Es gibt nicht viel einzustellen, aber auch nicht viel zu interpretieren, wodurch sich die Automatisierung der Moderation vereinfacht. Das Modell ist über den Pfad /mod-1 zu erreichen.

Authorizations:
path Parameters
language
required
string

Sprachcode. Mögliche Werte sind en, de

version
required
string

API Version. Mögliche Werte sind v1

Request Body schema: application/json
text
required
string

Eingabe-Text

Responses

200

OK

Response Schema: application/json
scores
object

Liste von Scores

400

Bad Request

401

Unauthorized

413

Request Entity Too Large

429

Too Many Requests

post/mod-1/{language}/{version}
/mod-1/{language}/{version}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "text": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scores":
    [
    ]
}

Multi-Task Klassifikation

Das Multi-Task-Klassifikationsmodell ermöglicht die Einrichtung detaillierter Filtersysteme. Es umfasst alle Datenkategorien aus dem Task zur Erkennung von anstößiger Sprache (PROFANITY, INSULT und ABUSE) und ist gleichzeitig für die Spam-Erkennung (SPAM) trainiert. Beide Tasks werden mit der Negativklasse OTHER kontrastiert. Das Multi-Task-Modell profitiert von der Interaktion der beteiligten Aufgaben, was zu reichhaltigeren und robusteren internen Repräsentationen führt. Dadurch wird eine feinkörnige Klassifizierung mit unterschiedlichen Schwellenwerten möglich, die speziell auf Ihren Anwendungsfall abgestimmt sind. Das Modell ist über den Pfad /mod-x zu erreichen.

Authorizations:
path Parameters
language
required
string

Sprachcode. Mögliche Werte sind en, de

version
required
string

API Version. Mögliche Werte sind v1

Request Body schema: application/json
text
required
string

Eingabe-Text

Responses

200

OK

Response Schema: application/json
scores
object

Liste von Scores

400

Bad Request

401

Unauthorized

413

Request Entity Too Large

429

Too Many Requests

post/mod-x/{language}/{version}
/mod-x/{language}/{version}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "text": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scores":
    [
    ]
}