Verifica un'immagine o un video

POST https://detect.samsa.ai/v1/public/detect

Carica una singola immagine o un singolo video come multipart/form-data. La risposta porta un verdetto complessivo detected più un dettaglio per ogni tecnica. Nessuna autenticazione, nessun credito. Il file caricato è elaborato in memoria e mai conservato.

Richiesta

Invia esattamente una parte file chiamata file. La parte deve portare un filename nel suo header Content-Disposition — un semplice campo di form senza nome file non è una parte file.


Content-Type	`multipart/form-data`
Campo	`file` — l’immagine o il video da verificare
Dimensione max.	50 MB
Formati immagine	JPEG, PNG, WebP, GIF
Formati video	MP4, QuickTime, WebM

JPEG/PNG/WebP/GIF e MP4/QuickTime sono riconosciuti dai magic byte, quindi un Content-Type della parte sbagliato o generico (per esempio application/octet-stream) non impedisce il rilevamento per questi formati. WebM non ha un ramo magic-byte ed è accettato solo se la parte dichiara Content-Type: video/webm.

curl -X POST https://detect.samsa.ai/v1/public/detect \
  -F "file=@photo.jpg"

import requests

with open("photo.jpg", "rb") as fh:
    response = requests.post(
        "https://detect.samsa.ai/v1/public/detect",
        files={"file": ("photo.jpg", fh, "image/jpeg")},
        timeout=120,
    )

response.raise_for_status()
result = response.json()
print(result["detected"])

import { readFile } from "node:fs/promises";

const form = new FormData();
// The third argument sets the part filename — required for it to count as a file part.
form.append("file", new Blob([await readFile("photo.jpg")]), "photo.jpg");

const response = await fetch("https://detect.samsa.ai/v1/public/detect", {
  method: "POST",
  body: form,
});

if (!response.ok) {
  const { detail } = await response.json();
  throw new Error(`Detection failed (${response.status}): ${detail}`);
}

const result = await response.json();
console.log(result.detected);

Risposta

200 OK. Un’immagine o un video che porta un manifest C2PA di Samsa valido e attendibile:

Response

{
  "request_id": "c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "detected": "samsa",
  "techniques": [
    {
      "type": "metadata",
      "technique_id": "c2pa",
      "result": "samsa",
      "confidence": "high",
      "manifest": {
        "claim_generator": "Samsa/1.0",
        "digital_source_type": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia",
        "upstream_provider": "fal",
        "upstream_model": "flux-pro",
        "timestamp": "2026-07-02T14:21:07+00:00",
        "assertions": ["c2pa.actions", "c2pa.hash.data"]
      }
    },
    {
      "type": "watermark",
      "technique_id": "trustmark-q",
      "result": "absent",
      "confidence": "low",
      "vendor_id": null
    },
    {
      "type": "watermark",
      "technique_id": "pixelseal",
      "result": "samsa",
      "confidence": "high",
      "vendor_id": "samsa-pixelseal-v1"
    }
  ],
  "external_verification": {
    "c2pa": "https://verify.contentauthenticity.org"
  },
  "result_pdf_url": "https://detect.samsa.ai/v1/public/detect/result/c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/pdf",
  "responded_at": "2026-07-02T14:21:09.412093Z"
}

Campo	Tipo	Descrizione
`request_id`	string (UUID)	ID generato dal server per questa verifica. Usalo per scaricare il PDF di risultato firmato.
`detected`	enum	Il verdetto complessivo: `samsa`, `non_samsa` o `unknown`.
`techniques[]`	array	Una voce per ogni tecnica applicata — vedi sotto.
`external_verification`	object	Link per verificare il risultato indipendentemente da Samsa. Attualmente `c2pa`.
`result_pdf_url`	string \| null	Link al PDF firmato di questo risultato, oppure `null` quando la persistenza dei risultati non è disponibile.
`responded_at`	string (ISO 8601)	Quando la verifica si è conclusa, in UTC.

result_pdf_url può essere null. Quando è presente, seguila esattamente come viene restituita invece di comporre l’URL da solo — essa e l’endpoint di risultato documentato servono lo stesso PDF firmato.

Il verdetto `detected`

Il verdetto deriva dalla verifica del manifest C2PA, che è autorevole. Le tecniche di filigrana sono conferma: possono fornire un’attribuzione quando non è presente alcun manifest, ma non sovrascrivono mai un verdetto basato su un manifest.

`detected`	Si raggiunge quando
`samsa`	È stato verificato un manifest Samsa valido, attendibile e in allowlist — oppure, in assenza di manifest, un rilevamento di filigrana ha restituito una corrispondenza Samsa.
`non_samsa`	Un manifest è presente ma non è attribuibile a Samsa (altro emittente, non attendibile o manomesso).
`unknown`	Nessun manifest presente e nessuna corrispondenza di filigrana.

unknown significa che questa verifica non ha trovato prove, non che il file sia autentico o creato da una persona. I metadati di provenienza si rimuovono facilmente e per i video il rilevamento ospitato delle filigrane non è ancora disponibile.

