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

API de Detecção de Texto Gerado por IA

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

Teste a API sem código visitando nosso endpoint FastAPI: https://detect-text.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.

Para cenários de web socket, você precisará enviar o Organization ID como parte da URL. Você pode obter seu Organization ID no topo da página em nosso portal de desenvolvedores.

A TruthScan espera que o Organization ID seja incluído na URL de todas as solicitações de web socket. A documentação ficará assim:

wss://detect-text.truthscan.com/ws/$ORG_ID

Você deve substituir $ORG_ID pelo seu Organization ID pessoal.

Detector de IA

Detectar

Este endpoint permite que você envie texto para detecção de IA. Pelo menos 200 palavras são recomendadas para melhor precisão.

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

Threshold

Este endpoint retorna uma pontuação "result" de 1-100. Para melhor precisão, qualquer pontuação abaixo de 50 é considerada definitivamente humana. 50-60 é possível IA. Acima de 60 é IA definitiva. Este é o resultado mais preciso, com 99%+ de precisão.

As pontuações para outros detectores, como Writer e Copyleaks, são aproximadas e não tão precisas quanto a pontuação principal "result".

Quebras de linha

Se você estiver enviando dados como JSON, as quebras de linha devem ser codificadas como \n dentro da string.

Exemplo de Solicitação

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0,
  "generate_analysis_details": true
}'

Aqui, a entrada da solicitação deve ser inferior a 30.000 palavras.

Parâmetros Opcionais

  • model: Modelo de detecção de IA a ser usado (padrão: 'xlm_ud_detector')
  • retry_count: Número de tentativas em caso de falha no processamento (padrão: 0)
  • generate_analysis_details: Definir como 'true' para habilitar resultados de análise aprofundada de IA (padrão: 'false'). Quando habilitado, a resposta da consulta incluirá os campos analysis_results_status e analysis_results.

Exemplo de Resposta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

A resposta contém o ID atribuído pelo servidor do documento. Neste ponto, o documento está na fila para processamento. Você pode usar o endpoint da API /query para consultar o status da solicitação de detecção de IA. O tempo médio para concluir uma verificação de detecção de IA é entre 2-4 segundos. Pode levar mais tempo dependendo da contagem de palavras.

Consultar

Este endpoint aceita um ID de documento retornado pela solicitação /detect. E retorna o status do envio do documento, bem como o resultado da operação de detecção de IA conforme tratado por vários detectores de IA de terceiros.

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

Exemplo de Solicitação

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

Exemplo de Resposta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "result_categories": {
        "advanced": 12,
        "standard": 12
    },
    "status": "done",
    "retry_count": 0
}

Interpretação dos Resultados

  • result: Pontuação de 0-100 indicando a probabilidade do texto ser gerado por IA. Abaixo de 50 = definitivamente humano. 50-60 = possivelmente IA. Acima de 60 = definitivamente IA.
  • label: A determinação geral: 'Human', 'AI' ou 'Paraphrase'
  • result_details scores: Pontuações aproximadas de detectores de terceiros: GPTZero, OpenAI, Writer, CrossPlag, CopyLeaks, Sapling, ContentAtScale, ZeroGPT (cada um 0, 50 ou 100)
  • human: Média de todas as pontuações dos detectores de terceiros indicando quão humano o texto parece
  • result_categories.advanced: Categoria de resultado avançada com pontuação escalonada (formato 1-99)
  • result_categories.standard: Categoria de resultado padrão
  • analysis_results_status: Status da análise aprofundada de IA ('pending', 'ready', 'skipped' ou null). Quando 'pending', continue consultando o endpoint /query — a análise ainda está sendo processada em segundo plano. Quando 'ready', o campo analysis_results contém a análise concluída. Quando 'skipped', null ou ausente, a análise aprofundada não está disponível para este texto.
  • analysis_results: Resultados da análise aprofundada de IA (disponível quando analysis_results_status é 'ready'). Contém: agreement (strong/moderate/weak/disagreement), confidence (0-100), keyIndicators (array de indicadores textuais encontrados), detailedReasoning (explicação), linguisticPatterns (array de padrões linguísticos observados) e recommendations (itens acionáveis).

