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
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.
O detector de PDF analisa documentos PDF enviados em busca de sinais de geração por IA e adulteração digital. Os PDFs são processados de forma assíncrona: envie o arquivo, submeta-o para detecção via `/detect-pdf` e então consulte os resultados.
O detector executa vários módulos de análise em cada documento. Por padrão, todos os módulos são executados. Você pode escolher quais módulos executar incluindo o parâmetro `modules` na solicitação:
metadataVerifica os metadados do documento em busca de artefatos de adulteração deixados por IA ou ferramentas de edição digital.
structureInspeciona o documento em busca de edições digitais, como camadas de texto oculto.
Seleção de modelo
Envie `model` no corpo da solicitação como um dos valores abaixo. Qualquer outro valor retorna 400 Bad Request.
pdf_detector: Versão mais recente (atualmente `pdf_detector/v5`). Equivale a omitir `model`.pdf_detector/v1: Detecta se o PDF foi gerado por uma ferramenta de IA nos metadados PDF.pdf_detector/v3: Verifica edições digitais e sinais de documentos gerados por IA.pdf_detector/v4: Verifica edições digitais e sinais de documentos gerados por IA, com desempenho geral aprimorado em relação à v3.pdf_detector/v5: Detector mais recente. Executa análise de metadados e de estrutura.Seleção de módulos
Envie `modules` no corpo da solicitação como um dos valores abaixo.
[]: Todos os módulos (padrão). Equivale a omitir `modules`.["metadata"]: Apenas análise de metadados.["structure"]: Apenas análise de estrutura.Fluxo de trabalho
Requisitos de arquivo
Os arquivos devem ser `.pdf`, ter no máximo 2 MB e estar publicamente acessíveis na URL informada.
Dedução de créditos
A detecção de PDF consome 1.000 créditos por página, independentemente dos módulos selecionados. Um PDF de 5 páginas custa 5.000 créditos. Verifique seu saldo com `GET /check-user-credits` antes de enviar documentos grandes.
Solicite uma URL de upload pré-assinada antes de enviar um PDF para detecção. `file_name` (obrigatório): o nome do arquivo PDF (deve terminar em `.pdf`). `expiration` (opcional): tempo de expiração da URL em segundos (padrão: 3600).
Cabeçalhos
Inclua sua chave de API no cabeçalho `apikey`.
GET https://detect-text.truthscan.com/get-presigned-urlExemplo 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"
}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'Envie um PDF que já foi carregado no armazenamento de objetos.
Corpo da solicitação
url (obrigatório): URL no armazenamento de objetos do PDF enviado (`presigned_url` host + `file_path`).key (obrigatório): Sua chave de API.model: O modelo do detector a usar. O padrão é `pdf_detector` (mais recente). Valores versionados suportados incluem `pdf_detector/v1`, `pdf_detector/v3`, `pdf_detector/v4` e `pdf_detector/v5`.modules: Array de módulos a executar: `["metadata"]`, `["structure"]` ou `["metadata", "structure"]`. Omita ou envie `[]` para executar todos. Aplica-se a v4 e v5; ignorado em versões legadas.POST https://detect-text.truthscan.com/detect-pdfExemplo de solicitação : todos os módulos (padrão)
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 : apenas metadados
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",
"modules": ["metadata"]
}'Exemplo de resposta
{
"id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
"model": "pdf_detector",
"result": null,
"result_details": null,
"status": "pending",
"retry_count": 0
}A resposta contém um `id` de documento. Use-o para consultar os resultados via `POST /query`. O processamento normalmente termina em alguns segundos.
Use o endpoint `/query` (o mesmo da detecção de texto) para verificar o status e obter resultados. O formato da resposta depende de qual `model` foi usado no trabalho. Consulte até que `status` seja `done`.
POST https://detect-text.truthscan.com/queryExemplo 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-FROM-STEP-3"
}'Exemplo de resposta : documento adulterado (Tampered)
{
"id": "594502f3-5474-4d2f-9a7a-039f85485854",
"model": "pdf_detector",
"status": "done",
"retry_count": 0,
"modules": {
"metadata": {
"status": "done",
"result_details": {
"prediction": "ChatGPT",
"rule": "PyMuPDF - Creator: OpenAI",
"base_category": "Possibly AI Generated/Edited",
"basic_source": "ChatGPT"
},
"source_details": {
"source": "AI Generated",
"credits_deducted": 1000
},
"label": "Tampered"
},
"structure": {
"status": "done",
"result_details": {
"prediction": "Suspicious",
"rule": { "hidden": "medium" },
"max_severity": "medium",
"signals_flagged": 1,
"signals": {
"hidden": {
"label": "Hidden Text",
"flagged": true,
"severity": "medium",
"findings": [
{
"severity": "medium",
"detail": "Page 1: invisible text layer found beneath visible content."
}
]
}
}
},
"detailed_explanation": "Page 1 contains a hidden text layer beneath visible content, suggesting possible content manipulation.",
"label": "Suspicious"
}
},
"summary": {
"label": "Tampered",
"detection_steps": ["metadata", "structure"],
"detection_rules": {
"metadata": "PyMuPDF - Creator: OpenAI",
"structure": "1 signals fired"
},
"details": {
"is_ai": true,
"ai_detection_steps": ["metadata"],
"is_digitally_edited": true,
"digital_edit_detection_steps": ["structure"]
}
}
}Módulo de metadados
label: Tampered se uma impressão digital de IA foi encontrada; Genuine caso contrário.result_details.prediction: A ferramenta de IA identificada (ex.: `"ChatGPT"`) ou `"No Tampering Detected"`.source_details: Aninhado em `modules.metadata`.source_details.source: `"AI Generated"`, `"Digitally Edited"` ou `null`.source_details.credits_deducted: Créditos cobrados por este trabalho em chaves TruthScan; `null` caso contrário.Exemplo de resposta: documento genuíno (Genuine)
{
"id": "e4c0f5d7-b061-4d4e-af9c-5b8da03e6f44",
"model": "pdf_detector",
"status": "done",
"retry_count": 0,
"modules": {
"metadata": {
"status": "done",
"result_details": {
"prediction": "No Tampering Detected",
"rule": null,
"base_category": "No Tampering Detected",
"basic_source": null
},
"source_details": {
"source": null,
"credits_deducted": 1000
},
"label": "Genuine"
},
"structure": {
"status": "done",
"result_details": {
"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.",
"label": "Genuine"
}
},
"summary": {
"label": "Genuine",
"detection_steps": [],
"detection_rules": {},
"details": {
"is_ai": false,
"ai_detection_steps": [],
"is_digitally_edited": false,
"digital_edit_detection_steps": []
}
}
}Entendendo a resposta
`summary.label` é o veredito geral. `summary.detection_steps` lista os módulos que sinalizaram o documento. `summary.detection_rules` registra o que acionou cada módulo sinalizado. `summary.details.is_ai` é `true` se o documento foi identificado como gerado por IA. `summary.details.is_digitally_edited` é `true` se edições estruturais foram detectadas.
Módulo de estrutura
label: Tampered, Suspicious ou Genuine.result_details.signals: Detalhamento por sinal. `hidden` detecta camadas de texto oculto no documento.result_details.signals_flagged: Número total de sinais que foram acionados.detailed_explanation: Resumo em linguagem natural dos achados.Veredito
Tampered: Evidência forte de manipulação de conteúdo ou origem gerada por IA.Suspicious: Um ou mais sinais detectados, mas não no nível de confiança mais alto.Genuine: Nenhum sinal de adulteração detectado.Níveis de severidade
Cada achado individual tem um nível de severidade: `"low"`, `"medium"` ou `"high"`.
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 Erro | Significado |
|---|---|
| 400 | Bad Request -- Sua solicitação é inválida. |
| 403 | Proibido -- A chave de API é inválida ou não há créditos suficientes (1.000 por página do PDF). |
| 404 | Not Found -- O recurso especificado não existe. |
| 405 | Method Not Allowed -- Você tentou acessar um recurso com um método inválido. |
| 406 | Not Acceptable -- Você solicitou um formato que não é JSON. |
| 410 | Gone -- O recurso neste endpoint foi removido. |
| 422 | Invalid Request Body -- O corpo da sua solicitação está formatado incorretamente ou inválido ou tem parâmetros ausentes. |
| 429 | Too Many Requests -- Você está enviando muitas solicitações! Diminua a velocidade! |
| 500 | Internal Server Error -- Tivemos um problema com nosso servidor. Tente novamente mais tarde. |
| 503 | Service Unavailable -- Estamos temporariamente offline para manutenção. Tente novamente mais tarde. |
Obtenha relatórios forenses completos - mapas de calor, indicadores-chave e descrições detalhadas.
Free
Experimente o motor completo
Starter
$0,03 / resultado - $290/ano
Para indivíduos e equipes pequenas
Professional
$0,02 / resultado - $990/ano
Para equipes em produção
Business
$0,01 / resultado - $3.990/ano
Para operações de alto volume
Find answers to the most common questions about our AI PDF detection API.