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,
  "generate_analysis_details": true
}'

Qui, l'input della richiesta deve essere inferiore a 30.000 parole.

Parametri Opzionali

  • model: Modello di rilevamento IA da utilizzare (predefinito: 'xlm_ud_detector')
  • retry_count: Numero di tentativi in caso di errore di elaborazione (predefinito: 0)
  • generate_analysis_details: Impostare su 'true' per abilitare i risultati dell'analisi approfondita IA (predefinito: 'false'). Quando abilitato, la risposta della query includerà i campi analysis_results_status e analysis_results.

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,
    "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
}

Interpretazione dei Risultati

  • result: Punteggio da 0-100 che indica la probabilità che il testo sia generato dall'IA. Sotto 50 = sicuramente umano. 50-60 = possibilmente IA. Sopra 60 = sicuramente IA.
  • label: La determinazione complessiva: 'Human', 'AI' o 'Paraphrase'
  • result_details scores: Punteggi approssimativi dai rilevatori di terze parti: GPTZero, OpenAI, Writer, CrossPlag, CopyLeaks, Sapling, ContentAtScale, ZeroGPT (ciascuno 0, 50 o 100)
  • human: Media di tutti i punteggi dei rilevatori di terze parti che indica quanto il testo sembra umano
  • result_categories.advanced: Categoria di risultato avanzata con punteggio a livelli (formato 1-99)
  • result_categories.standard: Categoria di risultato standard
  • analysis_results_status: Stato dell'analisi approfondita IA ('pending', 'ready', 'skipped' o null). Quando 'pending', continuare a interrogare l'endpoint /query — l'analisi è ancora in elaborazione in background. Quando 'ready', il campo analysis_results contiene l'analisi completata. Quando 'skipped', null o assente, l'analisi approfondita non è disponibile per questo testo.
  • analysis_results: Risultati dell'analisi approfondita IA (disponibili quando analysis_results_status è 'ready'). Contiene: agreement (strong/moderate/weak/disagreement), confidence (0-100), keyIndicators (array di indicatori testuali trovati), detailedReasoning (spiegazione), linguisticPatterns (array di modelli linguistici osservati) e recommendations (elementi attuabili).

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
}

Risultati dell'Analisi (Analisi Approfondita Asincrona)

Quando si imposta 'generate_analysis_details' su 'true' nella richiesta /detect, TruthScan esegue un'analisi approfondita IA in background dopo il completamento del rilevamento iniziale. La risposta iniziale della query restituirà con stato 'done' e i risultati del rilevamento pronti all'uso, ma il campo analysis_results_status potrebbe essere ancora 'pending'. È possibile utilizzare i risultati iniziali immediatamente e opzionalmente interrogare fino al completamento dell'analisi approfondita.

1. Risultato Iniziale Stabilito (Analisi Ancora in Attesa)

Quando si invia con 'generate_analysis_details': true e si interroga per la prima volta con stato 'done', i risultati principali del rilevamento (result, label, result_details) sono pronti. Tuttavia, analysis_results_status potrebbe essere 'pending' — questo significa che l'analisi approfondita IA è ancora in elaborazione in background.

{
    "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
    }
}

Cosa fare

È possibile utilizzare i risultati iniziali del rilevamento (result, label, punteggi result_details) immediatamente. Se si necessita anche dell'analisi approfondita, continuare a interrogare l'endpoint /query con lo stesso ID documento fino a quando analysis_results_status cambia da 'pending'.

2. Continuare a Interrogare per i Risultati dell'Analisi

Continuare a chiamare l'endpoint /query con lo stesso ID documento. Verificare il campo analysis_results_status ad ogni risposta. Quando cambia da 'pending' a 'ready', l'oggetto analysis_results sarà popolato.

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. Analisi Completata — Risposta Completa

Una volta che analysis_results_status è 'ready', l'oggetto analysis_results contiene l'analisi approfondita IA completa con livello di accordo, confidenza, indicatori chiave, ragionamento dettagliato, modelli linguistici e raccomandazioni.

{
    "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 l'Analisi Non è Disponibile

Se analysis_results_status è 'skipped', null o assente, non verrà prodotta alcuna analisi approfondita per questo testo. Questo accade quando 'generate_analysis_details' non è stato impostato su 'true' nella richiesta /detect, o per determinati scenari di elaborazione. Si dovrebbero trattare i risultati iniziali del rilevamento come definitivi.

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

Campi dei Risultati dell'Analisi

  • analysis_results_status: 'pending' = ancora in elaborazione, 'ready' = risultati disponibili, 'skipped' / null / assente = non disponibile per questo testo
  • analysis_results.agreement: Quanto fortemente l'analisi approfondita concorda con il rilevamento iniziale (strong / moderate / weak / disagreement)
  • analysis_results.confidence: Punteggio di confidenza dell'analisi approfondita (0-100)
  • analysis_results.keyIndicators: Array di indicatori testuali specifici trovati nel testo
  • analysis_results.detailedReasoning: Spiegazione di 2-4 frasi sul perché il testo è stato classificato in questo modo
  • analysis_results.linguisticPatterns: Array di modelli linguistici osservati (es., coerenza nella struttura delle frasi, modelli di vocabolario)
  • analysis_results.recommendations: Array di raccomandazioni attuabili per comprendere l'autenticità del testo

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.