GASTON REST API

OpenAPI 3.1 specification →

GASTON provides a simple REST API that allows you to connect your applications and websites to our services and transcribe video and audio files.

File transcription is asynchronous. After uploading a file to our API, you will receive a ID that is processed sequentially. The audio track is extracted, a spectrogram is generated, the language is detected, and the transcription is performed. The current file status, as well as retrieval of the transcript and additional information, is available via the endpoint /media. All uploaded files are stored in the media library, just as if they were added through the web application.

Authentication

The API key must be included in the HTTP header with every request. After logging in to your settings, generate an API key that is used to authorize requests to our REST API.

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

You can regenerate your API key at any time in your API settings.

Official API clients

Small, dependency-light official clients are available for Python (pip install gaston, Python 3.10+) and PHP (composer require streams-sro/gaston, PHP 7.0+). In both, the token can be passed directly or read from the GASTON_API_TOKEN environment variable. The snippets next to each endpoint below use these clients - switch between languages with the tabs above each example.

pip install gaston

composer require streams-sro/gaston

from gaston import GastonClient

# Token passed directly, or read from GASTON_API_TOKEN when omitted
client = GastonClient(token="gapi-...")

# Who am I + remaining quota
me = client.me()
print(me.email, "files left:", me.usage.files_left)

use StreamsSro\Gaston\GastonClient;

// Token passed directly, or read from GASTON_API_TOKEN when omitted
$client = new GastonClient('gapi-...');

// Who am I + remaining quota
$me = $client->me();
echo $me->email, ' files left: ', $me->usage->filesLeft, PHP_EOL;

Description of individual endpoints

The complete technical specification in OpenAPI 3.1 format is available here. A simplified description of the endpoints is provided below.

Retrieves basic information about the authenticated user, including service usage details such as the number of remaining API files available under the current quota.

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;

Lists processed files stored in the media library. The response contains summary information only and does not include the full transcript text.

Parameters

Returns complete information about a file, including the transcription, word-level timestamps, and available translations. You can filter the file version by specifying the lang parameter in the request. If lang=en is specified and an English translation exists, the English transcript will be returned.

Parameters

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;
}

Moves a media file to a selected directory.

Parameters

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

# Move back to the root directory
client.move_media(media_id="me...", dir_id=None)

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

// Move back to the root directory
$client->moveMedia('me...', null);

Uploads a media file for transcription. The maximum file size is 10 GB. You may specify the language spoken in the recording. If not specified, the language will be detected automatically. If known, specifying the language is recommended for faster processing. You may also define the file name in the media library. If not specified, the original file name will be used. After a successful request, the endpoint responds with file details including its ID and current status.

Parameters

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

# Large files can take minutes - override the upload timeout per call
client.transcribe("huge-recording.mp4", timeout=(10, None))

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

// Large files can take minutes - override the upload timeout per call (0 = no limit)
$client->transcribe('huge-recording.mp4', null, null, null, 0.0);

Similar to the previous endpoint, this method transcribes a video from a provided URL of a supported streaming service. After submitting the video URL, the file is automatically downloaded and processed.

Parameters

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;

Translates an already transcribed file into a selected language. 42 target languages are currently supported. Translation progress and available language versions for each file are indicated in the available_languages field, where the key represents the language and the value represents the percentage of completion.

For example, the following status indicates that the file is fully transcribed in Slovak (100%), while the English translation is still in progress at 66%:

available_languages: {
  sk: 100,
  en: 66
}

Parameters

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

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

Starts or restarts speaker diarization for a media file. Each language version maintains its own speaker segmentation. For example, you may have a diarized English version while the Spanish version remains without diarization.

Parameters

# Requires a completed translation in that language
client.diarize("me...", lang="de", speakers=2)

// Requires a completed translation in that language
$client->diarize('me...', 'de', 2);

Triggers word-level alignment of a translated sentence set against the source-language timestamps, giving the translated text per-word start/end times for karaoke-style playback. The target language must already be fully translated, otherwise the request returns a 400 error. Alignment runs asynchronously; progress is exposed under translation_alignment on the media object returned by /media.

Parameters

# Requires target_lang to already be fully translated
client.align_translation("me...", target_lang="de")

// Requires target_lang to already be fully translated
$client->alignTranslation('me...', 'de');

Recursively lists the full directory tree structure.

tree = client.directory_tree()

$tree = $client->directoryTree();

Creates a new directory.

Parameters

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

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

Renames a directory or moves it to another parent directory.

Parameters

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

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

Deletes a directory.

Parameters

client.delete_directory(folder.id)

$client->deleteDirectory($folder->id);

Search for sentences within your transcriptions.

Parameters

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

# Filter by directory and language, and page through results
page2 = client.search("budget", from_=50, max_=50, dir_ids=[42, 43], lang="en")

# Search within a single transcript only
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;
}

// Filter by directory and language, and page through results
$page2 = $client->search('budget', 50, 50, [42, 43], 'en');

// Search within a single transcript only
$page3 = $client->search('budget', 0, 50, null, null, '123');

Pricing

On the Gaston platform itself there are no limits on file transcription. You can transcribe as much as you need. Programmatic access through the API is a different story: every API request triggers transcription, translation and search workloads on our infrastructure, so to keep the service sustainable it can't logically be unlimited for a single flat price.

For that reason, API usage is billed per processed file. The price is €25 for every 100 files.

Only the transcription itself is behind this paywall. Once a file is in the system, you can do whatever you want with it. You can translate it into any supported language, run diarization, search, export, and organize it into directories at no additional charge. You pay once to get the file transcribed, and everything you do with it afterwards is free.

This flat per-file price assumes files of a reasonable length. To keep the service sustainable, we reserve the right to adjust pricing for extreme or automated bulk usage. We'll always reach out before any change affects you.

Processing & throughput

Transcription runs on a shared pool of GPUs with built-in flood protection. If you submit a large batch at once, it will not block other customers. Your files are processed steadily in the background, so a big batch may simply take a little longer to finish.

Partner pricing

If your project promotes our services in some way, you may qualify for partner pricing, which is even more favourable than the rates above. By partner we mean a customer project that helps make Gaston more visible, for example by referencing or recommending it to its own audience. Partner pricing is always an individual agreement and depends on how relevant your project is to us. If you think this could be a fit, reach out to contact@streams.guru and we will work out the details together.