Documentação da API

API de detecção de imagens por IA

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

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

Prefere uma biblioteca de cliente? Use nossos SDKs oficiais em vez de chamar a API REST diretamente. Ver Documentação dos SDKs de Cliente

Preços e créditos

Cada detecção de imagem bem-sucedida consome créditos. Uploads em massa via ZIP cobram apenas imagens que concluem a análise; arquivos ignorados ou com falha não são cobrados.

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

Autenticação

A TruthScan usa chaves de API. Obtenha sua chave no topo da página no portal do desenvolvedor.

A chave deve estar no corpo JSON das requisições (exceto endpoints só com cabeçalho, ex.: check-user-credits):

{
  "key": "YOUR API KEY GOES HERE"
}

Substitua YOUR API KEY GOES HERE pela sua chave pessoal.

Limites de taxa

A API aplica para cada chave de API um orçamento de requisições por minuto. Endpoints de escrita custam mais que os de leitura. O limite padrão é 250 requisições por minuto — fale conosco se precisar de um limite maior.

Pesos por endpoint

Cada chamada desconta seu peso do orçamento por minuto:

Endpoint	Tipo	Peso
POST /detect	Escrita	1
POST /bulk-upload	Escrita	1
GET /get-presigned-url	Leitura	0.2
GET /check-user-credits	Leitura	0.2
POST /heatmap/{id}	Leitura	0.2
POST /preview/{id}	Leitura	0.2
POST /query	Leitura	Sem limite
GET /health	Leitura	Sem limite

Exemplo: com um orçamento de 250/minuto você pode enviar até 250 chamadas de escrita, até ~1.250 chamadas de leitura, ou qualquer combinação cujo total ponderado fique ≤ 250 por minuto.

Resposta limitada (HTTP 429)

Quando você ultrapassa o orçamento por minuto, a API retorna:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 250
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3
X-RateLimit-Retry-After: 3
Content-Type: application/json

{
  "error": "Too many requests"
}

Cabeçalhos de resposta de rate limit

X-RateLimit-Limit — sua capacidade por minuto.
X-RateLimit-Remaining — chamadas restantes no minuto atual (após esta requisição).
X-RateLimit-Reset — (somente em 429) segundos até você poder enviar outra requisição de escrita.
X-RateLimit-Retry-After — (somente em 429) mesmo valor de X-RateLimit-Reset, no estilo Retry-After.

Comportamento recomendado do cliente

Acompanhe X-RateLimit-Remaining nas respostas bem-sucedidas para regular o ritmo das requisições.
Em um 429, espere pelo menos X-RateLimit-Retry-After segundos antes de tentar de novo — use backoff exponencial com jitter.
Para lotes, prefira POST /bulk-upload (uma chamada processa até 50 imagens) em vez de muitas /detect em paralelo.

Detector de imagens por IA

Detectar (fluxo em 3 etapas)

O fluxo de detecção de imagens por IA consiste nas seguintes etapas:

Obter URL de upload pré-assinada
Enviar a imagem
Enviar a imagem para detecção

1. Obter URL de upload pré-assinada

Primeiro, solicite uma URL pré-assinada à API. Ela permite enviar o arquivo de imagem com segurança ao armazenamento.

Formatos de arquivo suportados

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG, PDF

Nome do arquivo

Remova espaços do nome ao solicitar a URL pré-assinada.

Para PDF, apenas a primeira imagem é detectada (fluxo de arquivo único).

Use um nome .zip neste endpoint quando for enviar um ZIP em upload em lote.

Parâmetros de consulta

file_name (obrigatório) — Nome original; o servidor pode normalizar (espaços e caracteres inseguros são ajustados). Use extensão .zip para upload em lote.
expiration (opcional) — Validade da URL pré-assinada em segundos (padrão: 3600).

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

Exemplo de requisição

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

Exemplo de resposta

