API Documentation
ISO 27001SOC 2 CertifiedGDPR Compliant

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

Precios y créditos

La detección de PDF deduce 1.000 créditos por página (p. ej., un PDF de 5 páginas usa 5.000 créditos).

Consulte su saldo con GET /check-user-credits. Ver planes de precios

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 de forma asíncrona. Los PDF deben subirse primero al almacenamiento de objetos y luego enviarse mediante `/detect-pdf`. Consulte `/query` hasta que `status` sea `done`.

Hay tres versiones del detector disponibles. Cada una responde a una pregunta diferente, elija la que coincida con su caso de uso (o ejecute v1 y v3/v4 en el mismo archivo enviándolo dos veces con distintos valores de `model`):

  • v1: pdf_detector/v1

    Detecta si el PDF fue generado por una herramienta de IA en los metadatos PDF.

  • v3: pdf_detector/v3

    Comprueba ediciones digitales y señales de documentos generados por IA.

  • v4: pdf_detector/v4 (predeterminado / más reciente)

    Versión más reciente del detector de manipulación con rendimiento general mejorado y recomendada para nuevas integraciones.

Selección de modelo

  • pdf_detector: Omita `model`, o envíe `pdf_detector`, para usar la versión más reciente (actualmente `pdf_detector/v4`).
  • pdf_detector/v1: Envíe `model: pdf_detector/v1` para detección de metadatos de generación por IA.
  • pdf_detector/v3: Envíe `model: pdf_detector/v3` para fijar v3.
  • pdf_detector/v4: Envíe `model: pdf_detector/v4` para fijar v4 explícitamente.
  • model: Cualquier otro valor de `model` devuelve 400 Bad Request.

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, su `key` API y un `model` opcional.
  • `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.

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://detect-text.truthscan.com/get-presigned-url

Ejemplo de solicitud

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

Suba el archivo con un PUT a la `presigned_url` de la respuesta antes de llamar a `/detect-pdf`.

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'

Detectar PDF

Envíe un PDF que ya se haya subido al almacenamiento de objetos.

Cuerpo de la solicitud

  • url (obligatorio): URL pública en almacenamiento de objetos del PDF subido.
  • key (obligatorio): Su clave API.
  • model: `pdf_detector/v1`, `pdf_detector/v3`, `pdf_detector/v4` o `pdf_detector` (más reciente). El valor predeterminado es `pdf_detector/v4`.
POST https://detect-text.truthscan.com/detect-pdf

Ejemplo de solicitud — predeterminado (v4 / más reciente)

curl -X 'POST' \
  'https://detect-text.truthscan.com/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"
}'

Ejemplo de solicitud — fijar v1 (metadatos de generación por IA)

curl -X 'POST' \
  'https://detect-text.truthscan.com/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",
  "model": "pdf_detector/v1"
}'

Ejemplo de respuesta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "pdf_detector/v4",
    "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 de finalización es de unos segundos.

Consulta

Consulte el estado y los resultados de detección PDF por ID de documento (mismo endpoint que la detección de texto). El formato de respuesta depende del `model` usado en el trabajo.

POST https://detect-text.truthscan.com/query

Ejemplo de solicitud

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

Ejemplo de respuesta — v1 huella de IA encontrada

{
    "id": "077eaa29-db75-4266-8eae-8a49d41c25ad",
    "model": "pdf_detector/v1",
    "status": "done",
    "label": "Tampering Detected",
    "result_details": {
        "prediction": "Grok",
        "base_category": "Possibly AI Generated/Edited"
    },
    "result_categories": null,
    "source_details": {
        "source": "Grok",
        "confidence": null,
        "credits_deducted": null
    },
    "retry_count": 0
}

Campos v1

  • label: "Tampering Detected" cuando se marca; "No Tampering Detected" en caso contrario.
  • result_details.prediction: Nombre específico de herramienta (p. ej. "Grok", "ChatGPT"), "AI Generated" genérico o "No Tampering Detected".
  • result_details.base_category: "Possibly AI Generated/Edited" o "No Tampering Detected".
  • source_details.source: Fuente atribuida en una coincidencia; null cuando no se encuentra huella.

Ejemplo de respuesta — v1 sin huella de IA

{
    "id": "077eaa29-db75-4266-8eae-8a49d41c25ad",
    "model": "pdf_detector/v1",
    "status": "done",
    "label": "No Tampering Detected",
    "result_details": {
        "prediction": "No Tampering Detected",
        "base_category": "No Tampering Detected"
    },
    "result_categories": null,
    "source_details": null,
    "retry_count": 0
}

Ejemplo de respuesta — v3 manipulación estructural detectada

{
    "id": "5395e0d8-41d6-4e30-add7-97b8a7ffbbc9",
    "model": "pdf_detector/v3",
    "status": "done",
    "label": "Tampered",
    "result_details": {
        "status": "ok",
        "structure": {
            "prediction": "Tampered",
            "rule": { "hidden": "high" },
            "max_severity": "high",
            "signals_flagged": 1,
            "signals": {
                "hidden": {
                    "label": "Hidden Text",
                    "flagged": true,
                    "severity": "high",
                    "findings": [
                        {
                            "severity": "high",
                            "detail": "Invisible or off-page text detected on page 1."
                        }
                    ]
                }
            }
        },
        "detailed_explanation": "Hidden text was found on page 1 that is not visible in the rendered document."
    }
}

Ejemplo de respuesta — v3 sin manipulación detectada (Genuine)

{
    "id": "5395e0d8-41d6-4e30-add7-97b8a7ffbbc9",
    "model": "pdf_detector/v3",
    "status": "done",
    "label": "Genuine",
    "result_details": {
        "status": "ok",
        "structure": {
            "prediction": "Genuine",
            "rule": {},
            "max_severity": null,
            "signals_flagged": 0,
            "signals": {
                "hidden": { "label": "Hidden Text", "flagged": false, "severity": null, "findings": [] }
            }
        },
        "detailed_explanation": "No AI-generation or tampering fingerprints were detected; the PDF looks clean."
    }
}

Ejemplo de respuesta — v4 (mismo formato que v3)

v4 devuelve el mismo formato de respuesta que v3. El campo `model` mostrará `pdf_detector/v4`.

Campos v3 / v4

  • label: Refleja `structure.prediction`: "Tampered", "Suspicious" o "Genuine".
  • result_details.structure.signals: Desglose de la señal `hidden`. Incluye `label`, `flagged`, `severity` y `findings` (con `changes` opcional que muestra valores antes/después cuando están disponibles).
  • result_details.detailed_explanation: Resumen en lenguaje natural de los hallazgos.

Niveles de veredicto

  • Tampered: Evidencia sólida de manipulación de contenido u origen generado por IA.
  • Suspicious: Una o más señales detectadas, pero ninguna en el nivel de confianza más alto.
  • Genuine: No se detectaron señales de manipulación.

Niveles de severidad

Cada hallazgo usa `"low"`, `"medium"` o `"high"` para indicar confianza.

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