Aqui, "result": 12.0 indica a human-ness da entrada. Isso significa que, dado que é menor que o threshold de 50%, o texto é definitivamente humano. Da mesma forma, os valores sob result_details indicam a Human-ness da entrada. Por exemplo, "scoreZeroGPT": 50.0 significa que o texto provavelmente é 50% escrito por humanos de acordo com o ZeroGPT. O mesmo vale para o resto dos outros detectores.

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

Exemplo de Solicitação

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

Resultados da Análise (Análise Aprofundada Assíncrona)

Quando você define 'generate_analysis_details' como 'true' na solicitação /detect, o TruthScan executa uma análise aprofundada de IA em segundo plano após a conclusão da detecção inicial. A resposta inicial da consulta retornará com status 'done' e seus resultados de detecção prontos para uso, mas o campo analysis_results_status pode ainda estar 'pending'. Você pode usar os resultados iniciais imediatamente e opcionalmente consultar até que a análise aprofundada seja concluída.

1. Resultado Inicial Estabelecido (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, label, result_details) estão prontos. No entanto, analysis_results_status pode ser 'pending' — isso significa que a análise aprofundada de IA ainda está sendo processada em segundo plano.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

O que fazer

Você pode usar os resultados iniciais de detecção (result, label, pontuações de result_details) imediatamente. Se também precisar da análise aprofundada, continue consultando o endpoint /query com o mesmo ID do documento até que analysis_results_status mude de 'pending'.

2. Continue Consultando os Resultados da Análise

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

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

3. Análise Concluída — Resposta Completa

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

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "ready",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 78,
            "keyIndicators": [
                "Highly consistent sentence structure throughout",
                "Formulaic transitions between paragraphs",
                "Lack of personal voice or idiosyncratic expressions"
            ],
            "detailedReasoning": "The text exhibits hallmarks of AI-generated content including uniform sentence complexity, predictable paragraph transitions, and an absence of personal stylistic quirks. The vocabulary choices are sophisticated but lack the natural variation typical of human writing.",
            "linguisticPatterns": [
                "Uniform sentence length distribution",
                "Repetitive use of hedging language",
                "Absence of colloquialisms or informal markers"
            ],
            "recommendations": [
                "Cross-reference with the original source if available",
                "Check for consistent writing style across longer documents",
                "Compare with known writing samples from the claimed author",
                "Consider the context in which the text was produced"
            ]
        }
    },
    "result_categories": {
        "advanced": 73,
        "standard": 73
    }
}

Quando a Análise Não Está Disponível

Se analysis_results_status for 'skipped', null ou ausente, não será produzida análise aprofundada para este texto. Isso acontece quando 'generate_analysis_details' não foi definido como 'true' na solicitação /detect, ou em certos cenários de processamento. Você deve tratar os resultados iniciais de detecção como finais.