{
  "status": "success",
  "presigned_url": "https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

document_id é um novo UUID para esta solicitação de upload (correlação/logs). O id usado em /detect ou /bulk-upload é atribuído ao chamar esses endpoints, salvo se você passar um id opcional em /detect.

Respostas HTTP

Cabeçalho obrigatório: apikey: YOUR-API-KEY-GOES-HERE

Status	Corpo	Quando
200	JSON: status, presigned_url, file_path, document_id	Sucesso
400	{"error": "..."}	Tipo de arquivo não suportado / parâmetros inválidos
403	{"error": "..."}	Chave de API inválida
404	{"error": "..."}	Falha na validação da chave TruthScan
500	{"error": "..."}	Erro no servidor

2. Enviar a imagem

Use a presigned_url fornecida com PUT. Defina o Content-Type conforme o formato da imagem.

Nome do arquivo

Remova espaços do nome ao enviar.

Defina Content-Type exatamente conforme a extensão

image/jpeg: jpg, jpeg, jfif
image/png: png
image/webp: webp
image/heic: heic
image/heif: heif
image/avif: avif
image/bmp: bmp
image/tiff: tiff, tif
image/gif: gif
image/svg+xml: svg
application/pdf: pdf

Erros comuns a evitar

Não use image/jpg (incorreto). Use image/jpeg.
Não misture arquivo e cabeçalho (ex.: .png com image/jpeg).
Não altere a extensão sem atualizar o cabeçalho (e vice-versa).
Não inclua espaços nos nomes ao solicitar/enviar.

Exemplo de requisição

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

Mais exemplos de upload (PNG, PDF, SVG)

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'

curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'

curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

Limites de tamanho

Mínimo: 1 KB
Máximo: 10 MB

Mantenha o formato consistente durante o upload. Sucesso retorna HTTP 200.

Resposta do PUT no armazenamento

A etapa 2 é um PUT direto no armazenamento de objetos (URL pré-assinada), não na nossa API. Upload de imagem única e ZIP em massa funcionam da mesma forma.

Sucesso retorna HTTP 200 com corpo vazio — por design. Não há JSON para analisar.

Após o PUT em presigned_url: trate res.ok (status 200–299) como sucesso. Não chame response.json() em caso de sucesso — corpo vazio é esperado. Reporte erros apenas em respostas fora de 2xx.

3. Enviar imagem para detecção por IA

Após o upload, envie para detecção usando o file_path da etapa anterior. Para PDF, apenas a primeira imagem é analisada/detectada.

POST https://detect-image.truthscan.com/detect

Exemplo de requisição

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": true
}'

FILE_PATH é o caminho retornado na etapa da URL pré-assinada (ex.: uploads/...). Monte a URL completa com o host do armazenamento como no exemplo.

Parâmetros opcionais

id: UUID opcional. Se omitido, o servidor gera um novo id de documento. Se informado, não pode existir; caso contrário, erro.
generate_preview: true para gerar URL de pré-visualização (padrão: true). false pula a prévia.
document_type: Tipo de documento (padrão: Image).
email: E-mail para processamento.
generate_analysis_details: false para pular análise detalhada (padrão: true).
generate_heatmap: Quando false, pula a geração de mapa de calor por completo (padrão: true). Mapas de calor só são produzidos para imagens classificadas como IA quando true. Imagens reais nunca recebem mapa de calor.
generate_heatmap_overlayed: Controla como o mapa de calor é gerado (padrão: true). Aplica-se somente quando generate_heatmap é true e a imagem é classificada como gerada por IA. Com true, o mapa é sobreposto à imagem original; com false, retorna PNG RGBA transparente para compor na interface.
generate_heatmap_normalized: Com false, pula a normalização do mapa de ativação (padrão: true). Aplica-se somente quando generate_heatmap é true e a imagem é classificada como gerada por IA. Use junto com generate_heatmap_overlayed.
model: Dica de modelo ou roteamento (padrão: generic). Ex.: generic ou instance_id/model. instance_id inválido → 400.
user_agent: String opcional armazenada no documento para analytics/suporte.

Validação dos flags de heatmap

Se generate_heatmap for false, não defina explicitamente generate_heatmap_overlayed ou generate_heatmap_normalized como true. A API retorna 422 Unprocessable Entity com mensagens como "generate_heatmap_overlayed cannot be true when generate_heatmap is false." ou "generate_heatmap_normalized cannot be true when generate_heatmap is false."

Exemplo de requisição (heatmap habilitado, padrão)

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": true,
  "generate_preview": false,
  "generate_analysis_details": false,
  "model": "generic"
}'

