Zum Inhalt springen

Fileverity-API-Dokumentation

Grammatikprüfungen

Prüfen Sie reinen Text mit POST /text/grammar auf Fehler bei Rechtschreibung, Grammatik, Zeichensetzung und Wortwahl. Felder von Anfrage und Antwort, Kategorien, Offsets, Limits und Abrechnung.

Als Markdown ansehenAktualisiert am 2026-11-16

POST /text/grammar prüft einen Text mit grammar-1. Der Endpunkt liefert jeden Korrekturvorschlag mit seiner Position im Text, einer Kategorie und einer kurzen Erläuterung. Der Aufruf ist synchron: Das Ergebnis steht in der Antwort.

Die Prüfung funktioniert für Englisch, Spanisch, Französisch und Arabisch. Speichern Sie einen Text mit mindestens 20 Wörtern als essay.txt, um die Beispiele auszuführen.

curl https://api.fileverity.com/v1/text/grammar \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 2c7d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e21" \  -d "$(jq -Rs '{text: ., language: "en"}' essay.txt)"

Anfragetext

FeldTypErforderlichBeschreibung
textstringJaReiner Text mit mindestens 20 Wörtern und höchstens 30.000 Zeichen.
modelstringNeinStandard ist grammar-1. Akzeptiert wird die Modell-ID oder ihre Snapshot-ID grammar-1-2026-11-16.
languagestring oder nullNeinISO-639-1-Code: en, es, fr, ar. Wird bei Auslassung automatisch erkannt; senden Sie ihn, wenn der Text mehrere Sprachen mischt.

Unbekannte Felder werden mit invalid_parameter abgelehnt. Ein Text in einer anderen Sprache oder mit nicht erkennbarer Sprache liefert unsupported_language.

Antwort

