Hexis API is a RESTful API that lets you programmatically interact with language analysis tools built at our lab. At the moment this includes a high-performance text classification model for hate speech detection.
This API uses a base path of
https://api.hexis.ai. It is only available via a SSL-secured HTTP connection.
To work with Hexis API, you can either use standard network libraries for the programming language of your choice, or use the Swagger Generator 3 tool to auto-generate Hexis API client libraries for a variety of languages. We do not provide any guarantees that these autogenerated libraries are compatible with our API (e.g. some libraries may not work with Bearer authentication). You can find our OpenAPI 3.0 specification here.
The HTTP content type is
application/json and the payloads exchanged between a client and the REST-endpoint are valid JSON objects. Other things to note in the
text content: Double quotes (
") need to be escaped (
\") and line breaks should be replaced with
Hexis API's scores are an indication of probability, not severity. Higher numbers represent a higher likelihood that the patterns in the text resemble patterns in comments that people have tagged as offensive. These scores are intended to let developers pick a threshold and review or ignore scores below that point. Although the number is not a score of how offensive a particular comment is, the threshold should be set according to the use case at hand.
In a high-recall setting where it is favorable to deal with false positives instead of false negatives, one can choose a point around 0.5 or above. While it is possible to mistakenly flag a message that is only mildly toxic (ideally there is a manual review process in place), this setting will catch the less salient, implicit cases.
On the other hand, there is the high-precision setting where the priority is to automatically filter only definitive cases of offensive language. Here it's safe to choose a point around 0.9 or above.
As a simple heuristic: If you do moderation manually, a sensible threshold value would be 0.5. Alternatively, you could just use the raw classification scores to rank items for review. If you want to do moderation without human intervention, you could pick a threshold value of 0.9 (and be potentially overblocking in a few cases) or 0.99 (and be potentially underblocking in a few cases).
The REST-endpoint allows a maximum of 10 requests per second. Once this limit is reached, calls to the endpoint will start returning errors with an HTTP status code of 429. The maximum request body size is 10 kilobytes. Requests larger than this trigger a status code of 413. Keep in mind though that the maximum input size for the classification model is 120 words. Any request larger than this will be split into 120-word sized parts and counted seperately. If you are hitting the limit of the free tier, a status code of 401 will be issued.
In practice, you don't need to think about the timing in between requests, as small bursts of excessive requests are still being processed by the endpoint. The exception to this is bulk processing, where you should implement a 100ms pause in between requests.
In case you want to build a custom model with us, this is the specification for the training data.
We largely follow the annotation guidelines of the GermEval Shared Task on the Identification of Offensive Language as described e.g. in the Overview of the GermEval 2018 Shared Task on the Identification of Offensive Language. We implement Task 1: Coarse-grained Binary Classification, where postings are labeled as either
OTHER, and optionally Task 2: Fine-grained 4-way Classification, where postings are labeled as either
OTHER, and extend it by another class, namely
The data should be placed in a UTF-8 encoded plain text file. One training example per line, in the following format:
<TEXT> tab <LABEL-TASK-I> tab <LABEL-TASK-II>
Line breaks in the text should be replaced with
Language code. Possible values are
Model identifier. Possible values are
List of scores
Request Entity Too Large
Too Many Requests
- "text": "string"
- "scores": [