Exemplo de requisição (heatmap desabilitado)

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": false,
  "generate_preview": false,
  "generate_analysis_details": false,
  "model": "generic"
}'

Requisição inválida (422)

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-dev.nyc3.digitaloceanspaces.com/uploads/example.jpg",
  "generate_heatmap": false,
  "generate_heatmap_overlayed": true
}'

Exemplo de resposta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

A resposta inclui um id de imagem único para acompanhar o status.

Respostas HTTP

Status	Corpo	Quando
200	JSON: id, status (tipicamente "pending")	Job aceito — é o que a API retorna em caso de sucesso
400	{"error": "..."}	Validação (sem URL, arquivo não enviado, tamanho/tipo, id duplicado, modelo inválido, conflito de flag de heatmap, etc.)
403	{"error": "..."}	Chave inválida / créditos insuficientes
422	{"error": "..."}	Corpo da requisição inválido (ex.: generate_heatmap_overlayed true quando generate_heatmap é false)
500	{"error": "..."}	Erro no servidor

Trate qualquer resposta 2xx cujo JSON inclua id e status como sucesso — não apenas HTTP 200. Proxies ou outras pilhas HTTP podem retornar 201 ou 202 para padrões de aceitação assíncrona; valide o corpo JSON.

Consultar status e resultados da detecção

Use o endpoint /query com o id da imagem para obter status e resultados.

Autenticação: o corpo só inclui id; a API não envia chave nesta chamada. Quem souber o UUID pode consultar — trate ids de documento como sensíveis se precisar restringir acesso.

Respostas HTTP

Status	Corpo	Quando
200	JSON de resultado (imagem única ou em massa)	Encontrado
404	Error detail	Id desconhecido
500	Error detail	Erro no servidor

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

Exemplo de requisição

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

Exemplo de resposta

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "metadata": [
            "No Information Detected for Real/AI",
            "Could not find anything from ExifTool and Pillow metadata"
        ],
        "metadata_basic_source": "null",
        "ocr": [
            "OCR did not detect AI",
            0.0
        ],
        "ml_model": [
            "AI Generated",
            90.2371538185235
        ],
        "confidence": 90.2371538185235,
        "final_label_confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "pending",
        "analysis_results": null,
        "warnings": [
            { "type": "blur_dark", "label": "Blurred" },
            { "type": "watermark", "label": "Gemini", "confidence": 0.95 },
            { "type": "screen_recapture", "label": "screen", "metrics": { "is_screen": false }, "confidence": 99.99 }
        ]
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Exemplo de resposta (/query, URLs seguras ativas na organização)

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "final_label_confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
        "analysis_results_status": "ready",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}

