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.

Shell 
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.

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.

GET /user/me

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

GET /media/list

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

Parameters

Parameter Required Description
dir_id optional ID of the directory you want to list.
page optional Page number to display. Results are paginated in sets of 50 records.
GET /media

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

Parameter Required Description
lang optional Language code to filter the transcript version returned.
PATCH /media

Moves a media file to a selected directory.

Parameters

Parameter Required Description
media_id required ID of the media file to move.
dir_id required ID of the target directory.
NOTE

To move a file to the root directory, leave the dir_id parameter empty.

POST /media/transcribe

Uploads a media file for transcription. The maximum file size is 2 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

Parameter Required Description
lang optional Language of the file. Leave empty for auto-detection.
dir_id optional ID of the directory where the file should be stored after transcription.
POST /media/transcribe-url

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

Parameter Required Description
url required URL where the media file is located.
lang optional Language of the file. Leave empty for auto-detection.
dir_id optional ID of the directory where the file should be stored after transcription.
POST /media/translate

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
}

Parameters

Parameter Required Description
media_id required ID of the media file to translate.
target_lang required Target language for translation.
PATCH /media/diarize

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

Parameter Required Description
media_id required ID of the media file to diarize.
lang required Language version to diarize.
speakers optional Number of speakers in the file. Leave empty for auto-detection.
GET /directory/tree

Recursively lists the full directory tree structure.

POST /directory

Creates a new directory.

Parameters

Parameter Required Description
title required Name of the new directory.
dir_id optional Parent directory where the new directory should be created. Leave empty to create in root.
PATCH /directory

Renames a directory or moves it to another parent directory.

Parameters

Parameter Required Description
dir_id required ID of the directory to be moved or renamed.
title optional Provide a new title to rename the directory.
parent_id optional ID of the new parent directory if moving the directory.
DELETE /directory

Deletes a directory.

Parameters

Parameter Required Description
dir_id required 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.

GET /sentence/search

Search for sentences within your transcriptions.

Parameters

Parameter Required Description
query required Search query. Supports "OR", "AND", and wildcard (*) operators.
_from optional Index of the first record to return.
_max optional Maximum number of returned records.
dir_ids optional List of directory IDs to search within. Leave empty for global search.
lang optional Language of sentences to search in.

Conclusion

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.

GASTON REST API — full OpenAPI specification →