# 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.

Source : https://fileverity.com/fr/docs/grammar

`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.

**Requête: cURL**

```bash
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)"
```

**Requête: JavaScript**

```javascript
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();
```

**Requête: Python**

```python
import os
import uuid
import 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

**200 OK**

```json
{
  "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. |

> **Remarque.** 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 :

**Construire le texte corrigé: JavaScript**

```javascript
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("");
```

**Construire le texte corrigé: Python**

```python
corrected = text
for 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_units` est le nombre d’unités facturées et `usage.credits` le 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é](https://fileverity.com/fr/docs/security.md#retention). 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é](https://fileverity.com/fr/docs/security.md).

## 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`. |

> **Remarque.** 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](https://fileverity.com/fr/docs/idempotency.md).