Exemplo de resposta quando a análise detalhada está pronta

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "ready",
        "analysis_results": {
            "imageTags": ["person", "portrait", "outdoor", "vineyard", "smiling"],
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": ["Uniform noise pattern typical of diffusion models"],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Detalhes do resultado

is_valid: Indica se o arquivo de imagem é válido (true/false).
detection_step: Etapa em que a detecção concluiu: 1 = só metadados; 2 = metadados e ocr; 3 = metadados, ocr e ml_model.
final_result: Determinação geral (ex.: "AI Generated", "Real", "Digitally Edited", "AI Edited").
confidence: Confiança da detecção.
final_label_confidence: Quão certo o modelo está de `final_result`, de 0 a 100. Leia como “esta imagem é N% [rótulo]”. Por exemplo, `final_result`: `"AI Generated"` com `final_label_confidence`: `90` significa que o modelo está 90% confiante de que a imagem é gerada por IA; `final_result`: `"Real"` com `final_label_confidence`: `80` significa que o modelo está 80% confiante de que é real.
metadata: Informações extraídas dos metadados com ExifTool e Pillow.
metadata_basic_source: Pode indicar se a imagem foi capturada por um modelo de câmera, gerada por IA ou editada.
ocr: Resultado de marca d'água no campo histórico ocr. Array [rótulo, pontuação]; rótulo ex. "Gemini" ou "OCR did not detect AI"; pontuação 0–100. Resumido em warnings quando há rótulo.
ml_model: Resultados do modelo de aprendizado de máquina.
warnings: Array opcional de avisos (blur_dark, watermark, screen_recapture etc.). Pode estar vazio ou ausente. blur_dark e screen_recapture: ambos são bons candidatos a uma nova captura com o Capture em vez de uma decisão definitiva.
preview_url: URL de prévia se generate_preview foi true. Pode ser armazenamento direto ou caminho da API como https://<api-host>/preview/<document_id>.
heatmap_status: pending, ready ou failed. Omitido quando a imagem não é gerada por IA ou quando generate_heatmap era false no envio. A geração de heatmap é assíncrona e só ocorre para imagens classificadas como IA quando generate_heatmap é true.
heatmap_url: Presente quando heatmap_status é ready, a imagem foi classificada como IA e generate_heatmap estava habilitado no envio. Depende de generate_heatmap_overlayed. Direto ou API; com URLs seguras use POST /heatmap/{id} com chave.
analysis_results_status: pending, ready, skipped, failed ou analyzing. Omitido ou null se generate_analysis_details foi false.
analysis_results: Análise narrativa detalhada quando habilitada; veja embaixo.

Explicação dos resultados de análise

Quando analysis_results está pronto, costuma incluir: agreement (strong | moderate | weak | disagreement), imageTags (até cinco tags curtas), confidence (0–100), keyIndicators, detailedReasoning, visualPatterns e recommendations.

Observações

A geração de heatmap é assíncrona e só ocorre para imagens classificadas como IA quando generate_heatmap é true (padrão). Consulte /query até heatmap_status ser ready.
Análise detalhada é assíncrona salvo generate_analysis_details=false. Consulte analysis_results_status e analysis_results.
URLs seguras: heatmap_url e preview_url podem usar o host da API; busque com POST /heatmap/{id} e POST /preview/{id} com sua chave.
Chame /query novamente após o score principal para obter heatmap e analysis_results quando concluírem.

Mapa de calor e sobreposição

heatmap_url reflete generate_heatmap_overlayed e generate_heatmap_normalized de /detect (ou /bulk-upload) quando generate_heatmap era true: sobreposição padrão (true) é uma imagem normal com o mapa sobreposto; false costuma ser PNG transparente para composição. Imagens reais e requisições com generate_heatmap: false omitem heatmap_status e heatmap_url.

Exemplo de resposta (imagem IA, heatmap desabilitado no envio)

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "final_label_confidence": 90.2371538185235
    }
}

Exemplo de resposta (imagem IA, heatmap pendente)

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "final_label_confidence": 90.2371538185235,
        "heatmap_status": "pending",
        "heatmap_url": null
    }
}

Exemplo: result ~90,24 com final_result AI Generated e detection_step 3 indica pipeline completa (metadados, OCR, ML).

Como tratar resultados sinalizados

Beta

A API devolve uma classificação e uma confiança, não uma decisão. A maioria das integrações em produção usa três faixas. Abaixo do seu limite inferior, aprove automaticamente. Acima do seu limite superior, encaminhe para revisão com o mapa de calor e analysis_results anexados. Entre os dois, peça uma nova captura ao vivo com o TruthScan Capture (beta) antes de envolver um revisor.

Um pedido de Capture cabe quando o resultado é incerto ou a própria imagem é o problema: final_label_confidence na sua faixa do meio, analysis_results.agreement weak ou disagreement, ou uma entrada de warnings blur_dark ou screen_recapture. Em cada caso, a resolução mais barata é uma foto nova tirada ao vivo no dispositivo de quem enviou, não um julgamento humano sobre uma foto ruim.

O Capture devolve um novo resultado de detecção vinculado ao id da solicitação original, para que sua camada de decisão veja os dois. Durante a beta, o Capture é habilitado por conta.

Obter acesso à beta do Capture

result = client.detect(image)
conf = result.result_details.final_label_confidence
if conf < LOWER:            approve(result)
elif conf > UPPER:          route_to_review(result)
else:                       # gray band, or warnings / weak agreement
    capture = client.capture.request(result.request_id, contact=submitter)
    # poll capture.request_id for the linked, verified result

Resultados de análise (análise profunda assíncrona)

Com generate_analysis_details true em /detect, a análise detalhada pode concluir após o score principal. Consulte /query até analysis_results_status ready (ou skipped/failed).

1. Resultado inicial pode ficar pronto antes da análise

