Documentazione API
ISO 27001SOC 2 CertifiedGDPR Compliant

API Rilevamento Video AI

Documentazione completa per integrare l'API di rilevamento video AI di TruthScan nelle tue applicazioni.

Prova senza codice visitando il nostro endpoint FastAPI: https://detect-video.truthscan.com/docs

Autenticazione

TruthScan utilizza 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 YOUR API KEY GOES HERE con la tua chiave API personale.

Rilevatore Video AI

Rileva (Processo in 2 Passaggi)

Il flusso di lavoro di rilevamento video AI consiste nei seguenti passaggi:

  • Invia il Video per il Rilevamento (caricamento multipart)
  • Interroga il Job per Recuperare i Risultati

1. Invia il Video per il Rilevamento

Carica un file video direttamente all'API. Il server convaliderà il file.

Formati File Supportati

MP4, MOV, AVI, MKV, WEBM

Limiti Dimensione File

  • Dimensione file minima: 1KB
  • Dimensione file massima: 100MB
POST https://detect-video.truthscan.com/detect-file

Richiesta di Esempio

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

Parametri Opzionali

  • document_type: Tipo di documento (default: 'Video')
  • email: Indirizzo email opzionale per l'elaborazione

Risposta di Esempio

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

La risposta include un ID video univoco per tracciare lo stato del rilevamento.

2. Interroga Stato e Risultati del Rilevamento

Dopo l'invio, interroga l'endpoint /query con l'ID del job per recuperare stato e risultati.

POST https://detect-video.truthscan.com/query

Richiesta di Esempio

curl -X POST 'https://detect-video.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"id":"JOB-ID-GOES-HERE"}'

Risposta di Esempio

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

Dettagli Risultato

  • status: "pending", "analyzing", "done" o "failed"
  • result: Punteggio scalare in [0.0, 1.0] derivato da ML prob_fake
  • final_stage: Ultima fase che ha contribuito al risultato: 'metadata', 'watermark' o 'ml'
  • metadata: Imposta sempre prediction: 'no_detection' e confidence: 0.0. Lo stato può essere 'reject', 'reencode' o 'ok'
  • watermark: Euristica che campiona i frame e calcola la pseudo-confidenza dalla varianza dei pixel
  • ml: Modello classificatore eseguito su frame campionati. Restituisce prob_fake in [0.0, 1.0] e label ('ai_generated' se prob_fake ≥ 0.5, altrimenti 'no_detection')
  • latency_sec: Tempo totale della pipeline

Il campo "status" sarà uno di: "pending" (elaborazione in coda), "analyzing" (rilevamento AI in corso), "done" (risultati disponibili) o "failed" (elaborazione non riuscita).

Verifica Crediti Utente

Questo endpoint accetta l'apikey degli utenti tramite l'header. E restituisce i dettagli dei crediti degli utenti.

GET https://detect-video.truthscan.com/check-user-credits

Richiesta di Esempio

curl -X 'GET' \
  'https://detect-video.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
}

Verifica Integrità

Verifica lo stato di integrità del server API.

GET https://detect-video.truthscan.com/health

Richiesta di Esempio

curl -X 'GET' \
  'https://detect-video.truthscan.com/health' \
  -H 'accept: application/json'

Risposta di Esempio

{
    "status": "healthy"
}

Errori

La maggior parte degli errori sarà dovuta a parametri errati inviati all'API. Controlla attentamente i parametri di ogni chiamata API per assicurarti che sia formattata correttamente e prova a eseguire il codice di esempio fornito.

I codici di errore generici che utilizziamo 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 per l'elaborazione video.
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 corpo della tua 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 video

Soluzione:

  1. Controlla i tuoi crediti rimanenti usando /check-user-credits
  2. Acquista crediti aggiuntivi se necessario

Problemi di Validazione Input

"Unsupported video type" (400)

Causa: Formato file non supportato

Soluzione:

  1. Converti il video in un formato supportato (MP4, MOV, AVI, MKV, WEBM)
  2. Assicurati che l'estensione del file e il tipo MIME siano corretti

"File size exceeds limit" (400)

Causa: Il file video è troppo grande

Soluzione:

  1. Comprimi, taglia o ricodifica il video per ridurre le dimensioni (massimo 100MB)
  2. Usa un codec/container più efficiente

"File size is too small" (400)

Causa: Il file video è inferiore al requisito di dimensione minima

Soluzione:

  1. Usa un file video più grande (minimo 1KB)
  2. Controlla se il file è stato corrotto durante il caricamento

"Invalid file type" (400)

Causa: Validazione del tipo di file non riuscita (es. tipo MIME errato o file corrotto)

Soluzione:

  1. Assicurati che il file sia un formato video valido
  2. Verifica che il tipo MIME corrisponda all'estensione del file
  3. Riesporta o ricodifica il file se necessario

Problemi di Elaborazione

Stato video "failed"

Causa: Elaborazione non riuscita (es. container illeggibile, errori di decodifica)

Soluzione:

  1. Assicurati che il container/codec sia comunemente supportato (H.264/AAC in MP4 raccomandato)
  2. Ricodifica il video usando un preset standard (es. ffmpeg) e ricaricalo
  3. Assicurati che il file soddisfi i requisiti di dimensione e formato

Stato video "timeout" o elaborazione lunga

Causa: L'elaborazione del video sta richiedendo più tempo del previsto o è scaduta

Soluzione:

  1. Attendi un po' più a lungo e controlla di nuovo lo stato usando /query
  2. Assicurati che il file video soddisfi tutti i requisiti di formato e dimensione
  3. Contatta il supporto se il problema persiste

"User not found"

Causa: ID utente non valido

Soluzione:

  1. Verifica che la tua chiave API sia corretta e associata a un account attivo
  2. Assicurati che l'utente di integrazione sia valido e attivo
  3. Riautenticati se necessario

"File metadata could not be fetched" (500)

Causa: Impossibile accedere o analizzare il file caricato

Soluzione:

  1. Verifica che il caricamento sia stato completato correttamente
  2. Controlla che il file sia accessibile e non corrotto
  3. Prova a ricaricare il file

Hai Bisogno di Aiuto?

Per maggiori informazioni sull'uso della nostra API o per supporto tecnico, contattaci.

Contattaci

Domande Frequenti sull'API

Trova risposte alle domande più comuni sulla nostra API di rilevamento video AI.