The watermark
An optional upgrade to a verification, off by default. Ask for it and you get evidence; do not ask and you get exactly the bytes you got before this existed.
The four modes
| off | Default. The detector does not run and the response carries no watermark block. |
| sync | Runs inside the request. A still frame is tens of milliseconds of model. |
| async | Queued; the response carries watermark_job.id. Poll it, or subscribe to the webhook. |
| auto | sync for a still, async for a clip, decided from the proof's own media type. |
The provisional verdict, and why polling matters
A queued job cannot fold its result into the verdict of the request that started it โ the detector has not run yet. So an async response carries a verdict labelled watermark not evaluated, and says in watermark_job.note that this reading is provisional.
When you poll and state is done, you get both the raw detector evidence and a verdict recomputed with that evidence already folded in. This matters: if the pixels carry a different id than the signed core declares (a photo's capture id, a clip's mark id), the recomputed verdict's outcome is tampered. A client that displayed the first, provisional verdict and treated the later evidence as decoration would show a positive verdict for a contradicted file. Display the polled verdict, not the first one.
What the evidence is worth
Nothing signs a detection. The watermark block is this platform's own detector's reading, and the response says so in watermark_note every single time it carries one. You cannot hand it to a third party as proof, and neither can we. If you need something transportable, the signature over the file is the transportable part.
There is no signed or transportable watermark result to ask for, and there is not going to be one while the format is what it is: nothing binds a detection to the signed core. A signature of ours over our own detector's output would prove only that we ran it, which is what the response already tells you in words.
A watermark alone is never a green verdict either. Without a valid signature it means origin traced, not authentic โ the mark says where pixels came from, not that the file is unaltered.
No detector is an answer, not an error
A missing model, a digest that does not match, no demuxer: none of these produce an error. The outcome is not_evaluated with the reason in detail, and the verdict reads watermark not evaluated โ the same thing it reads when nobody asked. An outage of ours must not look like evidence against your file.