Documentação da API
ISO 27001SOC 2 CertifiedGDPR Compliant

API de Detecção de Vídeo Gerado por IA

Documentação completa para integrar a API de detecção de vídeo IA da TruthScan em suas aplicações.

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

Preços e créditos

Cada solicitação de detecção de vídeo consome créditos da sua conta quando o processamento é concluído.

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

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.

A TruthScan espera que a chave de API seja incluída em todas as solicitações de API para o servidor no corpo da solicitação da seguinte forma:

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

Você deve substituir YOUR API KEY GOES HERE pela sua chave de API pessoal.

Detector de Vídeo IA

Detectar (Processo de 2 Etapas)

O fluxo de trabalho de detecção de vídeo IA consiste em duas etapas:

  • Enviar o vídeo para detecção (upload multipart ou URL)
  • Consultar o trabalho para recuperar resultados

Modelos de Detecção

Selecione qual modelo ML executa durante o pipeline de detecção usando o parâmetro opcional model. Se omitido, generic é usado.

  • generic: Modelo de detecção geral de vídeo IA (padrão)
  • faceswap: Modelo dedicado de detecção de vídeos Face Swap

Ambos os modelos usam o mesmo pipeline de detecção (metadata → watermark → ML) e retornam o mesmo formato de resposta. Valores inválidos de model retornam 422.

1. Enviar o Vídeo

Faça upload de um arquivo de vídeo diretamente para a API ou envie uma URL de vídeo. O servidor validará o arquivo.

Formatos de Arquivo Suportados

mp4, mov, avi, mkv, webm

Limites de Tamanho de Arquivo

  • Tamanho mínimo de arquivo: 1KB
  • Tamanho máximo de arquivo: 100MB
Enviar via upload de arquivo

Headers

  • key (obrigatório): Sua chave de API
  • email: Endereço de email opcional
  • userkey: Chave de usuário de integração opcional

Multipart form-data

  • file (obrigatório): O vídeo a ser analisado
  • model: Modelo de detecção a usar, ou seja, generic ou faceswap (opcional, padrão: generic)
POST https://detect-video.truthscan.com/detect-file

Exemplo de Solicitação

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

Exemplo com modelo Face Swap

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4' \
  -F 'model=faceswap'

Parâmetros Opcionais

  • document_type: Tipo de documento (padrão: Video)
  • email: Endereço de email para processamento
  • model: Modelo de detecção, ou seja, generic ou faceswap (padrão: generic)
Enviar via URL

Headers

  • Content-Type: application/json

Body (JSON)

  • key (obrigatório): Sua chave de API
  • url: https://ai-video-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>
  • model: Modelo de detecção a usar, ou seja, generic ou faceswap (opcional, padrão: generic)
POST https://detect-video.truthscan.com/detect

Exemplo de Solicitação

curl -X POST \
  'https://detect-video.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://example.com/video.mp4",
  "model": "generic"
}'

Exemplo com modelo Face Swap

curl -X POST \
  'https://detect-video.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://example.com/video.mp4",
  "model": "faceswap"
}'

Parâmetros Opcionais

  • document_type: Tipo de documento (padrão: Video)
  • email: Endereço de email para processamento
  • model: Modelo de detecção, ou seja, generic ou faceswap (padrão: generic)

Exemplo de Resposta

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

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

2. Consultar Status e Resultados da Detecção

Após enviar, consulte o endpoint /query com o ID do trabalho para recuperar status e resultados.

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

Exemplo de Solicitação

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

Exemplo de Resposta

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

Detalhes dos Resultados

  • status: "pending", "analyzing", "done", ou "failed"
  • result: Pontuação escalar de probabilidade de IA em [0.0, 1.0] (valores mais altos = mais provável ser gerado por IA), derivada de ML prob_fake
  • final_stage: Último estágio que contribuiu para o resultado: 'metadata', 'watermark' ou 'ml'
  • metadata: Sempre define prediction: 'no_detection' e confidence: 0.0. Status pode ser 'reject', 'reencode' ou 'ok'
  • watermark: Heurística que amostra frames e calcula confiança pseudo a partir da variância de pixels
  • ml: Modelo classificador executado em frames amostrados. Retorna prob_fake em [0.0, 1.0] e label ('ai_generated' se prob_fake ≥ 0.5, senão 'no_detection')
  • latency_sec: Tempo total do pipeline