Detecção principal (result, final_result, confidence) pode terminar com analysis_results_status ainda pending.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "final_label_confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

O que fazer

Use os campos principais imediatamente; continue consultando se precisar de analysis_results.

2. Continue consultando

Chame /query com o mesmo id até analysis_results_status mudar de pending.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

3. Análise concluída

Com analysis_results_status ready, analysis_results inclui agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns e recommendations.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "final_label_confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Quando a análise não está disponível

Se analysis_results_status for skipped, failed ou ausente, ou generate_analysis_details false, considere a detecção principal como final.

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

Campos da análise detalhada

analysis_results_status: pending | ready | skipped | failed | analyzing
analysis_results.agreement: strong | moderate | weak | disagreement
analysis_results.imageTags: tags descritivas curtas
analysis_results.confidence: 0–100
analysis_results.keyIndicators: indícios específicos
analysis_results.detailedReasoning: explicação breve
analysis_results.visualPatterns: padrões mais amplos
analysis_results.recommendations: próximos passos

Upload em lote (ZIP)

Envie várias imagens em uma requisição com um ZIP. Fluxo igual ao de imagem única: URL pré-assinada (nome .zip) → PUT ZIP → POST /bulk-upload → consultar /query.

1. URL pré-assinada (ZIP)

Use get-presigned-url com nome .zip (ex.: images.zip).

GET https://detect-image.truthscan.com/get-presigned-url?file_name=images.zip

Exemplo de requisição

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=images.zip' \
--header 'apikey: YOUR API KEY GOES HERE'

2. Enviar o ZIP

PUT do ZIP na URL pré-assinada com Content-Type: application/zip.

curl -X PUT '<PRESIGNED_URL_FOR_images.zip>' \
  --header 'Content-Type: application/zip' \
  --header 'x-amz-acl: private' \
  --data-binary '@images.zip'

Limites do ZIP

Tamanho máximo do ZIP: 100 MB
Máximo de imagens por lote: 50
Por imagem: mínimo 1 KB, máximo 10 MB

Formatos suportados dentro do ZIP

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG

PDF dentro do ZIP não é suportado e será ignorado.

SVG é convertido para PNG antes da detecção.

3. Enviar ZIP para detecção em lote

POST /bulk-upload com key e url apontando para o caminho do ZIP enviado.

Parâmetros opcionais

generate_preview: true para gerar URLs de prévia por imagem (padrão: false).
generate_analysis_details: true para análise detalhada (padrão: false).
generate_heatmap: Quando false, pula a geração de mapa de calor por completo (padrão: true). Mapas de calor só são produzidos para imagens classificadas como IA quando true. Imagens reais nunca recebem mapa de calor.
generate_heatmap_overlayed: Mesmo comportamento de /detect (sobreposição vs RGBA transparente). Aplica-se somente quando generate_heatmap é true e a imagem é classificada como gerada por IA.
generate_heatmap_normalized: Mesmo comportamento de /detect (padrão: true). Aplica-se somente quando generate_heatmap é true e a imagem é classificada como gerada por IA.
model: Domínio do modelo: generic ou instance_id/model.

Validação dos flags de heatmap

Exemplo de requisição

curl -X 'POST' \
  'https://detect-image.truthscan.com/bulk-upload' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": false,
  "model": "generic"
}'

Exemplo de resposta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending",
    "expected_count": 12
}

Retorna id, status pending e expected_count (quantas imagens do ZIP serão analisadas).

Respostas HTTP

Status	Corpo	Quando
200	JSON: id, status, expected_count	Job em massa aceito
400	{"error": "..."} (pode incluir skipped)	Falhas na validação do ZIP
403	{"error": "..."}	Autenticação / créditos
500	{"error": "..."}	Erro no servidor

Mesma regra que /detect: qualquer 2xx com id, status e expected_count (quando presente) é sucesso.

Atualização dos resultados do ZIP em lote

Após envio, status pending até o processamento começar, depois analyzing.
results lista cada imagem; entradas pendentes têm result e result_details null até concluir.
Mapas de calor e análises em result_details podem ainda estar pending.
Quando todas as imagens terminam, status geral done; falha pode ser failed.
É possível chamar /query antes do ZIP terminar para ver resultados parciais.

