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

Výstupní formát (`format`)

Volitelný parametr format v query stringu určuje, v jaké podobě se hotový přepis vrátí. Uplatní se jen při status: done; u ostatních stavů se odpověď nemění. Bez parametru je odpověď stejná jako dosud (prostý text).

GET /api/device/recordings/{job_id}?format=segments

`format`	obsah odpovědi při `status: done`
(chybí) / `text`	beze změny — `transcript` jako prostý text
`segments`	`transcript` (prostý text) + `language`, `duration_s`, `diarization` a pole `segments` s časy a řečníky
`txt`	`transcript` jako řetězec bajtově shodný s TXT exportem z webového rozhraní
`srt`	`transcript` jako titulky SRT; řečník jako prefix `SPEAKER_00: text`
`vtt`	`transcript` jako titulky WebVTT; řečník jako `<v SPEAKER_00>`

Pole summary (pokud shrnutí existuje) je v odpovědi u všech formátů.

format=segments:

{
  "status": "done",
  "transcript": "Konec. Dobrý den, slyšíme se?",
  "language": "cs",
  "duration_s": 2903.0,
  "diarization": true,
  "segments": [
    {"start": 22.0, "end": 24.1, "speaker": "SPEAKER_00", "text": "Konec."},
    {"start": 52.0, "end": 55.3, "speaker": null, "text": "Dobrý den, slyšíme se?"}
  ]
}

start / end — sekundy (float) od začátku nahrávky. end může být null, pokud ho model nevrací.
speaker — stejný identifikátor jako v TXT exportu (SPEAKER_00, SPEAKER_01…, případně jméno, pokud jste řečníka ve webu přejmenovali). null, pokud řečník u segmentu rozpoznán nebyl — hodnota se neodvozuje z předchozího segmentu.
Segmenty jsou v chronologickém pořadí; stejný start u více segmentů je možný.
diarization — true, pokud má alespoň jeden segment řečníka. Záznam, který má jen prostý text (např. starší přepisy), vrátí segments: [] a diarization: false — nikoli chybu.
duration_s — délka nahrávky v sekundách, nebo null, pokud není známa.

format=txt vrací přesně to, co stáhnete tlačítkem Export → TXT na detailu přepisu: hlavičku (název, délka, případně seznam přejmenovaných řečníků), oddělovač a pak segmenty ve tvaru

[00:00:22] SPEAKER_00:
Konec.

[00:00:52]
Dobrý den, slyšíme se?

Každý segment začíná řádkem [HH:MM:SS] (případně s <řečník>:), následuje text a prázdný řádek. Pokud má server nastavenou veřejnou adresu, končí text patičkou Generated by Inkscriptio • <adresa>, oddělenou prázdným řádkem. Hlavičku i patičku API ponechává, aby výstup zůstal shodný s webovým exportem; při strojovém zpracování je přeskočte (berte jen řádky začínající časovou značkou a text za nimi).

Neznámá hodnota vrátí 400:

{"error": "unsupported format", "supported": ["text", "segments", "txt", "srt", "vtt"]}

Parametr format funguje stejně i pro GET /api/device/notes/{job_id}. Na limity dotazů nemá vliv.

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), včetně parametru format. 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.