API de Detecção de Imagem Gerada por IA

1. Obter uma URL de Upload Pré-assinada

Comece solicitando uma URL pré-assinada da API. Esta URL permite que você faça upload do arquivo de imagem para o servidor de armazenamento com segurança.

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

Exemplo de Solicitaçã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://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. Fazer Upload da Imagem

Use a 'presigned_url' fornecida para fazer upload da sua imagem via uma solicitação PUT. Certifique-se de que o tipo de conteúdo correto está definido de acordo com o formato da sua imagem.

Exemplo de Solicitação

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

Certifique-se de que o formato do arquivo permaneça consistente durante o processo de upload. Um upload bem-sucedido retornará um código de status de 200.

3. Enviar Imagem para Detecção de IA

Após o upload, envie a imagem para detecção de IA referenciando o 'file_path' da etapa anterior.

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

Exemplo de Solicitaçã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": false,
  "generate_analysis_details": true
}'

O 'FILE_PATH' refere-se ao caminho obtido da resposta na etapa inicial, 'Obter uma URL de Upload Pré-assinada'.

Exemplo de Resposta

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

A resposta inclui um ID único de imagem para rastrear o status da detecção.

1. Resultado Inicial Pronto (Análise Ainda Pendente)

Quando você envia com 'generate_analysis_details': true e consulta pela primeira vez com status 'done', os resultados principais de detecção (result, final_result, confidence) estão prontos. No entanto, analysis_results_status pode ser 'pending' — isso significa que a análise profunda de IA ainda está sendo processada em segundo plano.

{
    "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,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

2. Continuar Consultando para Resultados de Análise

Continue chamando o endpoint /query com o mesmo ID de imagem. Verifique o campo analysis_results_status em cada resposta. Quando mudar de 'pending' para 'done', o objeto analysis_results estará preenchido.

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 — Resposta Completa

Quando analysis_results_status for 'done', o objeto analysis_results contém a análise profunda completa de IA com nível de concordância, confiança, indicadores-chave, raciocínio detalhado, padrões visuais e recomendações.

{
    "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,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "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', null ou ausente, a análise profunda não será produzida para esta imagem. Isso acontece quando 'generate_analysis_details' não foi definido como 'true' na solicitação /detect, ou para certos tipos de imagem e cenários de detecção. Trate os resultados de detecção iniciais como finais.

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

"Verificação de usuário falhou" (403)

Causa: Chave de API inválida ou expirada

Solução:

1. Verifique se sua chave de API está correta
2. Verifique se sua chave de API está ativa em sua conta
3. Tente regenerar sua chave de API

"Não há créditos suficientes" (403)

Causa: Créditos insuficientes para processamento de imagem

Solução:

1. Verifique seus créditos restantes usando /check-user-credits
2. Compre créditos adicionais se necessário
3. Otimize o tamanho das imagens antes do upload para consumir menos créditos

"Formato de arquivo não suportado" (400)

Causa: Formato de imagem não suportado ou inválido enviado

Solução:

1. Verifique se o formato da imagem é suportado (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
2. Certifique-se de que o arquivo não está corrompido
3. Verifique o Content-Type header ao fazer upload

"Arquivo muito grande" (400)

Causa: Tamanho do arquivo excede o limite de 10MB

Solução:

1. Redimensione ou comprima a imagem para menos de 10MB
2. Verifique o tamanho do arquivo antes do upload
3. Use formatos mais eficientes como WebP quando possível

"Tempo limite da solicitação" (WebSocket)

Causa: O processamento da imagem demorou muito tempo

Solução:

1. Tente com uma imagem menor ou menos complexa
2. Verifique se o serviço está passando por alta carga
3. Tente novamente a solicitação

Status do Documento "falhou"

Causa: O processamento falhou por várias razões

Solução:

1. Verifique se a imagem atende aos requisitos mínimos (1KB - 10MB)
2. Verifique se a imagem está em um formato suportado
3. Verifique se o upload foi concluído com sucesso antes de enviar para detecção
4. Entre em contato com o suporte se o problema persistir

"Falha no upload da imagem" (403/400)

Causa: URL pré-assinada inválida ou expirada, ou problemas com o servidor de armazenamento

Solução:

1. Certifique-se de usar a URL pré-assinada imediatamente após recebê-la (pode expirar)
2. Verifique se o Content-Type header está correto para o formato da imagem
3. Remova espaços do nome do arquivo antes do upload
4. Tente gerar uma nova URL pré-assinada se a atual expirou

"URL pré-assinada inválida" (400)

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

Solução:

1. Remova todos os espaços do nome do arquivo antes de solicitar a URL pré-assinada
2. Use apenas caracteres alfanuméricos, hífens e underscores no nome do arquivo
3. Gere uma nova URL pré-assinada se necessário