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álni API klienti

K dispozícii sú oficiálni klienti pre Python (pip install gaston, Python 3.10+) a PHP (composer require streams-sro/gaston, PHP 7.0+). V oboch môžete token zadať priamo alebo načítať z premennej prostredia GASTON_API_TOKEN. Ukážky kódu pri jednotlivých endpointoch nižšie používajú týchto klientov - medzi jazykmi prepínate záložkami nad každou ukážkou.

pip install gaston

composer require streams-sro/gaston

from gaston import GastonClient

# Token zadaný 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)

use StreamsSro\Gaston\GastonClient;

// Token zadaný priamo, alebo načítaný z GASTON_API_TOKEN ak je vynechaný
$client = new GastonClient('gapi-...');

// Kto som + zostávajúca kvóta
$me = $client->me();
echo $me->email, ' files left: ', $me->usage->filesLeft, PHP_EOL;

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)

$me = $client->me();
echo $me->email, ' files left: ', $me->usage->filesLeft, PHP_EOL;

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)

$media = $client->getMedia('me...', 'en');
echo $media->title, ' ', $media->state, PHP_EOL;
foreach ($media->sentences as $sentence) {
    echo $sentence->id, ' ', $sentence->getText(), ' ', $sentence->speaker, PHP_EOL;
}

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)

$client->moveMedia('me...', $folder->id);

// Presun späť do koreňového priečinka
$client->moveMedia('me...', null);

Nahrá mediálny súbor na prepis. Maximálna veľkosť súboru je 10 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))

$result = $client->transcribe('interview.mp4', 'en', null, 'My interview');
echo $result->id, ' ', $result->state, PHP_EOL;

// Veľké súbory môžu trvať minúty - upravte časový limit nahrávania pre dané volanie (0 = bez limitu)
$client->transcribe('huge-recording.mp4', null, null, null, 0.0);

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)

$result = $client->transcribeUrl('https://youtu.be/dQw4w9WgXcQ', 'en');
echo $result->id, ' ', $result->state, PHP_EOL;

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")

$client->translate('me...', 'de');

Spustí alebo reštartuje diarizáciu rečníkov pre mediálny súbor. Každá jazyková verzia má vlastnú segmentáciu rečníkov. 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)

// Vyžaduje dokončený preklad v danom jazyku
$client->diarize('me...', 'de', 2);

Spustí zarovnanie prekladu na úrovni slov voči časovým značkám zdrojového jazyka, vďaka čomu preložený text získa časovanie start/end pre jednotlivé slová (prehrávanie v štýle karaoke). Cieľový jazyk musí byť už kompletne preložený, inak požiadavka vráti chybu 400. Zarovnávanie beží asynchrónne; priebeh je dostupný v poli translation_alignment na mediálnom objekte vrátenom endpointom /media.

Parametre

# Vyžaduje, aby bol target_lang už kompletne preložený
client.align_translation("me...", target_lang="de")

// Vyžaduje, aby bol target_lang už kompletne preložený
$client->alignTranslation('me...', 'de');

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

tree = client.directory_tree()

$tree = $client->directoryTree();

Vytvorí nový priečinok.

Parametre

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

$folder = $client->createDirectory('Podcasts');
echo $folder->id, ' ', $folder->title, PHP_EOL;

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

Parametre

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

$client->updateDirectory($folder->id, 'Podcast archive');

Odstráni priečinok.

Parametre

client.delete_directory(folder.id)

$client->deleteDirectory($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")

# Vyhľadávanie len v rámci jedného prepisu
page3 = client.search("budget", media_id="123")

$results = $client->search('(invoice OR receipt) AND "due date" NOT draft', 0, 20);
echo 'total matches: ', $results->total, PHP_EOL;
foreach ($results as $hit) {
    $sentence = $hit['_sentence'];
    echo $sentence['media']['title'], ' | ', implode(' ', $hit['_highlight']['body']), PHP_EOL;
}

// Filtrovanie podľa priečinka a jazyka, so stránkovaním výsledkov
$page2 = $client->search('budget', 50, 50, [42, 43], 'en');

// Vyhľadávanie len v rámci jedného prepisu
$page3 = $client->search('budget', 0, 50, null, null, '123');

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.