{
    "status": "done",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

Campos dos Resultados da Análise

  • analysis_results_status: 'pending' = ainda processando, 'ready' = resultados disponíveis, 'skipped' / null / ausente = não disponível para este texto
  • analysis_results.agreement: Quão fortemente a análise aprofundada concorda com a detecção inicial (strong / moderate / weak / disagreement)
  • analysis_results.confidence: Pontuação de confiança da análise aprofundada (0-100)
  • analysis_results.keyIndicators: Array de indicadores textuais específicos encontrados no texto
  • analysis_results.detailedReasoning: Explicação de 2-4 frases sobre por que o texto foi classificado desta forma
  • analysis_results.linguisticPatterns: Array de padrões linguísticos observados (ex.: consistência na estrutura das frases, padrões de vocabulário)
  • analysis_results.recommendations: Array de recomendações acionáveis para entender a autenticidade do texto

Detecção de IA em Nível de Sentença

O detector de IA em nível de sentença executa sobre um protocolo baseado em WebSocket.

Aqui estão as etapas necessárias para obter resultados em nível de sentença para seu texto:

  • Conectar ao WebSocket
  • Ouvir todos os eventos recebidos do WebSocket
  • Enviar uma solicitação document_watch
  • Receber um evento document_id
  • Pegar o id gerado pela resposta document_id e enviar um documento para detecção de IA
  • Começar a receber eventos document_chunk. Os eventos document_chunk retornarão cada sentença junto com o resultado em nível de sentença
  • Quando o documento terminar o processamento, você receberá um evento document_done

Conectar ao WebSocket

Este endpoint permite que você estabeleça a conexão WebSocket

wss://detect-text.truthscan.com/ws/$ORG_ID

Código de Exemplo

ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");

Ouvir todos os eventos recebidos do WebSocket

Uma vez que a conexão WebSocket seja estabelecida, ouça eventos enviados através da conexão WebSocket.

Código de Exemplo

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

Enviar uma solicitação document_watch

Envie interesse em enviar um documento enviando uma solicitação document_watch no WebSocket

Código de Exemplo

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

Receber um evento document_id

Depois de enviar um evento document_watch, o servidor retorna um evento document_id.

Exemplo de Resposta

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Enviar uma Solicitação de Detecção de IA

Pegue o id gerado pela resposta document_id e envie um documento para detecção de IA

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

Exemplo de Solicitação

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

Receber resultados em nível de sentença

Comece a receber eventos document_chunk. Os eventos document_chunk retornarão cada sentença junto com o resultado em nível de sentença

Exemplo de Resposta

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

Quando o documento terminar o processamento, você receberá um evento document_done.

Exemplo de Resposta

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector"
}

Lidar com circunstâncias excepcionais

Se por alguma razão o servidor encontrar um erro ao fazer a detecção de IA, um evento document_error será enviado para o cliente websocket. O cliente deve agir adequadamente, por exemplo, uma UI mostrará uma mensagem de erro.

Por exemplo, o servidor enviará um código de erro REQUEST_TIMEOUT quando levar mais de 20 segundos entre eventos de chunk.

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds."
}

Cancelamentos

Haverá instâncias em que a UI gostaria de cancelar a operação. O usuário decide fechar a janela ou cancela o evento explicitamente

Quando isso acontecer, você deve enviar um evento document_halt

Exemplo de Resposta

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

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 (0,1 por palavra).
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 texto

Solução:

  1. Verifique seus créditos restantes usando /check-user-credits
  2. Compre créditos adicionais se necessário
  3. Use entradas de texto mais curtas para consumir menos créditos

Problemas de Validação de Entrada

"O texto de entrada não pode estar vazio" (400)

Causa: Texto vazio ou apenas com espaços em branco enviado

Solução:

  1. Garanta que sua entrada de texto não esteja vazia
  2. Remova quaisquer espaços em branco à esquerda/direita
  3. Verifique se a codificação de texto está correta

"O email de entrada está vazio" (400)

Causa: Email ausente para processamento de URL

Solução:

  1. Forneça um endereço de email válido ao enviar URLs
  2. Verifique se o formato do email está correto

Problemas de Processamento

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

Causa: O processamento do documento demorou muito (>120 segundos)

Solução:

  1. Tente com uma entrada de texto menor
  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 o texto de entrada atende aos requisitos mínimos
  2. Verifique se o texto está em um formato suportado
  3. Tente com um modelo diferente
  4. Entre em contato com o suporte se o problema persistir

Problemas de Conexão WebSocket

Quedas de Conexão

Causa: Problemas de rede ou desconexões do servidor

Solução:

  1. Verifique sua conexão de rede
  2. Implemente lógica de reconexão
  3. Verifique se a URL do WebSocket está correta

"Usuário não encontrado" (WebSocket)

Causa: Organization ID inválido na conexão WebSocket

Solução:

  1. Verifique se o Organization ID está correto
  2. Garanta que a conta do usuário esteja ativa
  3. Reautentique se necessário

Precisa de Ajuda?

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

Perguntas Frequentes sobre a API

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