Documentação da API

API de Detecção de Áudio Gerado por IA

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

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

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 Áudio IA

Detectar

O fluxo de trabalho de detecção de áudio IA consiste nas seguintes etapas:

  • Obter uma URL de upload pré-assinada
  • Fazer upload do áudio
  • Enviar o áudio para detecção

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 áudio para o servidor de armazenamento com segurança.

Formatos de Arquivo Suportados

MP3, WAV, M4A, FLAC, OGG

Nota Importante

É necessário remover espaços do nome do arquivo de áudio ao solicitar uma URL pré-assinada.

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

Exemplo de Solicitação

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

Exemplo de Resposta

{
  "status": "success",
  "presigned_url": "https://nyc3.digitaloceanspaces.com/ai-audio-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...",
  "file_path": "https://ai-audio-detector-prod.nyc3.digitaloceanspaces.com/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250901-090201_example.mp3"
}

2. Fazer Upload do Áudio

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

Nota Importante

É necessário remover espaços do nome do arquivo de áudio ao fazer upload do áudio.

Exemplo de Solicitação

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-audio-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

Limites de Tamanho de Arquivo

  • Tamanho mínimo de arquivo: 1KB
  • Tamanho máximo de arquivo: 10MB

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 Áudio para Detecção de IA

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

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

Exemplo de Solicitação

curl -X 'POST' \
  'https://detect-audio.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'

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

Parâmetros Opcionais

  • analyzeUpToSeconds: Analisar até N segundos do início (padrão: 60)
  • document_type: Tipo de documento (padrão: 'Audio')
  • email: Endereço de email opcional para processamento

Exemplo de Resposta

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

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

Consultar Status e Resultados da Detecção

Para verificar o status e recuperar os resultados, use o endpoint /query com o ID.

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

Exemplo de Solicitação

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

Exemplo de Resposta

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 0.873,
    "result_details": {
        "is_valid": true,
        "message": "processed",
        "original_duration": 123.45,
        "is_truncated": true,
        "truncated_duration": 60.0,
        "mean_ai_prob": 0.873,
        "individual_chunks_ai_prob": [0.81, 0.90, 0.91]
    }
}

Detalhes dos Resultados

  • is_valid: Indica se o arquivo de áudio é válido (true/false)
  • message: Mensagem de processamento
  • original_duration: Duração em segundos do áudio original
  • is_truncated: Se o áudio foi truncado para análise
  • truncated_duration: Duração analisada se truncado
  • mean_ai_prob: Pontuação geral de probabilidade de IA
  • individual_chunks_ai_prob: Pontuações de probabilidade de IA por chunk

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-audio.truthscan.com/check-user-credits

Exemplo de Solicitação

curl -X 'GET' \
  'https://detect-audio.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-audio.truthscan.com/health

Exemplo de Solicitação

curl -X 'GET' \
  'https://detect-audio.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 áudio.
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 áudio

Solução:

  1. Verifique seus créditos restantes usando /check-user-credits
  2. Compre créditos adicionais se necessário
  3. Use analyzeUpToSeconds para analisar menos áudio e consumir menos créditos

Problemas de Validação de Entrada

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

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

Solução:

  1. Verifique se o formato do áudio é suportado (MP3, WAV, M4A, FLAC, OGG)
  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. Comprima ou converta o áudio para menos de 10MB
  2. Verifique o tamanho do arquivo antes do upload
  3. Use formatos mais eficientes como MP3 quando possível

Problemas de Processamento

"Processamento de áudio demorou muito tempo"

Causa: O processamento do áudio demorou muito tempo ou timeout ocorreu

Solução:

  1. Tente com um arquivo de áudio menor ou menos duração
  2. Use analyzeUpToSeconds para analisar apenas os primeiros segundos
  3. Verifique se o serviço está passando por alta carga
  4. Tente novamente a solicitação após alguns minutos

Status "falhou" na resposta do /query

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

Solução:

  1. Verifique se o áudio atende aos requisitos mínimos (1KB - 10MB)
  2. Verifique se o áudio 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

Problemas de Upload

"Falha no upload do áudio" (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 do áudio
  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

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 áudio IA.

Você pode obter sua chave de API visitando sua conta no portal de desenvolvedores da TruthScan. A chave de API está disponível no topo da página da sua conta.