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

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 em busca de impressões digitais de geração por IA usando metadados PDF (`/Creator`, `/Producer`). Os PDFs devem ser enviados primeiro ao armazenamento de objetos e depois submetidos para processamento assíncrono. Consulte `/query` até que `status` seja `done`.

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 e sua `key` de API (`document_type` é definido automaticamente como PDF).
  • `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. Outros tipos de arquivo são rejeitados neste fluxo.

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://ai-detect.undetectable.ai/get-presigned-url

Exemplo de solicitação

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'

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' # Attachment

Detectar PDF

Envie um PDF que já foi carregado no armazenamento de objetos. Este endpoint enfileira a análise de metadados e, opcionalmente, a detecção de IA do texto.

Threshold

Para trabalhos PDF (modelo: `pdf_metadata_detector`), `result` é sempre 100.0 (impressão digital encontrada → `label`: "AI") ou 0.0 (sem impressão digital → `label`: "Human"). Os limites 50/60 humano/IA aplicam-se apenas à detecção de texto (modelo: `xlm_ud_detector`).

Campos de resposta

Consulte `/query` para o documento. Para trabalhos PDF (modelo: `pdf_metadata_detector`), `result_details` contém `prediction`, `rule`, `base_category` e `basic_source` no nível superior. Os valores creator/producer brutos do PDF não são retornados; são usados internamente e refletidos em `rule` quando um padrão corresponde. `service_type` é sempre `detector`, e `model` permanece `pdf_metadata_detector` durante todo o trabalho.

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

Exemplo de solicitação

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 opcionais

  • Passe `"id"` para fornecer seu próprio UUID de documento (não deve existir previamente).
  • Passe `"generate_analysis_details": true` para solicitar análise profunda do texto quando a IA de texto for executada (mesmo comportamento do `/detect` de texto).
  • Você também pode usar `POST /detect` com `"document_type": "File"` para o mesmo comportamento.

Exemplo de resposta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "pdf_metadata_detector",
    "result": null,
    "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 alguns segundos para trabalhos apenas de metadados; trabalhos que também executam IA de texto podem demorar mais conforme a contagem de palavras extraídas.

Consulta

Consulte o status e os resultados da detecção de PDF por ID do documento (mesmo endpoint da detecção de texto).

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

Exemplo de solicitação

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

Exemplo de resposta (IA detectada nos metadados)

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

Quando a IA de texto também é executada, `model` pode ser `xlm_ud_detector`, `result_details` inclui pontuações do detector e `pdf_metadata`, e `source_details` pode incluir atribuição combinada de metadados/texto.

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.