API Documentation
ISO 27001SOC 2 CertifiedGDPR Compliant

API de Detecção de PDF por IA

Documentação completa para integrar a API de detecção de PDF por IA da TruthScan em suas aplicações.

Teste a API sem código visitando nosso endpoint FastAPI: https://detect-text.truthscan.com/docs

Preços e créditos

A detecção de PDF deduz 1.000 créditos por página (ex.: um PDF de 5 páginas usa 5.000 créditos).

Verifique seu saldo com GET /check-user-credits. Ver planos de preços

Autenticação

A TruthScan usa chaves de API para permitir o acesso à API. Você pode obter sua chave de API no topo da página em nosso portal de desenvolvedores.

Para solicitações de URL de upload pré-assinada (`GET /get-presigned-url`), inclua sua chave de API no cabeçalho `apikey`.

Para solicitações de detecção de PDF (`POST /detect-pdf`), inclua sua chave de API no corpo JSON como `key`.

Você deve substituir YOUR API KEY GOES HERE pela sua chave de API pessoal.

Detector de PDF

O detector de PDF analisa arquivos PDF enviados de forma assíncrona. Os PDFs devem ser enviados primeiro ao armazenamento de objetos e depois submetidos via `/detect-pdf`. Consulte `/query` até que `status` seja `done`.

Três versões do detector estão disponíveis. Cada uma responde a uma pergunta diferente, escolha a que corresponde ao seu caso de uso (ou execute v1 e v3/v4 no mesmo arquivo enviando duas vezes com valores diferentes de `model`):

  • v1: pdf_detector/v1

    Detecta se o PDF foi gerado por uma ferramenta de IA nos metadados PDF.

  • v3: pdf_detector/v3

    Verifica edições digitais e sinais de documentos gerados por IA.

  • v4: pdf_detector/v4 (padrão / mais recente)

    Versão mais recente do detector de adulteração com desempenho geral aprimorado e recomendada para novas integrações.

Seleção de modelo

  • pdf_detector: Omita `model`, ou envie `pdf_detector`, para usar a versão mais recente (atualmente `pdf_detector/v4`).
  • pdf_detector/v1: Envie `model: pdf_detector/v1` para detecção de metadados de geração por IA.
  • pdf_detector/v3: Envie `model: pdf_detector/v3` para fixar a v3.
  • pdf_detector/v4: Envie `model: pdf_detector/v4` para fixar a v4 explicitamente.
  • model: Qualquer outro valor de `model` retorna 400 Bad Request.

Fluxo de trabalho

  • `GET /get-presigned-url` com um nome de arquivo `.pdf` e sua chave de API no cabeçalho `apikey`.
  • `PUT` dos bytes do PDF para o `presigned_url` retornado.
  • `POST /detect-pdf` com a `url` pública do objeto, sua `key` de API e um `model` opcional.
  • `POST /query` com o `id` do documento retornado até a conclusão do processamento.

Limites de arquivo

Arquivos PDF devem ser `.pdf`, ter no máximo 2 MB e estar acessíveis na `url` enviada.

Dedução de créditos

A detecção de PDF deduz 1.000 créditos por página. Um PDF de 5 páginas consome 5.000 créditos. Verifique seu saldo com `/check-user-credits` antes de enviar documentos grandes.

Obter URL de upload pré-assinada

Solicite uma URL de upload pré-assinada antes de enviar um PDF para detecção.

Cabeçalhos

Inclua sua chave de API no cabeçalho `apikey`.

GET https://detect-text.truthscan.com/get-presigned-url

Exemplo de solicitação

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'

Envie o arquivo com um PUT para o `presigned_url` da resposta antes de chamar `/detect-pdf`.

Exemplo de resposta

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

Enviar o PDF

Use o presigned_url fornecido para enviar seu PDF via uma solicitação PUT.

Exemplo de solicitação

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

Envie um PDF que já foi carregado no armazenamento de objetos.

