GASTON REST API

OpenAPI 3.1 špecifikácia →

GASTON poskytuje jednoduché REST API, ktoré vám umožňuje prepojiť vaše aplikácie a webové stránky s našimi službami a prepisovať video a audio súbory.

Prepis súborov je asynchrónny. Po nahraní súboru do nášho API obdržíte ID, ktoré je spracovávané sekvenčne. Zvuková stopa sa extrahuje, vygeneruje sa spektrogram, deteguje sa jazyk a vykoná sa prepis. Aktuálny stav súboru, ako aj získanie prepisu a dodatočných informácií, je dostupné prostredníctvom endpointu /media. Všetky nahrané súbory sú uložené v knižnici médií, rovnako ako keby boli pridané cez webovú aplikáciu.

Autentifikácia

API kľúč musí byť súčasťou HTTP hlavičky pri každej požiadavke. Po prihlásení do vašich nastavení si vygenerujte API kľúč, ktorý sa používa na autorizáciu požiadaviek na naše REST API.

curl -X 'GET' \
  'https://api.gaston.live/user/me' \
  -H 'accept: application/json' \
  -H 'token: gapi-1234567890'

Svoj API kľúč môžete kedykoľvek znovu vygenerovať vo vašich API nastaveniach.

Oficiálny Python klient

Na PyPI je dostupný malý, typovaný Python klient. Nainštalujte ho príkazom pip install gaston (Python 3.10+). Token môžete zadať priamo alebo načítať z .env premennej GASTON_API_TOKEN. Ukážky kódu pri jednotlivých endpointoch nižšie používajú tohto klienta.

pip install gaston

from gaston import GastonClient

# Token odovzdaný priamo, alebo načítaný z GASTON_API_TOKEN ak je vynechaný
client = GastonClient(token="gapi-...")

# Kto som + zostávajúca kvóta
me = client.me()
print(me.email, "files left:", me.usage.files_left)

Popis jednotlivých endpointov

Kompletná technická špecifikácia vo formáte OpenAPI 3.1 je dostupná tu. Nižšie je uvedený zjednodušený popis endpointov.

Získa základné informácie o autentifikovanom používateľovi vrátane detailov o využívaní služby, ako je počet zostávajúcich API súborov dostupných v rámci aktuálnej kvóty.

me = client.me()
print(me.email, "files left:", me.usage.files_left)

Vypíše spracované súbory uložené v knižnici médií. Odpoveď obsahuje iba súhrnné informácie a nezahŕňa celý text prepisu.

Parametre

Vráti kompletné informácie o súbore vrátane prepisu, časových značiek na úrovni slov a dostupných prekladov. Verziu súboru môžete filtrovať zadaním parametra lang v požiadavke. Ak je zadané lang=en a existuje anglický preklad, bude vrátený anglický prepis.

Parametre

media = client.get_media("me...", lang="en")
print(media.title, media.state)
for sentence in media.sentences:
    print(sentence.id, sentence.text, sentence.speaker)

Presunie mediálny súbor do vybraného priečinka.

Parametre

client.move_media(media_id="me...", dir_id=folder.id)

# Presun späť do koreňového priečinka
client.move_media(media_id="me...", dir_id=None)

Nahrá mediálny súbor na prepis. Maximálna veľkosť súboru je 2 GB. Môžete určiť jazyk hovorený v nahrávke. Ak nie je zadaný, jazyk bude automaticky detegovaný. Ak je známy, odporúča sa jeho zadanie pre rýchlejšie spracovanie. Môžete tiež definovať názov súboru v knižnici médií. Ak nie je zadaný, použije sa pôvodný názov súboru. Po úspešnej požiadavke endpoint odpovie detailmi o súbore vrátane jeho ID a aktuálneho stavu.

Parametre

result = client.transcribe("interview.mp4", lang="en", title="My interview")
print(result.id, result.state)

# Veľké súbory môžu trvať minúty — upravte časový limit nahrávania pre dané volanie
client.transcribe("huge-recording.mp4", timeout=(10, None))

Podobne ako predchádzajúci endpoint, táto metóda prepíše video z poskytnutej URL adresy podporovanej streamovacej služby. Po odoslaní URL adresy videa sa súbor automaticky stiahne a spracuje.

Parametre

result = client.transcribe_url("https://youtu.be/dQw4w9WgXcQ", lang="en")
print(result.id, result.state)

