> ## Documentation Index > Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Verifica un'immagine o un video > Carica un file e ottieni un risultato per ogni tecnica, con il verdetto C2PA come risposta autorevole. ``` 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`. ```bash curl theme={null} curl -X POST https://detect.samsa.ai/v1/public/detect \ -F "file=@photo.jpg" ``` ```python Python theme={null} 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"]) ``` ```typescript TypeScript theme={null} 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: ```json Response theme={null} { "request_id": "c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "detected": "samsa", "techniques": [ { "type": "metadata", "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", "result": "not_checked", "confidence": null, "vendor_id": null }, { "type": "watermark", "result": "not_checked", "confidence": null, "vendor_id": null } ], "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](/it/content-verification/results). | | `detected` | enum | Il verdetto complessivo: `samsa`, `non_samsa` o `unknown`. | | `techniques[]` | array | Una voce per ogni tecnica applicata — vedi [sotto](#leggere-il-dettaglio-per-tecnica). | | `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](/it/content-verification/results) 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 il rilevamento ospitato delle filigrane [non è ancora disponibile](#leggere-il-dettaglio-per-tecnica). ## 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` ```json theme={null} { "type": "metadata", "result": "absent", "confidence": "low", "manifest": null } ``` | Campo | Descrizione | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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. L'attribuzione di un manifest a Samsa sarà disponibile una volta attivata la firma di produzione. ### Le tecniche di filigrana ```json theme={null} { "type": "watermark", "result": "not_checked", "confidence": null, "vendor_id": null } ``` | Campo | Descrizione | | ------------ | ---------------------------------------------------------------------------------------------------------- | | `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; `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**. | `not_checked` **non** afferma che non sia presente alcuna filigrana — questo è ciò che significa `absent`. Il rilevamento ospitato delle filigrane non è ancora disponibile; è previsto prima del 2 febbraio 2027. Fino ad allora l'API riporta queste tecniche come `not_checked`, mai come un falso « nessuna filigrana ». Non presentare mai una tecnica `not_checked` come filigrana assente. Poiché il rilevamento ospitato delle filigrane non è ancora attivo, ogni voce di filigrana torna attualmente come `not_checked` con `confidence: null`. Le voci di filigrana non portano un nome di tecnica proprio — 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](https://detect.samsa.ai/how-detection-works) oppure [`GET /v1/public/detect/info`](/it/content-verification/info). ## Errori Gli errori restituiscono `{"detail": "…"}` — non l' [envelope degli errori](/it/guides/errors) 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`.