# Revisiones gramaticales

> Revise texto sin formato en busca de errores de ortografía, gramática, puntuación y elección de palabras con POST /text/grammar. Campos de la solicitud y la respuesta, categorías, posiciones, límites y facturación.

Fuente: https://fileverity.com/es/docs/grammar

`POST /text/grammar` revisa un texto con `grammar-1`. Devuelve cada corrección sugerida con su posición en el texto, una categoría y una explicación breve. Es síncrono: el resultado va en la respuesta.

Funciona en inglés, español, francés y árabe. Guarde un texto de 20 palabras o más como `essay.txt` para ejecutar los ejemplos.

**Solicitud: 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)"
```

**Solicitud: 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();
```

**Solicitud: 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()
```

## Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `text` | cadena | Sí | Texto sin formato de al menos 20 palabras y como máximo 30.000 caracteres. |
| `model` | cadena | No | Valor predeterminado: `grammar-1`. Acepta el ID del modelo o el ID de su versión fechada `grammar-1-2026-11-16`. |
| `language` | cadena o null | No | Código ISO 639-1: `en`, `es`, `fr`, `ar`. Se detecta automáticamente si se omite; envíelo cuando el texto mezcle idiomas. |

Los campos desconocidos se rechazan con `invalid_parameter`. Un texto en otro idioma, o cuyo idioma no se puede reconocer, devuelve `unsupported_language`.

## Respuesta

**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
  }
}
```

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `id` | cadena | ID de la comprobación, con el prefijo `tgr_`. |
| `object` | cadena | Siempre `text.grammar`. |
| `created` | entero | Marca de tiempo Unix. |
| `model` | cadena | Versión fechada que produjo el resultado. |
| `livemode` | booleano | `false` para las claves de prueba. |
| `language` | cadena | El idioma utilizado: el que usted envió o el detectado. |
| `words` | entero | Palabras del texto. |
| `edits` | matriz | Correcciones sugeridas, en el orden del texto. Cada una tiene `start`, `end` (excluido), `original`, `replacement`, `category` y `message`. Las ediciones nunca se solapan. |
| `counts` | objeto | Número de ediciones por categoría: `spelling`, `grammar`, `punctuation`, `word`, `style`. |
| `version` | cadena | Versión del método de revisión. Compare los resultados solo dentro de una misma versión. |
| `usage` | objeto | `characters` evaluados, `billed_units` facturadas y `credits` descontados. |

> **Nota.** Las sugerencias las genera un modelo de lenguaje. Pueden ser erróneas o innecesarias, sobre todo con nombres, términos técnicos y estilos deliberados, así que muéstrelas a una persona como sugerencias en lugar de aplicarlas sin avisar. La revisión en árabe es reciente y aún se está evaluando.

## Categorías

| `category` | Significado |
| --- | --- |
| `spelling` | Una palabra mal escrita. |
| `grammar` | Concordancia, tiempos verbales, artículos, preposiciones, orden de las palabras y casos similares. |
| `punctuation` | Puntuación y uso de mayúsculas. |
| `word` | Una palabra incorrecta o confundida con otra. |
| `style` | Una sugerencia de legibilidad, no un error. Solo se devuelven unas pocas y únicamente cuando una oración resulta claramente difícil de leer. |

## Aplicar las ediciones

`start` y `end` son posiciones en el texto que envió, medidas en puntos de código Unicode, no en bytes ni en unidades UTF-16. `original` es el texto comprendido entre ambas. Para construir el texto corregido, sustituya cada intervalo por `replacement`, empezando por la última edición y terminando por la primera para que las posiciones anteriores sigan siendo válidas, o divida antes el texto en puntos de código:

**Construir el texto corregido: 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("");
```

**Construir el texto corregido: Python**

```python
corrected = text
for edit in reversed(check["edits"]):
    corrected = corrected[: edit["start"]] + edit["replacement"] + corrected[edit["end"] :]
```

Las cadenas de Python ya se indexan por punto de código.

## Facturación

- Una revisión gramatical cuesta 1 crédito por cada 5000 caracteres, contados en puntos de código Unicode. Cada solicitud se redondea hacia arriba a unidades completas, con un mínimo de una unidad.
- `usage.billed_units` es el número de unidades facturadas y `usage.credits` los créditos descontados. Ejemplo: 2412 caracteres facturan 1 unidad, es decir, 1 crédito.
- Las solicitudes rechazadas antes de la evaluación no se cobran: parámetros no válidos, texto demasiado corto o demasiado largo, idiomas no admitidos y casos similares. Una comprobación que falla dentro del servicio (`service_unavailable`) se libera y no se cobra.
- Si no hay créditos suficientes, se devuelve `insufficient_balance` (402). A través de la API, las revisiones gramaticales están abiertas a los espacios de trabajo que han comprado créditos y siempre consumen créditos; en el sitio web y en la Consola forman parte del plan Pro.

## Qué se almacena

El texto se envía a un modelo de lenguaje a través de Vercel AI Gateway mientras dura la revisión. Se conserva una copia cifrada del texto durante un máximo de 3 años para entrenar y evaluar los modelos de detección de Fileverity; consulte [Conservación de datos y seguridad](https://fileverity.com/es/docs/security.md#retention). Fileverity conserva durante 7 días el resultado (las ediciones con sus breves fragmentos originales y de sustitución, los recuentos y el uso), para que la Consola pueda mostrarlo y el uso pueda facturarse y auditarse. Una solicitud repetida con la misma `Idempotency-Key` recibe el resultado guardado durante 24 horas. Las revisiones gramaticales son síncronas: no aparecen en `GET /analyses` y no envían eventos de webhook. Las claves de prueba no registran nada. Consulte [Conservación de datos y seguridad](https://fileverity.com/es/docs/security.md).

## Errores

| Código | Estado | Causa |
| --- | --- | --- |
| `text_too_short` | 400 | Menos de 20 palabras. |
| `text_too_long` | 413 | Más de 30.000 caracteres. Divida el texto en varias solicitudes. |
| `unsupported_language` | 400 | El texto no está en inglés, español, francés ni árabe, o no se pudo reconocer su idioma. Envíe `language` para elegir uno. |
| `unsupported_media_type` | 415 | El cuerpo no se envía como `application/json`. |
| `invalid_json`, `missing_parameter`, `invalid_parameter` | 400 | El cuerpo no es un objeto JSON, falta `text`, un campo tiene un tipo incorrecto o se envió un campo desconocido. |
| `model_not_found` | 404 | El `model` es desconocido. |
| `plan_required` | 403 | El espacio de trabajo aún no ha comprado créditos. Compre un paquete de créditos en la Consola. |
| `insufficient_balance` | 402 | El saldo no cubre la solicitud. |
| `spend_limit_reached` | 402 | La clave alcanzó su límite de gasto mensual. |
| `idempotency_mismatch`, `idempotency_in_progress` | 409 | La `Idempotency-Key` se usó con un cuerpo distinto, o su primera solicitud sigue en curso. |
| `service_unavailable`, `analysis_failed` | 503, 502 | El servicio de revisión gramatical no está disponible temporalmente. No se cobra; reintente. `service_unavailable` incluye una cabecera `retry-after`. |

> **Nota.** Envíe `Idempotency-Key` para que, si reintenta tras un tiempo de espera agotado, no se facture dos veces. Consulte [Idempotencia](https://fileverity.com/es/docs/idempotency.md).

