API di Rilevamento Testo AI
Documentazione completa per integrare l'API di rilevamento AI di TruthScan nelle tue applicazioni.
Provalo senza codice visitando il nostro endpoint FastAPI: https://detect-text.truthscan.com/docs
Autenticazione
TruthScan usa chiavi API per consentire l'accesso all'API. Puoi ottenere la tua chiave API al in alto nella pagina del nostro portale sviluppatori.
TruthScan si aspetta che la chiave API sia inclusa in tutte le richieste API al server in un corpo richiesta che assomiglia al seguente:
{
"key": "YOUR API KEY GOES HERE"
}Devi sostituire IL TUO CHIAVE API VA QUI con la tua chiave API personale.
Per scenari web socket, dovrai inviare il tuo ID Organizzazione come parte dell'url. Puoi ottenere il tuo ID Organizzazione al in alto nella pagina del nostro portale sviluppatori.
TruthScan si aspetta che il tuo ID Organizzazione sia incluso nell'url di tutte le richieste web socket. La documentazione assomiglierà al seguente:
wss://detect-text.truthscan.com/ws/$ORG_IDDevi sostituire $ORG_ID con il tuo ID Organizzazione personale.
Rilevatore AI
Rileva
Questo endpoint ti permette di inviare testo per il rilevamento AI. Almeno 200 parole sono raccomandate per la migliore accuratezza.
POST https://detect-text.truthscan.com/detectSoglia
Questo endpoint restituisce un punteggio "result" da 1-100. Per la migliore accuratezza, qualsiasi punteggio sotto 50 è considerato definitivamente umano. 50-60 è possibile AI. Sopra 60 è definitivamente AI. Questo è il risultato più accurato, con accuratezza 99%+.
I punteggi per altri rilevatori, come Writer e Copyleaks, sono approssimativi e non accurati come il punteggio "result" principale.
Interruzioni di riga
Se stai inviando dati come JSON, le interruzioni di riga dovrebbero essere codificate come \n all'interno della stringa.
Richiesta di Esempio
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
}'Qui, l'input della richiesta deve essere inferiore a 30.000 parole.
Risposta di Esempio
{
"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
}La risposta contiene l'ID assegnato dal server del documento. A questo punto il documento è ora in coda per l'elaborazione. Puoi usare l'endpoint API /query per interrogare lo stato della richiesta di Rilevamento AI. Il tempo medio per completare un controllo di Rilevamento AI è tra 2-4 secondi. Potrebbe richiedere più tempo a seconda del conteggio delle parole.
Interroga
Questo endpoint accetta un id documento restituito dalla richiesta /detect. E restituisce lo stato della sottomissione del documento così come il risultato dell'operazione di Rilevamento AI gestita da vari rilevatori AI di terze parti.
POST https://detect-text.truthscan.com/queryRichiesta di Esempio
curl -X 'POST' \
'https://detect-text.truthscan.com/query' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"id": "DOCUMENT-ID-GOES-HERE"
}'Risposta di Esempio
{
"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
}Qui, "result": 12.0 indica l'umanità dell'input. Questo significa che dato che è inferiore alla soglia del 50%, il testo è definitivamente umano. Similmente i valori sotto result_details indicano l'Umanità dell'input. Per esempio "scoreZeroGPT": 50.0 significa che il testo è probabilmente 50% scritto da umano secondo ZeroGPT. Lo stesso vale per il resto degli altri rilevatori.
Controlla Crediti Utente
Questo endpoint accetta l'apikey degli utenti tramite l'header. E restituisce i dettagli dei crediti degli utenti.
GET https://detect-text.truthscan.com/check-user-creditsRichiesta di Esempio
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'Risposta di Esempio
{
"baseCredits": 10000,
"boostCredits": 1000,
"credits": 11000
}Rilevamento AI a Livello di Frase
Il Rilevatore AI a livello di frase gira sopra un protocollo basato su WebSocket.
Ecco i passaggi necessari per ottenere risultati a livello di frase per il tuo testo:
- Connettiti al WebSocket
- Ascolta tutti gli eventi ricevuti dal WebSocket
- Invia una richiesta document_watch
- Ricevi un evento document_id
- Prendi l'id generato dalla risposta document_id e invia un documento per il Rilevamento AI
- Inizia a ricevere eventi document_chunk. Gli eventi document_chunk restituiranno ogni frase insieme al risultato a livello di frase
- Quando il documento finisce l'elaborazione, riceverai un evento document_done
Connettiti al WebSocket
Questo endpoint ti permette di stabilire la connessione WebSocket
wss://detect-text.truthscan.com/ws/$ORG_IDCodice di esempio
ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");Ascolta tutti gli eventi ricevuti dal WebSocket
Una volta stabilita la connessione WebSocket, ascolta gli eventi inviati attraverso la connessione WebSocket.
Codice di esempio
ws.addEventListener("message", (event) => {
console.log("Message from server ", event.data);
});Invia una richiesta document_watch
Mostra interesse per un documento inviando una richiesta document_watch via WebSocket
Codice di esempio
ws.send(JSON.stringify({
"event_type": "document_watch",
"api_key": "$API_KEY",
}))Ricevi un evento document_id
Dopo aver inviato un evento document_watch, il server restituisce un evento document_id.
Risposta di esempio
{
"event_type": "document_id",
"success": true,
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}Invia una Richiesta di Rilevamento AI
Usa l'id generato dalla risposta document_id per inviare un documento al Rilevamento AI
POST https://detect-text.truthscan.com/detectRichiesta di Esempio
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"
}'Ricevi risultati a livello di frase
Inizia a ricevere eventi document_chunk. Gli eventi document_chunk restituiranno ogni frase insieme al risultato a livello di frase
Risposte di esempio
{
"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 il documento finisce l'elaborazione, riceverai un evento document_done.
Risposte di esempio
{
"event_type": "document_done",
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
"model": "xlm_ud_detector"
}Gestione di circostanze eccezionali
Se per qualche motivo il server incontra un errore durante l'esecuzione del rilevamento AI, un evento document_error sarà inviato al client websocket. Il client dovrebbe agire di conseguenza, per esempio un'UI mostrerà un messaggio di errore.
Per esempio, il server invierà un codice di errore REQUEST_TIMEOUT quando impiega più di 20 secondi attraverso gli eventi chunk.
{
"event_type": "document_error",
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
"error_code": "REQUEST_TIMEOUT",
"message": "Request timeout. Took 20 seconds."
}Cancellazioni
Ci saranno istanze in cui l'UI vorrebbe cancellare l'operazione. L'utente decide di chiudere la finestra o cancella l'evento esplicitamente
Quando questo accade dovresti inviare un evento document_halt
Risposte di esempio
{
"event_type": "document_halt",
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}Errori
La maggior parte degli errori è causata da parametri errati inviati all'API. Verifica i parametri di ogni chiamata per assicurarti che siano formattati correttamente e prova il codice d'esempio fornito.
I codici di errore generici che usiamo sono conformi allo standard REST:
| Codice Errore | Significato |
|---|---|
| 400 | Bad Request -- La tua richiesta non è valida. |
| 403 | Forbidden -- La chiave API non è valida o non ci sono crediti sufficienti (0.1 per parola). |
| 404 | Not Found -- La risorsa specificata non esiste. |
| 405 | Method Not Allowed -- Hai provato ad accedere a una risorsa con un metodo non valido. |
| 406 | Not Acceptable -- Hai richiesto un formato che non è JSON. |
| 410 | Gone -- La risorsa a questo endpoint è stata rimossa. |
| 422 | Invalid Request Body -- Il tuo corpo richiesta è formattato in modo errato o non valido o ha parametri mancanti. |
| 429 | Too Many Requests -- Stai inviando troppe richieste! Rallenta! |
| 500 | Internal Server Error -- Abbiamo avuto un problema con il nostro server. Riprova più tardi. |
| 503 | Service Unavailable -- Siamo temporaneamente offline per manutenzione. Riprova più tardi. |
Problemi Comuni e Soluzioni
Problemi di Autenticazione
"User verification failed" (403)
Causa: Chiave API non valida o scaduta
Soluzione:
- Verifica che la tua chiave API sia corretta
- Controlla se la tua chiave API è attiva nel tuo account
- Prova a rigenerare la tua chiave API
"Not enough credits" (403)
Causa: Crediti insufficienti per l'elaborazione del testo
Soluzione:
- Controlla i tuoi crediti rimanenti usando /check-user-credits
- Acquista crediti aggiuntivi se necessario
- Usa input di testo più brevi per consumare meno crediti
Problemi di Validazione Input
"Input text cannot be empty" (400)
Causa: Testo vuoto o solo spazi bianchi inviato
Soluzione:
- Assicurati che il tuo input di testo non sia vuoto
- Rimuovi eventuali spazi bianchi iniziali/finali
- Controlla se la codifica del testo è corretta
"Input email is empty" (400)
Causa: Email mancante per l'elaborazione URL
Soluzione:
- Fornisci un indirizzo email valido quando invii URL
- Controlla che il formato email sia corretto
Problemi di Elaborazione
"Request timeout" (WebSocket)
Causa: L'elaborazione del documento ha richiesto troppo tempo (>120 secondi)
Soluzione:
- Prova con un input di testo più piccolo
- Controlla se il servizio sta sperimentando alto carico
- Riprova la richiesta
Stato Documento "failed"
Causa: Elaborazione fallita per vari motivi
Soluzione:
- Controlla se il testo di input soddisfa i requisiti minimi
- Verifica che il testo sia in un formato supportato
- Prova con un modello diverso
- Contatta il supporto se il problema persiste
Problemi di Connessione WebSocket
Cadute di Connessione
Causa: Problemi di rete o disconnessioni server
Soluzione:
- Controlla la tua connessione di rete
- Implementa logica di riconnessione
- Verifica che l'URL WebSocket sia corretto
"User not found" (WebSocket)
Causa: ID Organizzazione non valido nella connessione WebSocket
Soluzione:
- Verifica che l'ID Organizzazione sia corretto
- Assicurati che l'account utente sia attivo
- Riautenticati se necessario
Hai Bisogno di Aiuto?
Per maggiori informazioni sull'uso della nostra API o per supporto tecnico, contattaci.
Domande Frequenti API
Trova risposte alle domande più comuni sulla nostra API di rilevamento AI.