API de humanizador de IA: Humanizer API v2 y Detector API

La API de humanizador de IA de Academic Humanizer tiene dos endpoints REST para desarrolladores e instituciones: POST /api/v2/external/humanize, que devuelve el texto humanizado con los cambios a nivel de frase, y POST /api/v2/external/detector, que devuelve una evaluación de detección de IA para hasta 100.000 caracteres. Ambos usan una clave de API del lado del servidor y consumen el mismo saldo de créditos que tu cuenta.

Este artículo explica para quién es la API, cómo funcionan la autenticación y el control de acceso, qué devuelve cada endpoint y cómo se cuentan los créditos. La referencia completa está en /docs.

Para quién es la API del humanizador de IA

El editor web es ideal para investigadores individuales. La API es para productos y equipos que trabajan con texto académico en volumen o dentro de su propia interfaz:

• Plataformas de escritura que quieren ofrecer un paso de humanización dentro de su propio editor.
• Herramientas de LMS y materiales de curso que necesitan una señal de detección de IA como un elemento más de un proceso de revisión humana, no como un veredicto automático.
• Servicios de edición y corrección que pasan los borradores de sus clientes por una primera revisión uniforme antes de que los lea un editor.
• Oficinas de investigación que quieren revisar por lotes textos de solicitudes de financiación o informes.

Si tu uso afecta a trabajos de estudiantes, diséñalo para que las decisiones finales las tomen personas. La salida de un detector es una evidencia que hay que revisar, y nuestro artículo sobre qué tener en cuenta antes de cuestionar la autoría de un estudiante explica por qué.

Autenticación, listas de IP permitidas y límites de uso

Crea una clave en /api con la sesión iniciada. La clave se muestra una sola vez, al crearla, y Academic Humanizer solo guarda un hash de ella, así que cópiala directamente en tu gestor de secretos o en una variable de entorno del servidor. Nunca la incluyas en código de navegador o de aplicaciones móviles.

Envía la clave en la cabecera X-API-Key. Es la cabecera que recomienda la documentación; el servidor también acepta la clave como token bearer en la cabecera Authorization.

Después, cada solicitud pasa por unas comprobaciones antes de procesar ningún texto.

1. Comprobación de la claveLa clave debe existir y estar activa, y la cuenta asociada también debe estar activa.
2. Lista de IP permitidasEn modo restringido, solo se aceptan solicitudes de las IP o rangos CIDR que hayas indicado.
3. Límite de usoLas solicitudes que superan el límite por segundo de la clave se rechazan con HTTP 429.
4. ProcesamientoEl texto se humaniza o se analiza, y se comprueban los créditos frente a tu saldo.
5. Resultado guardadoEl resultado se guarda en tu cuenta y se devuelve como JSON.

El acceso por IP tiene dos modos: público, en el que cualquier IP puede llamar con una clave válida, y restringido, en el que solo pueden hacerlo las IP o bloques CIDR indicados. Merece la pena activar el modo restringido en cualquier servidor de producción con una dirección de salida fija. El límite predeterminado es de 10 solicitudes por segundo.

El endpoint Humanize

El cuerpo de la solicitud es un JSON con un campo obligatorio, originalContent, y un campo opcional, researchField. Si envías un campo de investigación, debe ser uno de los nombres admitidos: Arts and Humanities, Social Sciences, Business and Economics, Engineering, Natural Sciences o Medical and Health Sciences. Omítelo o envía null si no lo necesitas.

curl -X POST https://academichumanizer.ai/api/v2/external/humanize   -H "Content-Type: application/json"   -H "X-API-Key: YOUR_API_KEY"   -d '{"originalContent": "Paste the paragraph or abstract to humanize here.", "researchField": "Natural Sciences"}'

Una llamada correcta devuelve HTTP 201 con un cuerpo JSON que contiene:

• humanizedText: el texto reescrito completo.
• changedCount: cuántas frases se cambiaron.
• sentences: un array de entradas a nivel de frase, cada una con sus posiciones de inicio y fin en tu texto original, la frase de origen, la frase humanizada y un indicador changed. El array puede estar vacío.

El ID del resultado guardado se devuelve en la cabecera de respuesta X-Humanizer-Id, para que puedas vincular una solicitud de tu sistema con el resultado guardado en la cuenta del usuario. Ten en cuenta que changed indica si una frase se reescribió; no es un veredicto de detección de IA. Para eso, usa el endpoint Detector.

Las posiciones de las frases facilitan mostrar un diff en tu propia interfaz: resalta los tramos cambiados y deja que el usuario acepte o edite cada uno. Los usuarios deben revisar cada resultado antes de usarlo, ya que la reescritura con IA puede introducir errores o desplazar el sentido.

El endpoint Detector

El endpoint Detector recibe un único campo obligatorio, text, de hasta 100.000 caracteres. Devuelve el estado del análisis, el número de caracteres, el tiempo transcurrido, una evaluación global del documento, los resultados de los detectores y creditUsed. Aquí no se usan campos de investigación.

Un patrón habitual es llamar primero a Detector, mostrar al usuario qué fragmentos presentan señales y llamar a Humanize solo para las secciones que elija. Así se reducen al mínimo tanto el coste como los cambios.

Cómo se cuentan los créditos de la API

Ambos endpoints consumen créditos de la cuenta propietaria de la clave. Los dos endpoints cuentan de forma distinta.

Humanize cuesta 1 crédito por cada 500 caracteres, redondeando hacia arriba por solicitud, y solo se cobra cuando se guarda un resultado completo. Detector cuesta 1 crédito por cada 5.000 caracteres, redondeando hacia arriba. Si el saldo es insuficiente, la solicitud falla con un error de créditos insuficientes en lugar de devolver un resultado parcial. Los planes y paquetes se describen en cómo funcionan los créditos y los precios, y los precios actuales están en /pricing.

Errores que debes gestionar

Los cuerpos de error incluyen un código breve legible por máquina, así que ramifica según el código y no según el texto del mensaje.

Preguntas frecuentes

¿Cómo consigo una clave de API?

Inicia sesión y abre /api. Crea una clave, cópiala de inmediato (solo se muestra una vez) y guárdala en tu servidor.

¿Puedo restringir qué servidores usan mi clave?

Sí. Cambia el acceso por IP al modo restringido e indica las IP o rangos CIDR que pueden llamar a la API. Las solicitudes desde cualquier otro lugar se rechazan con HTTP 403.

¿Hay un plan gratuito para la API?

La API usa los mismos créditos que la aplicación web. Las cuentas nuevas reciben 10 créditos gratis una sola vez, suficientes para probar el endpoint Humanize con algunos fragmentos cortos.

¿Frente a qué detectores se comprueba el resultado?

Academic Humanizer se valida frente a Turnitin, GPTZero, ZeroGPT, Copyleaks, Sapling y Originality.ai. Como con cualquier herramienta, los resultados varían según el detector y no se garantiza ningún resultado.

Desarrollar con Academic Humanizer

Si tu producto ya trabaja con manuscritos, resúmenes o trabajos de curso, la API te permite añadir un paso de humanización o una comprobación de detección sin mandar a los usuarios a otro sitio. Empieza con una clave de prueba, pasa unos cuantos párrafos reales por ambos endpoints y lee la referencia completa en /docs antes de pasar a producción.