O campo "status" será um dos seguintes: "pending" (processamento em fila), "analyzing" (detecção de IA em progresso), "done" (resultados disponíveis), ou "failed" (processamento falhou).

Verificar Créditos do Usuário

Este endpoint aceita o apikey do usuário via header. E retorna detalhes de créditos do usuário.

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

Exemplo de Solicitação

curl -X 'GET' \
  'https://detect-video.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
}

Verificação de Saúde

Verifique o status de saúde do servidor da API.

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

Exemplo de Solicitação

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

Exemplo de Resposta

{
  "status": "healthy"
}

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.
403Forbidden -- A chave de API é inválida ou não há créditos suficientes para processamento de vídeo.
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.

Problemas Comuns e Soluções

Problemas de Autenticação

"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 vídeo

Solução:

  1. Verifique seus créditos restantes usando /check-user-credits
  2. Compre créditos adicionais se necessário

Problemas de Validação de Entrada

"Tipo de vídeo não suportado" (400)

Causa: Formato de vídeo não suportado

Solução:

  1. Converta o vídeo para um formato suportado (MP4, MOV, AVI, MKV, WEBM)
  2. Certifique-se de que a extensão do arquivo e o tipo MIME estão corretos

"Tamanho do arquivo excede o limite" (400)

Causa: Arquivo de vídeo muito grande

Solução:

  1. Comprima, corte ou re-codifique o vídeo para reduzir o tamanho (máximo 100MB)
  2. Use um codec/container mais eficiente

"Tamanho do arquivo é muito pequeno" (400)

Causa: Arquivo de vídeo está abaixo do requisito de tamanho mínimo

Solução:

  1. Use um arquivo de vídeo maior (mínimo 1KB)
  2. Verifique se o arquivo foi corrompido durante o upload

"Tipo de arquivo inválido" (400)

Causa: Validação do tipo de arquivo falhou (por exemplo, tipo MIME incorreto ou arquivo corrompido)

Solução:

  1. Certifique-se de que o arquivo é um formato de vídeo válido
  2. Verifique se o tipo MIME corresponde à extensão do arquivo
  3. Re-exporte ou re-codifique o arquivo se necessário

Valor de model inválido (422)

Causa: O parâmetro model não é generic ou faceswap

Solução:

  1. Omita model para usar o modelo generic padrão
  2. Defina model como generic para detecção geral de vídeo IA
  3. Defina model como faceswap para detecção de vídeos Face Swap

Problemas de Processamento

Status "falhou" do vídeo

Causa: Processamento falhou (por exemplo, container ilegível, erros de decodificação)

Solução:

  1. Certifique-se de que o container/codec é comumente suportado (H.264/AAC em MP4 recomendado)
  2. Re-codifique o vídeo usando um preset padrão (por exemplo, ffmpeg) e re-envie
  3. Certifique-se de que o arquivo atende aos requisitos de tamanho e formato
  4. Entre em contato com o suporte se o problema persistir

"Usuário não encontrado"

Causa: ID de usuário inválido

Solução:

  1. Verifique se sua chave de API está correta e vinculada a uma conta ativa
  2. Certifique-se de que o usuário de integração é válido e ativo
  3. Re-autentique se necessário

"Metadados do arquivo não puderam ser obtidos" (500)

Causa: Incapaz de acessar ou analisar o arquivo enviado

Solução:

  1. Verifique se o upload foi concluído com sucesso
  2. Verifique se o arquivo está acessível e não está corrompido
  3. Tente re-enviar o arquivo

Precisa de Ajuda?

Para mais informações sobre como usar nossa API ou para suporte técnico, entre em contato conosco.

Contate-nos

Perguntas Frequentes sobre a API

Encontre respostas para as perguntas mais comuns sobre nossa API de detecção de vídeo IA.