Lo stato di una marcatura

GET https://api.kennmarq.com/v1/marks/{id}

Una clip viene marcata come job (POST /v1/mark risponde 202 con il suo ID): interroga questo endpoint finché non è pronta, poi scarica la clip marcata. Le richieste di stato non contano marcature. Serve una chiave con l’ambito mark, dell’organizzazione e dell’ambiente della marcatura.

Esempio

curl https://api.kennmarq.com/v1/marks/mk_… -H "Authorization: Bearer $KENNMARQ_API_KEY"

{
  "object": "mark", "id": "mk_…", "status": "completed", "kind": "clip",
  "created_at": "2026-11-12T10:00:00.000Z", "finished_at": "2026-11-12T10:01:12.000Z",
  "file": { "type": "video/mp4", "bytes": 18734211, "sha256": "…", "seconds": 9.6, "width": 1920, "height": 1080, "frames": 230 },
  "watermark_id": "1d455a804e9802a6",
  "watermarks": { "video": { "alg": "Meta Video Seal 1.0", "id": "1d455a804e9802a6", "read_back": 1, "frames": 64, "strength": 0.2 },
                  "audio": { "alg": "Meta AudioSeal (16 bits)", "claimed": true, "detected": 0.71, "bits": 16 } },
  "manifest": "urn:c2pa:…", "log_index": 1234, "marks": 10, "safety": null,
  "download": { "url": "https://…", "expires_at": "2026-11-12T10:06:12.000Z" },
  "download_until": "2026-11-13T10:01:12.000Z", "download_links_left": 4, "download_error": null
}

Mentre il job è in corso, la risposta è {"object": "mark", "id": "mk_…", "status": "running", …}. La maggior parte delle clip richiede un minuto o due; interroga l’endpoint ogni pochi secondi, oppure fatti avvisare da un webhook. Il link di download non richiede alcuna chiave: è esso stesso l’autorizzazione, quindi condividilo con cautela. Un’immagine o un brano è stato marcato nella sua stessa chiamata: qui risulta completed, senza download.

Download

Il file di una clip completata viene conservato per un giorno. Ogni link al file funziona per 5 minuti: avvia il download entro quel tempo (un download già avviato arriva a termine). Una nuova richiesta entro quei 5 minuti restituisce lo stesso link, con il tempo che gli resta; dopo, un nuovo link, fino a 5 per clip. La dimensione del file conta sui dati del tuo mese una volta alla fine del job, il che copre il primo link, e di nuovo per ogni link successivo. Esauriti i dati del mese, non viene creato alcun nuovo link fino al primo del mese (UTC) o al passaggio a un piano superiore.

Campi

Ricevute

GET https://api.kennmarq.com/v1/marks/{id}/receipt

Una marcatura fatta con markets ha una ricevuta: per ogni mercato, la legge, ciò che il file contiene per quella legge, ciò che eventualmente manca e ciò che resta a te in quanto fornitore. La firmiamo con la chiave del nostro verificatore quando la richiedi, così puoi conservarla come prova; GET /v1/verify/key fornisce la stessa chiave. Le marcature fatte senza markets, o in modalità locale, non ne hanno (404 not_found).

curl https://api.kennmarq.com/v1/marks/mk_4Q8oT1n6mWc2fLr0aZ9eYb/receipt \
  -H "Authorization: Bearer $KENNMARQ_API_KEY"

{
  "receipt": {
    "object": "receipt",
    "mark_id": "mk_4Q8oT1n6mWc2fLr0aZ9eYb",
    "made_at": "2026-10-24T10:00:00Z",
    "file": { "type": "image/png", "sha256": "…" },
    "marks": {
      "credential": { "manifest": "urn:c2pa:…", "time_stamp": { "serial": "…", "time": "2026-10-24T10:00:00Z" } },
      "watermark": { "alg": "com.adobe.trustmark.Q", "id": "1a2b3c4d5e6f7081" },
      "sound_watermark": null
    },
    "origin": { "provider": "Acme Inc.", "system": "Acme Studio", "system_version": "2.1", "source": "created", … },
    "markets": [
      { "market": "us-ca", "law": "California AI Transparency Act …", "applied": ["a latent disclosure: …", …], "missing": [], "yours": ["being the covered provider", …] }
    ],
    "rules_checked": "2026-10-24",
    "guarantee": "…"
  },
  "jws": "eyJhbGciOiJFUzI1NiIs…",
  "key_id": "…",
  "public_key": "-----BEGIN PUBLIC KEY-----…"
}

Quando un job non riesce

status: failed, con l’errore con cui avrebbe risposto una chiamata: content_blocked (un fotogramma bloccato dal controllo di sicurezza, in safety, con il suo frame), quota_exceeded (la clip richiede più marcature di quelle rimaste), payload_too_large (oltre i nostri limiti), invalid_request (un file che non riusciamo a leggere), mark_failed o marker_unavailable. Un job non riuscito non conta nulla, tranne i controlli di un blocco, se li avevi richiesti. Dopo un errore da parte nostra, l’upload torna utilizzabile fino allo scadere della sua ora. Le clip che non riescono con mark_failed dopo che le abbiamo elaborate hanno un limite giornaliero (clip).