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_IDVocê 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/detectThreshold
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/queryExemplo 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-creditsExemplo 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_IDCó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/detectExemplo 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 Erro | Significado |
|---|---|
| 400 | Bad Request -- Sua solicitação é inválida. |
| 403 | Forbidden -- A chave de API é inválida ou não há créditos suficientes (0,1 por palavra). |
| 404 | Not Found -- O recurso especificado não existe. |
| 405 | Method Not Allowed -- Você tentou acessar um recurso com um método inválido. |
| 406 | Not Acceptable -- Você solicitou um formato que não é JSON. |
| 410 | Gone -- O recurso neste endpoint foi removido. |
| 422 | Invalid Request Body -- O corpo da sua solicitação está formatado incorretamente ou inválido ou tem parâmetros ausentes. |
| 429 | Too Many Requests -- Você está enviando muitas solicitações! Diminua a velocidade! |
| 500 | Internal Server Error -- Tivemos um problema com nosso servidor. Tente novamente mais tarde. |
| 503 | Service 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:
- Verifique se sua chave de API está correta
- Verifique se sua chave de API está ativa em sua conta
- Tente regenerar sua chave de API
"Não há créditos suficientes" (403)
Causa: Créditos insuficientes para processamento de texto
Solução:
- Verifique seus créditos restantes usando /check-user-credits
- Compre créditos adicionais se necessário
- 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:
- Garanta que sua entrada de texto não esteja vazia
- Remova quaisquer espaços em branco à esquerda/direita
- 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:
- Forneça um endereço de email válido ao enviar URLs
- 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:
- Tente com uma entrada de texto menor
- Verifique se o serviço está passando por alta carga
- Tente novamente a solicitação
Status do Documento "falhou"
Causa: O processamento falhou por várias razões
Solução:
- Verifique se o texto de entrada atende aos requisitos mínimos
- Verifique se o texto está em um formato suportado
- Tente com um modelo diferente
- 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:
- Verifique sua conexão de rede
- Implemente lógica de reconexão
- 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:
- Verifique se o ID do usuário está correto
- Garanta que a conta do usuário esteja ativa
- 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.