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.
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)"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()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
{ "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. |
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:
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"] :]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_unitses el número de unidades facturadas yusage.creditslos 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ó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. |
Envíe Idempotency-Key para que, si reintenta tras un tiempo de espera agotado, no se facture dos veces. Consulte Idempotencia.