Ir al contenido

Documentación de la API de Fileverity

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.

Ver como MarkdownActualizado el 2026-11-16

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.

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

Cuerpo de la solicitud

CampoTipoObligatorioDescripción
textcadenaSíTexto sin formato de al menos 20 palabras y como máximo 30.000 caracteres.
modelcadenaNoValor predeterminado: grammar-1. Acepta el ID del modelo o el ID de su versión fechada grammar-1-2026-11-16.
languagecadena o nullNoCó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

{  "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  }}
CampoTipoDescripción
idcadenaID de la comprobación, con el prefijo tgr_.
objectcadenaSiempre text.grammar.
createdenteroMarca de tiempo Unix.
modelcadenaVersión fechada que produjo el resultado.
livemodebooleanofalse para las claves de prueba.
languagecadenaEl idioma utilizado: el que usted envió o el detectado.
wordsenteroPalabras del texto.
editsmatrizCorrecciones sugeridas, en el orden del texto. Cada una tiene start, end (excluido), original, replacement, category y message. Las ediciones nunca se solapan.
countsobjetoNúmero de ediciones por categoría: spelling, grammar, punctuation, word, style.
versioncadenaVersión del método de revisión. Compare los resultados solo dentro de una misma versión.
usageobjetocharacters evaluados, billed_units facturadas y credits descontados.

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
spellingUna palabra mal escrita.
grammarConcordancia, tiempos verbales, artículos, preposiciones, orden de las palabras y casos similares.
punctuationPuntuación y uso de mayúsculas.
wordUna palabra incorrecta o confundida con otra.
styleUna 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:

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

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

Errores

CódigoEstadoCausa
text_too_short400Menos de 20 palabras.
text_too_long413Más de 30.000 caracteres. Divida el texto en varias solicitudes.
unsupported_language400El 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_type415El cuerpo no se envía como application/json.
invalid_json, missing_parameter, invalid_parameter400El cuerpo no es un objeto JSON, falta text, un campo tiene un tipo incorrecto o se envió un campo desconocido.
model_not_found404El model es desconocido.
plan_required403El espacio de trabajo aún no ha comprado créditos. Compre un paquete de créditos en la Consola.
insufficient_balance402El saldo no cubre la solicitud.
spend_limit_reached402La clave alcanzó su límite de gasto mensual.
idempotency_mismatch, idempotency_in_progress409La Idempotency-Key se usó con un cuerpo distinto, o su primera solicitud sigue en curso.
service_unavailable, analysis_failed503, 502El servicio de revisión gramatical no está disponible temporalmente. No se cobra; reintente. service_unavailable incluye una cabecera retry-after.

Envíe Idempotency-Key para que, si reintenta tras un tiempo de espera agotado, no se facture dos veces. Consulte Idempotencia.