Documentazione API
ISO 27001SOC 2 CertifiedGDPR Compliant

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_ID

Devi 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/detect

Soglia

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/query

Richiesta 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-credits

Richiesta 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_ID

Codice 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/detect

Richiesta 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 ErroreSignificato
400Bad Request -- La tua richiesta non è valida.
403Forbidden -- La chiave API non è valida o non ci sono crediti sufficienti (0.1 per parola).
404Not Found -- La risorsa specificata non esiste.
405Method Not Allowed -- Hai provato ad accedere a una risorsa con un metodo non valido.
406Not Acceptable -- Hai richiesto un formato che non è JSON.
410Gone -- La risorsa a questo endpoint è stata rimossa.
422Invalid Request Body -- Il tuo corpo richiesta è formattato in modo errato o non valido o ha parametri mancanti.
429Too Many Requests -- Stai inviando troppe richieste! Rallenta!
500Internal Server Error -- Abbiamo avuto un problema con il nostro server. Riprova più tardi.
503Service 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:

  1. Verifica che la tua chiave API sia corretta
  2. Controlla se la tua chiave API è attiva nel tuo account
  3. Prova a rigenerare la tua chiave API

"Not enough credits" (403)

Causa: Crediti insufficienti per l'elaborazione del testo

Soluzione:

  1. Controlla i tuoi crediti rimanenti usando /check-user-credits
  2. Acquista crediti aggiuntivi se necessario
  3. 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:

  1. Assicurati che il tuo input di testo non sia vuoto
  2. Rimuovi eventuali spazi bianchi iniziali/finali
  3. Controlla se la codifica del testo è corretta

"Input email is empty" (400)

Causa: Email mancante per l'elaborazione URL

Soluzione:

  1. Fornisci un indirizzo email valido quando invii URL
  2. 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:

  1. Prova con un input di testo più piccolo
  2. Controlla se il servizio sta sperimentando alto carico
  3. Riprova la richiesta

Stato Documento "failed"

Causa: Elaborazione fallita per vari motivi

Soluzione:

  1. Controlla se il testo di input soddisfa i requisiti minimi
  2. Verifica che il testo sia in un formato supportato
  3. Prova con un modello diverso
  4. Contatta il supporto se il problema persiste

Problemi di Connessione WebSocket

Cadute di Connessione

Causa: Problemi di rete o disconnessioni server

Soluzione:

  1. Controlla la tua connessione di rete
  2. Implementa logica di riconnessione
  3. Verifica che l'URL WebSocket sia corretto

"User not found" (WebSocket)

Causa: ID Organizzazione non valido nella connessione WebSocket

Soluzione:

  1. Verifica che l'ID Organizzazione sia corretto
  2. Assicurati che l'account utente sia attivo
  3. 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.