Preloží už prepísaný súbor do zvoleného jazyka. Momentálne je podporovaných 42 cieľových jazykov. Postup prekladu a dostupné jazykové verzie pre každý súbor sú uvedené v poli available_languages, kde kľúč predstavuje jazyk a hodnota predstavuje percento dokončenia.

Napríklad nasledujúci stav označuje, že súbor je úplne prepísaný v slovenčine (100 %), zatiaľ čo anglický preklad je stále vo fáze spracovania na 66 %:

available_languages: {
  sk: 100,
  en: 66
}

Parametre

client.translate("me...", target_lang="de")

Spustí alebo reštartuje diarizáciu hovorcov pre mediálny súbor. Každá jazyková verzia má vlastnú segmentáciu hovorcov. Napríklad môžete mať diarizovanú anglickú verziu, zatiaľ čo španielska verzia zostane bez diarizácie.

Parametre

# Vyžaduje dokončený preklad v danom jazyku
client.diarize("me...", lang="de", speakers=2)

Rekurzívne vypíše celú štruktúru stromu priečinkov.

tree = client.directory_tree()

Vytvorí nový priečinok.

Parametre

folder = client.create_directory("Podcasts")
print(folder.id, folder.title)

Premenuje priečinok alebo ho presunie do iného nadradeného priečinka.

Parametre

client.update_directory(folder.id, title="Podcast archive")

Odstráni priečinok.

Parametre

client.delete_directory(folder.id)

Vyhľadávanie viet vo vašich prepisoch.

Parametre

results = client.search('(invoice OR receipt) AND "due date" NOT draft', max_=20)
print("total matches:", results.total)
for hit in results:
    sentence = hit["_sentence"]
    print(sentence["media"]["title"], "|", hit["_highlight"]["body"])

# Filtrovanie podľa priečinka a jazyka, so stránkovaním výsledkov
page2 = client.search("budget", from_=50, max_=50, dir_ids=[42, 43], lang="en")

Cenník

Samotná platforma Gaston nemá žiadne obmedzenia na prepis súborov. Môžete prepisovať, koľko potrebujete. Programový prístup cez API je však iný prípad: každá API požiadavka spúšťa prepis, preklad a vyhľadávanie na našej infraštruktúre, takže aby bola služba udržateľná, nemôže byť logicky neobmedzená za jednu paušálnu cenu.

Z tohto dôvodu sa používanie API účtuje za spracovaný súbor. Cena je 25 € za každých 100 súborov.

Za týmto spoplatnením je iba samotný prepis. Vo chvíli, keď je súbor v systéme, môžete s ním robiť, čo chcete. Môžete ho preložiť do ktoréhokoľvek podporovaného jazyka, spustiť diarizáciu, vyhľadávať, exportovať a organizovať do priečinkov bez akýchkoľvek ďalších poplatkov. Zaplatíte raz za prepis súboru a všetko, čo s ním robíte potom, je zadarmo.

Táto paušálna cena za súbor predpokladá súbory primeranej dĺžky. Kvôli udržateľnosti služby si vyhradzujeme právo upraviť cenu pri extrémnom alebo automatizovanom hromadnom používaní. Pred akoukoľvek zmenou, ktorá by sa vás týkala, vás vždy budeme kontaktovať.

Spracovanie a priepustnosť

Prepis beží na zdieľanom GPU klasteri so vstavanou ochranou proti zahlteniu. Ak naraz odošlete veľkú dávku súborov, nezablokuje to ostatných zákazníkov. Vaše súbory sa spracúvajú priebežne na pozadí, takže veľká dávka môže jednoducho trvať o niečo dlhšie.

Partnerské ceny

Ak váš projekt nejakým spôsobom propaguje naše služby, môžete mať nárok na partnerské ceny, ktoré sú ešte výhodnejšie než sadzby uvedené vyššie. Partnerom myslíme zákaznícky projekt, ktorý pomáha zviditeľniť Gaston, napríklad tým, že ho spomína alebo odporúča svojmu publiku. Partnerské ceny sú vždy individuálna dohoda a závisia od toho, nakoľko je váš projekt pre nás relevantný. Ak si myslíte, že by ste mohli do tohto popisu zapadnúť, ozvite sa na contact@streams.guru a detaily doladíme spoločne.