4. Consultar resultados do lote

POST /query com o id retornado por /bulk-upload. Mesmo endpoint da imagem única; o formato depende se o id é imagem única ou lote ZIP.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
}'

Exemplo de resposta (ainda processando)

{
  "id": "3b81fb24-dd23-40e7-ae95-82f823f44098",
  "status": "analyzing",
  "results": [
    {
      "id": "4600c7e5-00ec-469d-9117-ff20e0f1c1fa",
      "status": "done",
      "result": 44.0006,
      "result_details": {},
      "filename": "photo1.jpg",
      "preview_url": null
    },
    {
      "id": "2f770c89-352a-4d53-b6a3-a2147ca2c0ae",
      "status": "pending",
      "result": null,
      "result_details": null,
      "filename": "photo2.jpg",
      "preview_url": null
    }
  ],
  "skipped": []
}

Campos da resposta (ZIP em lote)

id — id da requisição em lote.
status — pending, depois analyzing, depois done ou failed.
results — Uma entrada por imagem (id, status, result, result_details, filename, preview_url quando houver).
skipped — Arquivos não analisados (tipo, tamanho etc.) com failed e motivo em result_details.

Cobrança: créditos são usados apenas para imagens analisadas com sucesso. Falhas de conversão SVG e arquivos ignorados não são cobrados.

Mapa de calor e prévia seguros

Quando heatmap_url ou preview_url em /query apontam para o host da API (não armazenamento direto), baixe os bytes com POST e sua chave.

POST /heatmap/{id}

POST /preview/{id}

Corpo JSON: { "key": "YOUR-API-KEY-GOES-HERE" }

Respostas do mapa de calor (verifique status HTTP e Content-Type)

200 + binário (image/png etc.) — Arquivo disponível. X-Heatmap-Status pode estar definido.
202 + JSON — heatmap_status pending; consulte /query e tente de novo.
200 + JSON — Sem mapa de calor para servir (opcional/falhou); não é erro de servidor.
500 + JSON — heatmap_url existe mas o download do armazenamento falhou; tente depois.
404 + JSON — id de documento não encontrado.
403 + JSON — A chave não pertence a este documento.

Prévia: POST /preview/{id} retorna bytes brutos. 404 com JSON se não houver prévia (generate_preview false).

Exemplos

curl -X POST 'https://detect-image.truthscan.com/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output heatmap.png

curl -X POST 'https://detect-image.truthscan.com/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output preview.png

Consultar créditos do usuário

Este endpoint aceita o apikey do usuário no cabeçalho e retorna detalhes de créditos.

GET https://detect-image.truthscan.com/check-user-credits

Exemplo de requisição

curl -X 'GET' \
  'https://detect-image.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Exemplo de resposta

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Em integrações externas, normalmente só o campo credits vem preenchido.

Verificação de saúde

Verifica o estado do servidor da API.

GET https://detect-image.truthscan.com/health

Exemplo de requisição

curl -X 'GET' \
  'https://detect-image.truthscan.com/health' \
  -H 'accept: application/json'

Exemplo de resposta

{
    "status": "healthy"
}

Resposta "healthy" indica que o serviço está operando normalmente.

Erros

A maioria dos erros vem de parâmetros incorretos. Revise cada chamada e use os exemplos.

Os códigos de erro seguem o padrão REST:

Código	Significado
400	Bad Request — Requisição inválida.
401	Unauthorized — Segredo do job inválido (endpoints internos) ou falha de autenticação similar.
403	Forbidden — Chave de API inválida, acesso negado ou créditos insuficientes.
404	Not Found — Recurso não encontrado.
405	Method Not Allowed — Método HTTP inválido para o recurso.
406	Not Acceptable — Formato solicitado não é JSON.
410	Gone — Recurso neste endpoint foi removido.
422	Invalid Request Body — Corpo mal formatado, inválido ou com parâmetros faltando.
429	Too Many Requests — Você ultrapassou o limite de taxa da sua chave de API (veja Limites de taxa). O corpo é {"error":"Too many requests"}; o cabeçalho X-RateLimit-Retry-After indica os segundos a aguardar antes de tentar novamente.
500	Internal Server Error — Erro no servidor; tente novamente mais tarde.
503	Service Unavailable — Manutenção ou sobrecarga; tente novamente mais tarde.

