API přístup

Inkscriptio nabízí jednoduché HTTP API, přes které mohou nahrávat zvuk a stahovat hotové přepisy externí zařízení a aplikace — například hardwarový diktafon nebo interní firemní nástroj. Přístup k API se ověřuje pomocí API klíčů.

API klíče

API klíč je dlouhý tajný řetězec začínající ink_, který zastupuje váš uživatelský účet při komunikaci přes API. Vše, co zařízení s klíčem nahraje, se objeví ve vašem účtu jako běžná nahrávka a přepis.

Vytvoření klíče

Otevřete Nastavení (ikona ozubeného kola) a sjeďte na sekci API klíče.
Zadejte název klíče (např. „AI Noter" nebo „interní aplikace") a klikněte na Vytvořit klíč.
Zobrazí se celý klíč se žlutým upozorněním — zkopírujte si ho hned. Z bezpečnostních důvodů se klíč zobrazuje pouze jednou; v aplikaci se ukládá jen jeho otisk (hash) a prvních 12 znaků pro identifikaci.

Klíč se zobrazí jen jednou

Pokud klíč ztratíte, nelze ho znovu zobrazit. Jednoduše ho revokujte a vytvořte nový.

Správa klíčů

V tabulce v Nastavení vidíte u každého klíče název, prefix, datum vytvoření a kdy byl naposledy použit — snadno tak poznáte, které klíče jsou aktivní a které můžete bezpečně zrušit.

Revokovat — okamžitě zneplatní klíč. Zařízení, která ho používají, přestanou mít přístup. Revokace je nevratná (vytvořte si nový klíč).
Počet klíčů není omezen — pro každé zařízení či aplikaci je vhodné mít samostatný klíč, aby šly rušit nezávisle.

Endpointy

Všechny požadavky vyžadují hlavičku Authorization: Bearer <váš klíč>. Odpovědi jsou vždy JSON (i chyby, ve tvaru {"error": "..."}), v angličtině. Cesty se zadávají bez lomítka na konci.

Kontrola spojení

GET /api/device/ping

Vrátí 200 {"status": "ok"}, pokud je klíč platný. Cokoliv jiného znamená neplatný klíč nebo problém se spojením.

Nahrání nahrávky

POST /api/device/recordings
Content-Type: multipart/form-data

část	typ	obsah
`meta`	`application/json`	metadata (viz níže), všechna pole volitelná
`audio`	`audio/wav`	zvukový soubor

{
  "device_id": "noter-01",
  "recording_id": "rec_0042",
  "title": "volitelný název",
  "language": "cs",
  "tags": ["schůzka", "projekt-x"]
}

language — cs nebo en; bez uvedení se použije čeština.
tags — volitelné štítky přepisu (pole řetězců nebo text s čárkami, max 10); chovají se stejně jako štítky z webu a lze podle nich rovnou filtrovat.
Auto-tag: každá nahrávka přes API navíc automaticky dostane štítek podle názvu použitého API klíče (klíč „AI Noter" → štítek ai noter). Když má každé zařízení vlastní klíč, máte tak filtrování podle zařízení zdarma — bez jakéhokoli nastavování na zařízení.
device_id + recording_id — pokud jsou obě pole vyplněná, funguje ochrana proti duplicitám: opakované odeslání stejné nahrávky (např. po výpadku spojení) nevytvoří druhý přepis, ale vrátí job_id toho původního.
Nevalidní či chybějící metadata nahrávku neshodí — použijí se výchozí hodnoty.

Odpověď: 201 {"job_id": "<id>", "status": "queued"}. Přepis proběhne výchozím modelem a strategií podle vašich preferencí v Nastavení (Secure mode se respektuje — vynucuje lokální zpracování).

Stav přepisu

GET /api/device/recordings/{job_id}

Odpověď obsahuje pole status s jednou z hodnot:

status	význam
`queued`	čeká ve frontě
`processing`	přepisuje se
`done`	hotovo — odpověď obsahuje `transcript` s celým textem (a `summary`, pokud shrnutí existuje)
`error`	selhalo — odpověď obsahuje `error` s důvodem

Rychlá poznámka (ephemeral)

POST /api/device/notes
Content-Type: multipart/form-data

Stejný formát požadavku jako /api/device/recordings (části meta + audio), navíc s jedním polem v meta:

{
  "device_id": "noter-01",
  "recording_id": "note_0007",
  "save": false
}

save — true/false, výchozí false.

Výchozí chování (save chybí nebo false) — poznámka je ephemerní:

Poznámka se nezobrazuje na /transcriptions/ ani /files/ — v aplikaci je zcela neviditelná, i pro majitele klíče.
Nedostává žádné štítky (ani meta tags, ani automatický štítek podle názvu API klíče).
Jakmile je přepis hotový (nebo selže), zvukový soubor se okamžitě smaže — zůstává jen text přepisu.
Samotný text přepisu je dostupný přes GET /api/device/notes/{job_id} po dobu note_retention_hours (výchozí 24 hodin, nastavitelné administrátorem v SiteSettings). Po uplynutí této doby je celý záznam trvale odstraněn a job_id už nic nevrátí (404).

meta.save: true — poznámka se stane běžnou nahrávkou:

Chová se identicky jako /api/device/recordings — trvalý přepis, viditelný v /transcriptions/, se štítky (meta tags + automatický štítek podle klíče), bez automatického mazání.

Ochrana proti duplicitám je oddělená od /recordings: stejná dvojice device_id + recording_id odeslaná na /notes a na /recordings vytvoří dva nezávislé přepisy — obor idempotence je pro každý endpoint samostatný.

Odpověď: 201 {"job_id": "<id>", "status": "queued"} — stejně jako u /recordings.

Stav poznámky

GET /api/device/notes/{job_id}

Naprosto stejný kontrakt jako GET /api/device/recordings/{job_id} (queued / processing / done s transcript / error). U ephemerních poznámek přestane endpoint po uplynutí note_retention_hours vracet 200 — záznam už neexistuje.

Limity

co	limit
Velikost souboru	200 MB (≈ 1,5 h WAV 16 kHz mono)
Nahrávání	20 souborů za hodinu
Dotazy na stav	120 za minutu
Kontrola spojení	30 za minutu

Při překročení limitu vrací API 429 {"error": "rate limited"} — počkejte a zkuste to znovu.

Bezpečnost

Klíče se v databázi ukládají pouze jako otisk (SHA-256) — únik databáze neznamená únik klíčů.
Nahrávky přes API podléhají stejným pravidlům jako běžné nahrávky: Secure mode, retence, audit.
Vytvoření, revokace i každé nahrání přes API se zaznamenává do auditního logu.