Documentation de l’API Fileverity
Vérifications grammaticales
Vérifiez l’orthographe, la grammaire, la ponctuation et le choix des mots d’un texte brut avec POST /text/grammar. Champs de la requête et de la réponse, catégories, positions, limites et facturation.
POST /text/grammar vérifie un texte avec grammar-1. Il renvoie chaque correction suggérée avec sa position dans le texte, sa catégorie et une courte explication. L’appel est synchrone : le résultat figure dans la réponse.
Il fonctionne en anglais, espagnol, français et arabe. Enregistrez un texte d’au moins 20 mots sous le nom essay.txt pour exécuter les exemples.
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)"import { readFile } from "node:fs/promises";import { randomUUID } from "node:crypto"; const response = await fetch("https://api.fileverity.com/v1/text/grammar", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": randomUUID(), }, body: JSON.stringify({ text: await readFile("essay.txt", "utf8"), language: "en" }),});const check = await response.json();import osimport uuidimport requests response = requests.post( "https://api.fileverity.com/v1/text/grammar", headers={ "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4()), }, json={"text": open("essay.txt", encoding="utf-8").read(), "language": "en"},)check = response.json()Corps de la requête
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
text | chaîne | Oui | Texte brut d’au moins 20 mots et d’au plus 30 000 caractères. |
model | chaîne | Non | Valeur par défaut : grammar-1. Accepte l’ID de modèle ou son ID d’instantané grammar-1-2026-11-16. |
language | chaîne ou null | Non | Code ISO 639-1 : en, es, fr, ar. Détecté automatiquement si omis ; envoyez-le lorsque le texte mélange plusieurs langues. |
Les champs inconnus sont rejetés avec invalid_parameter. Un texte rédigé dans une autre langue, ou dont la langue ne peut pas être reconnue, renvoie unsupported_language.
Réponse
{ "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 }}| Champ | Type | Description |
|---|---|---|
id | chaîne | ID de la vérification, avec le préfixe tgr_. |
object | chaîne | Toujours text.grammar. |
created | entier | Horodatage Unix. |
model | chaîne | Instantané qui a produit le résultat. |
livemode | booléen | false pour les clés de test. |
language | chaîne | La langue utilisée : celle que vous avez envoyée, ou celle qui a été détectée. |
words | entier | Mots du texte. |
edits | tableau | Corrections suggérées dans l’ordre du texte. Chacune comporte start, end (exclu), original, replacement, category et message. Les corrections ne se chevauchent jamais. |
counts | objet | Nombre de corrections par catégorie : spelling, grammar, punctuation, word, style. |
version | chaîne | Version de la méthode de relecture. Ne comparez les résultats qu’au sein d’une même version. |
usage | objet | characters évalués, billed_units facturées et credits débités. |
Les suggestions proviennent d’un modèle de langage. Elles peuvent être erronées ou superflues, surtout pour les noms, les termes techniques et les choix de style assumés : présentez-les donc à une personne comme des suggestions plutôt que de les appliquer silencieusement. La vérification de l’arabe est récente et encore en cours d’évaluation.
Catégories
| `category` | Signification |
|---|---|
spelling | Un mot mal orthographié. |
grammar | Accord, temps, articles, prépositions, ordre des mots et cas similaires. |
punctuation | Ponctuation et majuscules. |
word | Un mot erroné ou confondu avec un autre. |
style | Une suggestion de lisibilité plutôt qu’une erreur. Seules quelques-unes sont renvoyées, uniquement lorsqu’une phrase est manifestement difficile à lire. |
Appliquer les corrections
start et end sont des positions dans le texte que vous avez envoyé, comptées en points de code Unicode, et non en octets ni en unités UTF-16. original est le texte compris entre les deux. Pour construire le texte corrigé, remplacez chaque plage par replacement en partant de la dernière correction vers la première afin que les positions précédentes restent valables, ou découpez d’abord le texte en points de code :
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("");corrected = textfor edit in reversed(check["edits"]): corrected = corrected[: edit["start"]] + edit["replacement"] + corrected[edit["end"] :]Les chaînes Python sont déjà indexées par point de code.
Facturation
- Une vérification grammaticale coûte 1 crédit par tranche de 5 000 caractères, comptés en points de code Unicode. Chaque requête est arrondie à l’unité supérieure, avec un minimum d’une unité.
usage.billed_unitsest le nombre d’unités facturées etusage.creditsle nombre de crédits débités. Exemple : 2 412 caractères comptent pour 1 unité, soit 1 crédit.- Les requêtes rejetées avant l’évaluation ne sont pas facturées : paramètres non valides, texte trop court ou trop long, langues non prises en charge, etc. Une vérification qui échoue au sein du service (
service_unavailable) est libérée et n’est pas facturée. - Un nombre de crédits insuffisant renvoie
insufficient_balance(402). Via l’API, les vérifications grammaticales sont ouvertes aux espaces de travail qui ont acheté des crédits et utilisent toujours des crédits ; sur le site et dans la Console, elles font partie de la formule Pro.
Ce qui est conservé
Le texte est envoyé à un modèle de langage via Vercel AI Gateway pendant la durée de la vérification. Une copie du texte est conservée chiffrée pendant 3 ans au plus pour entraîner et évaluer les modèles de détection de Fileverity ; voir Conservation des données et sécurité. Fileverity conserve le résultat (les corrections avec leurs courts fragments d’origine et de remplacement, les compteurs et l’utilisation) pendant 7 jours, afin que la Console puisse l’afficher et que l’utilisation puisse être facturée et auditée. Une nouvelle tentative avec la même Idempotency-Key reçoit le résultat enregistré pendant 24 heures. Les vérifications grammaticales sont synchrones : elles n’apparaissent pas dans GET /analyses et n’envoient pas d’événements webhook. Les clés de test n’enregistrent rien. Voir Conservation des données et sécurité.
Erreurs
| Code | Statut | Cause |
|---|---|---|
text_too_short | 400 | Moins de 20 mots. |
text_too_long | 413 | Plus de 30 000 caractères. Divisez le texte en plusieurs requêtes. |
unsupported_language | 400 | Le texte n’est pas rédigé en anglais, espagnol, français ou arabe, ou sa langue n’a pas pu être reconnue. Envoyez language pour en choisir une. |
unsupported_media_type | 415 | Le corps n’est pas envoyé en application/json. |
invalid_json, missing_parameter, invalid_parameter | 400 | Le corps n’est pas un objet JSON, text est absent, un champ a un type incorrect ou un champ inconnu a été envoyé. |
model_not_found | 404 | Le model est inconnu. |
plan_required | 403 | L’espace de travail n’a pas encore acheté de crédits. Achetez un pack de crédits dans la Console. |
insufficient_balance | 402 | Le solde ne permet pas de couvrir la requête. |
spend_limit_reached | 402 | La clé a atteint sa limite de dépense mensuelle. |
idempotency_mismatch, idempotency_in_progress | 409 | La Idempotency-Key a été utilisée avec un corps différent, ou sa première requête est encore en cours. |
service_unavailable, analysis_failed | 503, 502 | Le service de vérification grammaticale est temporairement indisponible. Aucune facturation ; réessayez. service_unavailable s’accompagne d’un en-tête retry-after. |
Envoyez une Idempotency-Key pour qu’une nouvelle tentative après un délai dépassé ne soit pas facturée deux fois. Voir Idempotence.