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

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.

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.

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.

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_overlayed: Controla como o mapa de calor é gerado (padrão: true). true: sobreposto à imagem original; false: PNG RGBA transparente para compor na interface.
generate_heatmap_normalized: false pula a normalização do mapa de ativação (padrão: true). 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.

Exemplo de resposta

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

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

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.

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,
        "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,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detect.undetectable.ai/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
        "analysis_results_status": "ready",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detect.undetectable.ai/preview/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.
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.
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. Geração de mapa de calor é assíncrona.
heatmap_url: Mapa de calor quando heatmap_status é ready. 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

Geração do mapa de calor é assíncrona. Consulte /query para heatmap_status e heatmap_url.
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): sobreposição padrão (true) é uma imagem normal com o mapa sobreposto; false costuma ser PNG transparente para composição.

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

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,
        "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,
        "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_overlayed: Mesmo comportamento de /detect (sobreposição vs RGBA transparente).
generate_heatmap_normalized: Mesmo comportamento de /detect (padrão: true).
model: Domínio do modelo: generic ou instance_id/model.

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).

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

Interno: sincronizar uso da organização com Stripe (segredo do job)

Apenas jobs de backend confiáveis, não clientes gerais da API. Exige cabeçalho x-job-secret igual ao JOB_SECRET do servidor. Sincroniza uso medido da organização TruthScan com Stripe para um intervalo de datas.

POST /organizations/{org_id}/usage/sync-to-stripe

Cabeçalhos: x-job-secret: <JOB_SECRET>

Corpo JSON: start_date, end_date, idempotency_id opcional para Stripe.

Retorna success, organization_id, total_documents, value_sent_to_stripe, report_date, message. 400 se org não medida ou faltar stripe_customer_id; 401 segredo inválido; 404 org não encontrada; 500 Stripe/configuração.

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 — Muitas requisições; reduza a taxa.
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

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

Precisa de ajuda?

Para mais informações sobre a API ou suporte técnico, entre em contato.

Fale conosco

Perguntas frequentes da API

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