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.
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. For example:
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.
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.
Lists processed files stored in the media library.
Available parameters:
- dir_id: ID of the directory you want to list (optional).
- page: Page number to display. Results are paginated in sets of 50 records.
The response contains summary information only and does not include the full transcript text.
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.
Moves a media file to a selected directory.
Available parameters:
- media_id: ID of the media file to move.
- dir_id: ID of the target directory.
NOTE: To move a file to the root directory, leave the dir_id parameter empty.
Uploads a media file for transcription. The maximum file size is 2GB.
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.
Available parameters:
- lang: Language of the file. Leave empty for auto-detection.
- dir_id: ID of the directory where the file should be stored after transcription.
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.
Available parameters:
- url: URL where the media file is located.
- lang: Language of the file. Leave empty for auto-detection.
- dir_id: ID of the directory where the file should be stored after transcription.
Translates an already transcribed file into a selected language. Currently, approximately 40 languages are 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
}
Available parameters:
- media_id: ID of the media file to translate.
- target_lang: Target language for translation.
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.
Available parameters:
- media_id: ID of the media file to diarize.
- lang: Language version to diarize.
- speakers: Number of speakers in the file. Leave empty
for auto-detection.
Recursively lists the full directory tree structure.
Creates a new directory.
Available parameters:
- title: Name of the new directory.
- dir_id: Parent directory where the new directory
should be created. Leave empty to create the directory in the root.
Deletes a directory.
Available parameters:
- dir_id: ID of the directory to remove.
NOTE: This method deletes only the directory itself. It does NOT remove files contained within it.
All child directories are deleted recursively.
Renames a directory or moves it to another parent directory.
Available parameters:
- dir_id: ID of the directory to be moved or renamed.
- title: Provide a new title to rename the directory.
- parent_id: ID of the new parent directory if moving the directory.
Search for sentences within your transcriptions.
Available parameters:
- query: Search query. Supports "OR", "AND", and wildcard (*) operators.
- _from: Index of the first record to return.
- _max: Maximum number of returned records.
- dir_ids: List of directory IDs to search within. Leave empty for global search.
- lang: Language of sentences to search in.
Our API has no limitations beyond the monthly quota defined by your subscription plan. For technical support, contact us anytime at contact@streams.guru. We continuously expand our endpoints and add new functionality.