Vai al contenuto
Kennmarq.com, pagina iniziale
Menu

SDK Python

Marca immagini, brani e clip IA da Python con una sola riga: nel cloud, oppure le immagini sulla tua macchina, da cui non escono mai. Il controllo di sicurezza e la verifica sono inclusi. Licenza MIT; il client cloud non ha dipendenze.

Installazione

Shell
pip install kennmarq                 # the cloud API: no dependencies
pip install "kennmarq[local]"        # local mode
pip install "kennmarq[safety]"       # the safety check on your machine too

L’SDK legge la tua chiave da KENNMARQ_API_KEY, oppure la riceve con api_key=. Python 3.10 o successivo.

Nel cloud

Python
from kennmarq import Kennmarq

k = Kennmarq()
result = k.mark("render.png", "render.marked.png", source="created", model="FLUX.1 schnell")
print(result.mark_id, result.watermark_id, result.marks_used)

L’immagine va a POST /v1/mark: i nostri server a Zurigo la marcano in memoria e non conservano nulla. Un file oltre 4 MB, fino a 25 MB, viene prima caricato da sé tramite POST /v1/uploads; check() e verify() fanno lo stesso (un upload richiede una chiave).

Brani e clip

Python
song = k.mark("track.mp3", "track.marked.mp3", model="Song Model 2")
print(song.marks_counted, song.audio_watermark)        # 15 (five per started minute), "claimed"

clip = k.mark("clip.mp4", "clip.marked.mp4", check="ai-act")   # waits for the job, then downloads
print(clip.watermark_id, clip.marks_counted)

job = k.mark("long.mp4", wait=False)                    # or start it now…
clip = k.wait_for(job.mark_id, "long.marked.mp4")        # …and fetch it later

Nel cloud, mark() accetta anche brani MP3, WAV e M4A e clip MP4: una clip è un job, che mark() attende (fino a 40 minuti) prima di scaricare la clip marcata; una clip fino a 1 GB viene prima caricata da sé. Un fotogramma bloccato solleva ContentBlocked, con il fotogramma in safety. Per ora la modalità locale marca solo immagini.

mark(..., label=True) disegna l’etichetta visibile dell’UE («AI GENERATED») in un’immagine o in ogni fotogramma di una clip; deepfake=True la attiva, e label_language, label_position, label_size e label_style ne definiscono l’aspetto. Le etichette vengono disegnate nel cloud: mark_file() non le disegna ancora.

Sulla tua macchina

Python
result = k.mark_file("render.png", "render.marked.png", source="created", model="FLUX.1 schnell")
assert result.mode == "local"
  • La filigrana e le Content Credentials vengono create sulla tua macchina. Solo il manifest va a POST /v1/sign, circa 13 KB e mai pixel, per essere firmato e ricevere la marca temporale. Ogni file conta una marcatura.
  • Prima di scrivere qualsiasi cosa, l’SDK legge il file con i nostri certificati radice: deve risultare Trusted, con una marca temporale convalidata e la sua filigrana al suo posto. Altrimenti solleva InvalidSignedFile e non scrive nulla.
  • Le credenziali che il file contiene già vengono conservate come ingrediente, come chiede il codice di buone pratiche, e viaggiano con il manifest; keep_input_credentials=False non ne conserva nessuna.
  • Il modello della filigrana (65 MB) viene scaricato una sola volta, in ~/.cache/kennmarq/models o in KENNMARQ_MODELS_DIR, e verificato rispetto al suo SHA-256 fissato.
  • Dove la libreria C2PA non ha una build (per ora Windows), la filigrana viene creata sulla tua macchina e il manifest nel cloud: l’immagine con la filigrana viene inviata a POST /v1/mark (mode == "hybrid").
  • Senza una chiave, watermark_file() scrive solo la filigrana e l’etichetta IA IPTC, senza Content Credentials.

Il controllo di sicurezza

Python
answer = k.check("render.png", policy="ai-act")              # in the cloud: two marks
answer = k.check("render.png", policy="ai-act", local=True)  # on your machine: nothing sent, nothing counted
result = k.mark_file("render.png", "out.png", check="ai-act")  # a block raises ContentBlocked

Lo stesso controllo di POST /v1/check, con gli stessi modelli e gli stessi tassi di errore. Sulla tua macchina i suoi modelli vengono scaricati una sola volta, circa 2,3 GB.

Verifica un file

Python
Kennmarq().verify("render.marked.png")   # free, no key needed

Errori

Gli errori dell’API sollevano KennmarqError, con code, status e request_id dell’API (errori). ContentBlocked porta la risposta del controllo in safety; MissingApiKey, LocalModeUnavailable e InvalidSignedFile indicano cosa manca.