Corpo da solicitação

  • url (obrigatório): URL pública no armazenamento de objetos do PDF enviado.
  • key (obrigatório): Sua chave de API.
  • model: `pdf_detector/v1`, `pdf_detector/v3`, `pdf_detector/v4` ou `pdf_detector` (mais recente). O padrão é `pdf_detector/v4`.
POST https://detect-text.truthscan.com/detect-pdf

Exemplo de solicitação — padrão (v4 / mais recente)

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"
}'

Exemplo de solicitação — fixar v1 (metadados de geração 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"
}'

Exemplo de resposta

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

A resposta contém o ID do documento atribuído pelo servidor. Use `POST /query` para consultar os resultados. O tempo típico de conclusão é de alguns segundos.

Consulta

Consulte o status e os resultados da detecção de PDF por ID do documento (mesmo endpoint da detecção de texto). O formato da resposta depende de qual `model` foi usado no trabalho.

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

Exemplo de solicitação

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

Exemplo de resposta — v1 impressão digital 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" quando sinalizado; "No Tampering Detected" caso contrário.
  • result_details.prediction: Nome específico da ferramenta (ex.: "Grok", "ChatGPT"), "AI Generated" genérico ou "No Tampering Detected".
  • result_details.base_category: "Possibly AI Generated/Edited" ou "No Tampering Detected".
  • source_details.source: Fonte atribuída em uma detecção; null quando nenhuma impressão digital é encontrada.

Exemplo de resposta — v1 sem impressão digital 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
}

Exemplo de resposta — v3 adulteração estrutural 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."
    }
}

Exemplo de resposta — v3 nenhuma adulteração 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."
    }
}

Exemplo de resposta — v4 (mesmo formato que v3)

A v4 retorna o mesmo formato de resposta que a v3. O campo `model` mostrará `pdf_detector/v4`.

Campos v3 / v4

  • label: Reflete `structure.prediction`: "Tampered", "Suspicious" ou "Genuine".
  • result_details.structure.signals: Detalhamento do sinal `hidden`. Inclui `label`, `flagged`, `severity` e `findings` (com `changes` opcional mostrando valores antes/depois quando disponíveis).
  • result_details.detailed_explanation: Resumo em linguagem natural dos achados.

Níveis de veredito

  • Tampered: Evidência forte de manipulação de conteúdo ou origem gerada por IA.
  • Suspicious: Um ou mais sinais detectados, mas nenhum no nível de confiança mais alto.
  • Genuine: Nenhum sinal de adulteração detectado.

Níveis de severidade

Cada achado usa `"low"`, `"medium"` ou `"high"` para indicar confiança.

Erros

A maioria dos erros será de parâmetros incorretos sendo enviados para a API. Verifique novamente os parâmetros de cada chamada de API para garantir que esteja formatado corretamente e tente executar o código de exemplo fornecido.

Os códigos de erro genéricos que usamos estão em conformidade com o padrão REST:

Código de ErroSignificado
400Bad Request -- Sua solicitação é inválida.
403Proibido -- A chave de API é inválida ou não há créditos suficientes (1.000 por página do PDF).
404Not Found -- O recurso especificado não existe.
405Method Not Allowed -- Você tentou acessar um recurso com um método inválido.
406Not Acceptable -- Você solicitou um formato que não é JSON.
410Gone -- O recurso neste endpoint foi removido.
422Invalid Request Body -- O corpo da sua solicitação está formatado incorretamente ou inválido ou tem parâmetros ausentes.
429Too Many Requests -- Você está enviando muitas solicitações! Diminua a velocidade!
500Internal Server Error -- Tivemos um problema com nosso servidor. Tente novamente mais tarde.
503Service Unavailable -- Estamos temporariamente offline para manutenção. Tente novamente mais tarde.

Precisa de Ajuda?

Para mais informações sobre como usar nossa API ou para suporte técnico, entre em contato conosco.

Contate-nos

API Frequently Asked Questions

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