Leggere il dettaglio per tecnica

techniques[] inizia sempre con l’unica voce metadata (il livello C2PA autorevole), seguita dalle tecniche di filigrana applicabili alla modalità del file.

La tecnica `metadata`

{
  "type": "metadata",
  "technique_id": "c2pa",
  "result": "absent",
  "confidence": "low",
  "manifest": null
}

Campo	Descrizione
`technique_id`	Sempre `c2pa` per questa voce.
`result`	`samsa` (manifest Samsa valido, attendibile e in allowlist), `non_samsa` (manifest di un altro emittente, o valido ma non attendibile), `tampered` (manifest che non supera la validazione) o `absent` (nessun manifest — di solito perché è stato rimosso).
`confidence`	`high`, `medium` o `low`. Sempre presente per questa tecnica.
`manifest`	Un riepilogo comprensibile del manifest verificato (`claim_generator`, `digital_source_type`, `upstream_provider`, `upstream_model`, `timestamp`, `assertions`), oppure `null` quando non c’è nulla da riepilogare.

La verifica del manifest C2PA è attiva: è fornita dall’API pubblica di Samsa e da qualsiasi validatore C2PA indipendente.

Le tecniche di filigrana

{
  "type": "watermark",
  "technique_id": "pixelseal",
  "result": "samsa",
  "confidence": "high",
  "vendor_id": "samsa-pixelseal-v1"
}

Campo	Descrizione
`technique_id`	`trustmark-q` o `pixelseal` per un’immagine, `video-seal` per un video. Sempre presente, anche per `not_checked`.
`result`	`samsa`, `absent`, `low_confidence` o `not_checked` — vedi la tabella sotto.
`confidence`	`high`, `medium` o `low`, e `null` se e solo se `result` è `not_checked`. La chiave è sempre presente.
`vendor_id`	Indica il decoder che ha prodotto una corrispondenza (`samsa-trustmark-v1`, `samsa-pixelseal-v1`); `null` a meno che `result` non sia `samsa`.

`result`	Significato
`samsa`	Un decoder è stato eseguito e ha trovato una filigrana Samsa.
`absent`	Un decoder è stato eseguito e non ha trovato alcuna filigrana Samsa.
`low_confidence`	Un decoder è stato eseguito e ha restituito una corrispondenza debole.
`not_checked`	Il backend del decoder non è predisposto, quindi la tecnica non è mai stata valutata.

Il rilevamento ospitato è attivo per entrambe le tecniche per immagini, con una semantica di confidenza volutamente diversa:

TrustMark Q (trustmark-q) copre il corpus storico — le immagini marcate quando TrustMark era il fornitore di inserimento — e resta disponibile in modo permanente per quel corpus. La confidenza descrive la corrispondenza: high è una corrispondenza esatta del payload, medium una corrispondenza entro il raggio di correzione degli errori del codice, e un segnale residuo debole viene riportato come low_confidence — mai un falso « nessuna filigrana ».
Meta PixelSeal (pixelseal) è la filigrana per immagini attuale — le nuove immagini generate da Samsa portano PixelSeal. La presenza è decisa dall’accuratezza dei bit rispetto al payload del fornitore a una soglia fissa; sotto la soglia il risultato è absent. Questa via non ha volutamente alcuna banda low_confidence.

not_checked non afferma che non sia presente alcuna filigrana — questo è ciò che significa absent. Il rilevamento ospitato delle filigrane video non è ancora disponibile; è previsto prima del 2 febbraio 2027. Fino ad allora l’API riporta la tecnica video-seal come not_checked, mai come un falso « nessuna filigrana ». Non presentare mai una tecnica not_checked come filigrana assente.

In ogni via, un decoder che non può essere eseguito riporta not_checked, mai un absent costruito. Per gli ID degli algoritmi, gli hash degli artefatti di modello fissati, le etichette di soft-binding per via di firma e i decoder open source dietro ogni tecnica, leggi Come funziona il rilevamento oppure GET /v1/public/detect/info.

Errori

Gli errori restituiscono {"detail": "…"} — non l’ envelope degli errori dell’API REST di Samsa.

Stato	Quando
`400`	Corpo multipart malformato, boundary mancante, upload vuoto, o un numero di parti file diverso da esattamente una.
`413`	L’upload supera il limite di 50 MB.
`415`	La richiesta non è `multipart/form-data`, oppure i byte caricati non sono un’immagine o un video supportato.
`503`	Un decoder disponibile o il verificatore C2PA è fallito durante l’inferenza. La risposta porta un header `Retry-After`.

Tratta 503 come transitorio e riprova dopo l’intervallo Retry-After. Un decoder semplicemente non predisposto non produce mai un 503 — degrada a not_checked in una normale risposta 200.

​Richiesta

​Risposta

​Il verdetto detected

​Leggere il dettaglio per tecnica

​La tecnica metadata

​Le tecniche di filigrana

​Errori

Richiesta

Risposta

Il verdetto `detected`

Leggere il dettaglio per tecnica

La tecnica `metadata`

Le tecniche di filigrana

Errori