Documentação da API

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 ID do usuário como parte da URL. Você pode obter seu ID de usuário no topo da página em nosso portal de desenvolvedores.

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

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

Você deve substituir $USER_ID pelo seu ID de usuário 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
}'

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

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,
    "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
    },
    "status": "done",
    "retry_count": 0
}

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
}

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/$USER_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: ID de usuário inválido na conexão WebSocket

Solução:

  1. Verifique se o ID do usuário 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.

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.