API Documentation

API de Detección de PDF con IA

Documentación completa para integrar la API de detección de PDF con IA de TruthScan en sus aplicaciones.

Pruébala sin código visitando nuestro endpoint FastAPI: https://detect-text.truthscan.com/docs

Autenticación

TruthScan usa claves de API para permitir el acceso a la API. Puede obtener su clave de API en la parte superior de la página en nuestro portal de desarrolladores.

Para solicitudes de URL de carga prefirmada (`GET /get-presigned-url`), incluya su clave de API en el encabezado `apikey`.

Para solicitudes de detección de PDF (`POST /detect-pdf`), incluya su clave de API en el cuerpo JSON como `key`.

Debe reemplazar YOUR API KEY GOES HERE con su clave de API personal.

Detector de PDF

El detector de PDF analiza archivos PDF cargados en busca de huellas de generación por IA usando metadatos PDF (`/Creator`, `/Producer`). Los PDF deben subirse primero al almacenamiento de objetos y luego enviarse para procesamiento asíncrono. Consulte `/query` hasta que `status` sea `done`.

Flujo de trabajo

`GET /get-presigned-url` con un nombre de archivo `.pdf` y su clave API en el encabezado `apikey`.
`PUT` de los bytes del PDF a la `presigned_url` devuelta.
`POST /detect-pdf` con la `url` pública del objeto y su `key` API (`document_type` se establece automáticamente en PDF).
`POST /query` con el `id` del documento devuelto hasta que finalice el procesamiento.

Límites de archivo

Los archivos PDF deben ser `.pdf`, de como máximo 2 MB y accesibles en la `url` enviada. Otros tipos de archivo se rechazan en este flujo.

Deducción de créditos

La detección de PDF deduce 1.000 créditos por página. Un PDF de 5 páginas consume 5.000 créditos. Verifique su saldo con `/check-user-credits` antes de enviar documentos grandes.

Obtener una URL de carga preautorizada

Solicite una URL de carga preautorizada antes de enviar un PDF para detección.

Encabezados

Incluya su clave API en el encabezado `apikey`.

GET https://ai-detect.undetectable.ai/get-presigned-url

Ejemplo de solicitud

curl -X 'GET' \
  'https://ai-detect.undetectable.ai/get-presigned-url?file_name=report.pdf&expiration=3600' \
  -H 'accept: application/json' \
  -H 'apikey: YOUR-API-KEY-GOES-HERE'

Ejemplo de respuesta

{
    "status": "success",
    "presigned_url": "https://...digitaloceanspaces.com/...?X-Amz-Algorithm=...",
    "file_path": "userId_20250604120000_report.pdf"
}

Subir el PDF

Use la presigned_url proporcionada para subir su PDF mediante una solicitud PUT.

Ejemplo de solicitud

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_report.pdf...' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@report.pdf' # Attachment

Detectar PDF

Envíe un PDF que ya se haya subido al almacenamiento de objetos. Este endpoint encola el análisis de metadatos y, opcionalmente, la detección de IA del texto.

Umbral

Para trabajos PDF (modelo: `pdf_metadata_detector`), `result` es siempre 100.0 (huella detectada → `label`: "AI") o 0.0 (sin huella → `label`: "Human"). Los umbrales 50/60 humano/IA solo aplican a la detección de texto (modelo: `xlm_ud_detector`).

Campos de respuesta

Consulte `/query` para el documento. Para trabajos PDF (modelo: `pdf_metadata_detector`), `result_details` contiene `prediction`, `rule`, `base_category` y `basic_source` en el nivel superior. Los valores creator/producer del PDF no se devuelven; se usan internamente y se reflejan en `rule` cuando coincide un patrón. `service_type` es siempre `detector`, y `model` permanece `pdf_metadata_detector` durante todo el trabajo.

POST https://ai-detect.undetectable.ai/detect-pdf

Ejemplo de solicitud

curl -X 'POST' \
  'https://ai-detect.undetectable.ai/detect-pdf' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://your-bucket.region.digitaloceanspaces.com/userId_20250604120000_report.pdf",
  "key": "YOUR-API-KEY-GOES-HERE",
  "retry_count": 0
}'

Parámetros opcionales

Pase `"id"` para proporcionar su propio UUID de documento (no debe existir ya).
Pase `"generate_analysis_details": true` para solicitar análisis profundo del texto cuando se ejecute IA de texto (mismo comportamiento que `/detect` de texto).
También puede usar `POST /detect` con `"document_type": "File"` para el mismo comportamiento.

Ejemplo de respuesta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "pdf_metadata_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

La respuesta contiene el ID de documento asignado por el servidor. Use `POST /query` para consultar resultados. El tiempo típico es de unos segundos para trabajos solo de metadatos; los trabajos que también ejecutan IA de texto pueden tardar más según el recuento de palabras extraídas.

Consulta

Consulte el estado y los resultados de detección PDF por ID de documento (mismo endpoint que la detección de texto).

POST https://ai-detect.undetectable.ai/query

Ejemplo de solicitud

curl -X 'POST' \
  'https://ai-detect.undetectable.ai/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "DOCUMENT-ID-GOES-HERE"
}'

Ejemplo de respuesta (IA detectada en metadatos)

{
    "id": "49b5a390-2285-47fe-a161-303b4e22406f",
    "model": "pdf_metadata_detector",
    "status": "done",
    "result": 100.0,
    "result_details": {
        "prediction": "Grok",
        "rule": "PyMuPDF - Creator: Grok xAI",
        "base_category": "Possibly AI Generated/Edited",
        "basic_source": "Grok"
    },
    "result_categories": null,
    "source_details": {
        "source": "Grok",
        "confidence": null,
        "credits_deducted": 1000
    },
    "retry_count": 0,
    "label": "AI"
}

Cuando también se ejecuta IA de texto, `model` puede ser `xlm_ud_detector`, `result_details` incluye puntuaciones del detector y `pdf_metadata`, y `source_details` puede incluir atribución combinada de metadatos/texto.

Errores

La mayoría de los errores serán por parámetros incorrectos enviados a la API. Verifique nuevamente los parámetros de cada llamada de API para asegurarse de que esté formateado correctamente e intente ejecutar el código de ejemplo proporcionado.

Los códigos de error genéricos que usamos se ajustan al estándar REST:

Código de Error	Significado
400	Bad Request -- Su solicitud es inválida.
403	Prohibido -- La clave de API no es válida o no hay créditos suficientes (1.000 por página del PDF).
404	Not Found -- El recurso especificado no existe.
405	Method Not Allowed -- Intentó acceder a un recurso con un método inválido.
406	Not Acceptable -- Solicitó un formato que no es JSON.
410	Gone -- El recurso en este endpoint ha sido eliminado.
422	Invalid Request Body -- El cuerpo de su solicitud está formateado incorrectamente o es inválido o tiene parámetros faltantes.
429	Too Many Requests -- ¡Está enviando demasiadas solicitudes! ¡Reduzca la velocidad!
500	Internal Server Error -- Tuvimos un problema con nuestro servidor. Intente nuevamente más tarde.
503	Service Unavailable -- Estamos temporalmente fuera de línea para mantenimiento. Intente nuevamente más tarde.

¿Necesita Ayuda?

Para obtener más información sobre cómo usar nuestra API o para soporte técnico, contáctenos.

Contáctenos

API Frequently Asked Questions

Find answers to the most common questions about our AI PDF detection API.