{  "id": "tgr_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "text.grammar",  "created": 1794787200,  "model": "grammar-1-2026-11-16",  "livemode": true,  "language": "en",  "words": 412,  "edits": [    {      "start": 118,      "end": 125,      "original": "recieve",      "replacement": "receive",      "category": "spelling",      "message": "The word is spelled receive."    },    {      "start": 402,      "end": 414,      "original": "has went",      "replacement": "has gone",      "category": "grammar",      "message": "The past participle of go is gone."    },    {      "start": 1170,      "end": 1175,      "original": "Their",      "replacement": "They're",      "category": "word",      "message": "They're is the contraction of they are."    },    {      "start": 1788,      "end": 1789,      "original": ",",      "replacement": ";",      "category": "punctuation",      "message": "Two complete sentences are joined with a comma."    }  ],  "counts": {    "spelling": 1,    "grammar": 1,    "punctuation": 1,    "word": 1,    "style": 0  },  "version": "2026.11-g1",  "usage": {    "characters": 2412,    "billed_units": 1,    "credits": 1  }}
FeldTypBeschreibung
idstringID der Prüfung mit dem Präfix tgr_.
objectstringImmer text.grammar.
createdintegerUnix-Zeitstempel.
modelstringSnapshot, der das Ergebnis erzeugt hat.
livemodebooleanfalse bei Testschlüsseln.
languagestringDie verwendete Sprache: die von Ihnen gesendete oder die erkannte.
wordsintegerWörter im Text.
editsarrayKorrekturvorschläge in Textreihenfolge. Jeder enthält start, end (exklusiv), original, replacement, category und message. Änderungen überlappen sich nie.
countsobjectAnzahl der Änderungen pro Kategorie: spelling, grammar, punctuation, word, style.
versionstringVersion des Korrekturverfahrens. Vergleichen Sie Ergebnisse nur innerhalb einer Version.
usageobjectcharacters ausgewertet, billed_units berechnet und credits belastet.

Die Vorschläge stammen von einem Sprachmodell. Sie können falsch oder unnötig sein, besonders bei Namen, Fachbegriffen und bewusstem Stil. Zeigen Sie sie deshalb einer Person als Vorschläge an, statt sie unbemerkt anzuwenden. Die Prüfung arabischer Texte ist neu und wird noch evaluiert.

Kategorien

`category`Bedeutung
spellingEin falsch geschriebenes Wort.
grammarKongruenz, Zeitform, Artikel, Präpositionen, Wortstellung und Ähnliches.
punctuationZeichensetzung sowie Groß- und Kleinschreibung.
wordEin falsches oder verwechseltes Wort.
styleEin Lesbarkeitsvorschlag und kein Fehler. Es werden nur wenige zurückgegeben, und nur dort, wo ein Satz eindeutig schwer lesbar ist.

Die Änderungen anwenden

start und end sind Offsets in den Text, den Sie gesendet haben, gezählt in Unicode-Codepoints, nicht in Bytes und nicht in UTF-16-Einheiten. original ist der Text dazwischen. Um den korrigierten Text zu erzeugen, ersetzen Sie jeden Bereich durch replacement und gehen dabei von der letzten zur ersten Änderung vor, damit die früheren Offsets gültig bleiben, oder zerlegen Sie den Text zuerst in Codepoints:

const points = Array.from(text);const out = [];let at = 0;for (const edit of check.edits) {  out.push(points.slice(at, edit.start).join(""), edit.replacement);  at = edit.end;}out.push(points.slice(at).join(""));const corrected = out.join("");

Python-Strings werden bereits nach Codepoints indiziert.

Abrechnung

  • Eine Grammatikprüfung kostet 1 Credit pro 5.000 Zeichen, gezählt in Unicode-Codepoints. Jede Anfrage wird auf ganze Einheiten aufgerundet, mindestens eine Einheit.
  • usage.billed_units ist die Anzahl der berechneten Einheiten und usage.credits die berechneten Credits. Beispiel: 2.412 Zeichen ergeben 1 Einheit, 1 Credit.
  • Anfragen, die vor der Auswertung abgelehnt werden, werden nicht berechnet: ungültige Parameter, zu kurzer oder zu langer Text, nicht unterstützte Sprachen und Ähnliches. Eine Prüfung, die im Dienst fehlschlägt (service_unavailable), wird freigegeben und nicht berechnet.
  • Reichen die Credits nicht aus, wird insufficient_balance (402) zurückgegeben. Über die API stehen Grammatikprüfungen Workspaces offen, die Credits gekauft haben, und verbrauchen immer Credits; auf der Website und in der Konsole gehören sie zum Pro-Tarif.

Was gespeichert wird

Der Text wird für die Dauer der Prüfung über Vercel AI Gateway an ein Sprachmodell gesendet. Eine Kopie des Textes wird bis zu 3 Jahre lang verschlüsselt aufbewahrt, um die Erkennungsmodelle von Fileverity zu trainieren und zu bewerten; siehe Datenaufbewahrung und Sicherheit. Fileverity speichert das Ergebnis (die Änderungen mit ihren kurzen Original- und Ersatzfragmenten, Zählwerte und die Nutzung) 7 Tage lang, damit die Konsole es anzeigen und die Nutzung abgerechnet und geprüft werden kann. Eine wiederholte Anfrage mit demselben Idempotency-Key erhält 24 Stunden lang das gespeicherte Ergebnis. Grammatikprüfungen sind synchron: Sie erscheinen nicht in GET /analyses und senden keine Webhook-Ereignisse. Testschlüssel speichern nichts. Siehe Datenaufbewahrung und Sicherheit.

Fehler

CodeStatusUrsache
text_too_short400Weniger als 20 Wörter.
text_too_long413Mehr als 30.000 Zeichen. Teilen Sie den Text auf mehrere Anfragen auf.
unsupported_language400Der Text ist nicht auf Englisch, Spanisch, Französisch oder Arabisch verfasst, oder seine Sprache konnte nicht erkannt werden. Senden Sie language, um eine Sprache festzulegen.
unsupported_media_type415Der Anfragetext wird nicht als application/json gesendet.
invalid_json, missing_parameter, invalid_parameter400Der Anfragetext ist kein JSON-Objekt, text fehlt, ein Feld hat den falschen Typ oder es wurde ein unbekanntes Feld gesendet.
model_not_found404Das model ist unbekannt.
plan_required403Der Workspace hat noch keine Credits gekauft. Kaufen Sie ein Credit-Paket in der Konsole.
insufficient_balance402Das Guthaben reicht für die Anfrage nicht aus.
spend_limit_reached402Der Schlüssel hat sein monatliches Ausgabenlimit erreicht.
idempotency_mismatch, idempotency_in_progress409Der Idempotency-Key wurde mit einem anderen Anfragetext verwendet, oder seine erste Anfrage läuft noch.
service_unavailable, analysis_failed503, 502Der Grammatikdienst ist vorübergehend nicht verfügbar. Es wird nichts berechnet; versuchen Sie es erneut. Bei service_unavailable enthält die Antwort den Header retry-after.

Senden Sie einen Idempotency-Key, damit ein erneuter Versuch nach einem Timeout nicht doppelt berechnet wird. Siehe Idempotenz.