Problemas comuns e soluções

Autenticação

"User verification failed" (403)

Causa: Chave de API inválida ou expirada

Solução:

Confirme se a chave está correta
Verifique se a chave está ativa na conta
Gere uma nova chave se necessário

"Not enough credits" (403)

Causa: Créditos insuficientes para processar a imagem

Solução:

Consulte créditos restantes com /check-user-credits
Compre créditos adicionais se precisar

Validação de entrada

"Input URL cannot be empty" (400)

Causa: URL vazia ou inválida

Solução:

Garanta que url não está vazia
Remova espaços extras nos nomes de arquivo
Verifique a codificação da URL

"Input email is empty" (400)

Causa: E-mail ausente para processamento por URL

Solução:

Informe um e-mail válido ao enviar URLs
Verifique o formato do e-mail

"Unsupported image type" (400)

Causa: Formato não suportado

Solução:

Converta para um formato suportado (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
Confira a extensão do arquivo

"File size is too small" (400)

Causa: Arquivo abaixo do tamanho mínimo

Solução:

Use um arquivo maior (mínimo 1 KB)
Verifique se o arquivo não corrompeu no upload

"File size exceeds limit" (400)

Causa: Arquivo muito grande

Solução:

Comprima ou redimensione; o limite em MB aparece na mensagem de erro da API
Use outro formato de imagem

"Invalid file type" (400)

Causa: Validação de tipo falhou

Solução:

Confirme que é um formato de imagem válido
Verifique se o arquivo não está corrompido
MIME type e extensão devem coincidir

Processamento

Status da imagem "failed"

Causa: Falha no processamento por diversos motivos

Solução:

Confirme formato de URL suportado
Verifique se o arquivo é válido e não corrompido
Atenda aos requisitos de tamanho
Entre em contato com o suporte se persistir

"User not found"

Causa: ID de usuário inválido

Solução:

Confirme o ID do usuário
A conta deve estar ativa
Reautentique se necessário

"File metadata could not be fetched" (500)

Causa: Não foi possível acessar o arquivo enviado

Solução:

Confirme que o upload foi concluído
A URL do arquivo deve estar acessível
Tente enviar novamente

O resultado é AI Generated, mas quem enviou diz que a foto é real

Verifique primeiro final_label_confidence e analysis_results.agreement; uma confiança na faixa do meio ou um agreement fraco significa que o modelo não tem certeza. Verifique warnings em busca de blur_dark ou screen_recapture, que muitas vezes explicam uma pontuação ruim em uma foto real. Em qualquer um dos casos, peça uma nova captura ao vivo pelo TruthScan Capture em vez de decidir de forma definitiva sobre o original. Se a nova captura também for sinalizada, encaminhe para revisão com os dois resultados anexados.

Upload

"Image upload failed" (403/400)

Causa: URL pré-assinada inválida/expirada ou problema no armazenamento

Solução:

Use a URL pré-assinada logo após recebê-la
Content-Type deve corresponder ao formato
Remova espaços do nome antes do upload
Gere nova URL pré-assinada se necessário

"Invalid pre-signed URL" (400)

Causa: Nome com espaços ou URL pré-assinada expirada/corrompida

Solução:

Remova espaços do nome antes de solicitar a URL pré-assinada
Use letras, números, hífens e sublinhados
Gere nova URL pré-assinada se necessário

Upload em lote

"URL must point to a ZIP file" (400)

Causa: A URL em /bulk-upload não aponta para um ZIP

Solução:

Use get-presigned-url?file_name=images.zip (ou outro .zip)
Envie um ZIP válido para a URL pré-assinada
Garanta que bulk-upload use a URL do ZIP enviado

"ZIP file too large" (400)

Causa: ZIP acima de 100 MB

Solução:

Reduza imagens ou comprima
Divida em vários lotes

"Too many files" (400)

Causa: ZIP com mais de 50 imagens válidas

Solução:

Limite a 50 imagens por ZIP
Divida em vários lotes

"No valid images found in ZIP" (400)

Causa: Todos os arquivos foram ignorados (formato, tamanho, caminho etc.)

Solução:

Use formatos suportados (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
PDF não é suportado em lote
Cada imagem: mínimo 1 KB, máximo 10 MB
Evite arquivos ocultos (nome começa com .) e path traversal (..)

"Document is not a bulk upload (image-zip) result" (400)

Causa: O id não corresponde ao tipo (imagem única vs lote ZIP)

Solução:

Use o id de /detect para envios de imagem única
Use o id de /bulk-upload para envios ZIP

Preços

Obtenha relatórios forenses completos - indicadores-chave e descrições detalhadas.

Free

$0/mês

Experimente o motor completo

25 resultados/mês (imagens + páginas de PDF)
Indicadores detalhados em cada resultado
Acesso completo à API
Histórico de detecção no painel
Grátis para sempre — sem período de teste
Extensão Chrome, assentos ilimitados

Starter

$24/mês

$0,03 / resultado - $290/ano

Para indivíduos e equipes pequenas

1.000 resultados/mês incluídos
$0,03 por resultado adicional
Exportação CSV do histórico
Uploads em lote
Relatórios auditáveis
Suporte padrão
Extensão Chrome, assentos ilimitados

Mais popular

Professional

$83/mês

$0,02 / resultado - $990/ano

Para equipes em produção

5.000 resultados/mês incluídos
$0,02 por resultado adicional
Processamento prioritário
Limites de API mais altos
Extensão Chrome, assentos ilimitados

Business

$333/mês

$0,01 / resultado - $3.990/ano

Para operações de alto volume

40.000 resultados/mês incluídos
$0,01 por resultado adicional
Zero Data Retention (ZDR)
Maiores limites self-serve
Suporte prioritário
Extensão Chrome, assentos ilimitados

Enterprise

Personalize um plano para suas necessidades

$0,005 ou menos por resultado

Falar com vendas

Descontos escalam com o volume
SLAs personalizados com créditos de serviço
Zero Data Retention (ZDR)
Integrações personalizadas

MSA e DPA personalizados
Throughput dedicado
Equipe de conta nomeada 24/7
Implantação dedicada / on-prem

Perguntas frequentes da API

Respostas às dúvidas mais comuns sobre a API de detecção de imagens por IA.

API de detecção de imagens por IA

Autenticação

Limites de taxa

Pesos por endpoint

Resposta limitada (HTTP 429)

Detector de imagens por IA

Detectar (fluxo em 3 etapas)

1. Obter URL de upload pré-assinada

2. Enviar a imagem

3. Enviar imagem para detecção por IA

Consultar status e resultados da detecção

Como tratar resultados sinalizados

Resultados de análise (análise profunda assíncrona)

1. Resultado inicial pode ficar pronto antes da análise

2. Continue consultando

3. Análise concluída

Quando a análise não está disponível

Upload em lote (ZIP)

1. URL pré-assinada (ZIP)

2. Enviar o ZIP

3. Enviar ZIP para detecção em lote

4. Consultar resultados do lote

Mapa de calor e prévia seguros

Consultar créditos do usuário

Verificação de saúde

Erros

Problemas comuns e soluções

Autenticação

"User verification failed" (403)

"Not enough credits" (403)

Validação de entrada

"Input URL cannot be empty" (400)

"Input email is empty" (400)

"Unsupported image type" (400)

"File size is too small" (400)

"File size exceeds limit" (400)

"Invalid file type" (400)

Processamento

Status da imagem "failed"

"User not found"

"File metadata could not be fetched" (500)

O resultado é AI Generated, mas quem enviou diz que a foto é real

Upload

"Image upload failed" (403/400)

"Invalid pre-signed URL" (400)

Upload em lote

"URL must point to a ZIP file" (400)

"ZIP file too large" (400)

"Too many files" (400)

"No valid images found in ZIP" (400)

"Document is not a bulk upload (image-zip) result" (400)

Preços

Personalize um plano para suas necessidades

Perguntas frequentes da API

Como obtenho uma chave de API?

Quais formatos de imagem são suportados?

Quais são os limites de tamanho?

Como funciona o fluxo em 3 etapas?

Padrões de generate_preview e generate_analysis_details?

Como funciona upload ZIP em lote?

Como funcionam os créditos?

O que significam os valores de detection_step?

O que é analysis_results e como uso?

O que devo fazer quando uma foto real é sinalizada?

Há limite de taxa?