Gaston API Client
A small, typed Python client for the Gaston API: transcription, translation, AI digests and full-text search of sentences within transcribed recordings.
Requires a Gaston account and an API token (see Configuration).
Installation
pip install gaston
Requires Python 3.10+.
For local development from a checkout instead:
pip install -e .
Quick start
from gaston import GastonClient
client = GastonClient(token="gapi-...")
# Who am I + remaining quota
me = client.me()
print(me.email, "files left:", me.usage.files_left)
# Transcribe a local file
result = client.transcribe("interview.mp4", lang="en", title="My interview")
print(result.id, result.state)
# Transcribe from a URL (YouTube or web)
client.transcribe_url("https://youtu.be/dQw4w9WgXcQ", lang="en")
# Translate an existing transcription
client.translate(result.id, target_lang="de")
# Speaker diarization (requires a completed translation in that language)
client.diarize(result.id, lang="de", speakers=2)
# Word-level alignment of a translation against source timestamps
# (requires a completed translation in that language)
client.align_translation(result.id, target_lang="de", clamp=True)
# List your media (paginated). Items are Media objects.
page = client.list_media(page=1)
print("total:", page.total, "pages:", page.pages)
for item in page:
print(item.id, item.title, item.state, item.available_languages)
# Fetch a single media item with its sentences
media = client.get_media(result.id, lang="en")
for sentence in media.sentences:
print(sentence.id, sentence.text, sentence.speaker)
# Export a transcript (text, text_timestamps, csv, srt or audio)
client.export_media_to_file(result.id, "subtitles.srt", format="srt", lang="de")
# AI digest (summary) of a URL; see "Digest" below
digest = client.wait_for_digest(client.create_digest("https://youtu.be/dQw4w9WgXcQ").digest_id)
# Full text search across the whole library
results = client.search("climate change", max_=20)
print("total matches:", results.total)
for hit in results:
print(hit["_sentence"]["body"], "->", hit["_highlight"]["body"])
See Search for query syntax and filtering options.
Configuration
Generate an API token in the Gaston app under Settings -> API. Full endpoint documentation is available at https://www.gaston.live/en/api.
The token can be supplied directly or via an environment variable:
| Argument | Environment variable | Default |
|---|---|---|
token |
GASTON_API_TOKEN |
(required) |
# Uses GASTON_API_TOKEN from the environment
with GastonClient() as client:
...
Timeouts
Ordinary requests use a 30s timeout. The file upload in transcribe can take
minutes for large files, so it uses a separate, more generous upload_timeout
(default (10s connect, 600s read)).
A timeout may be a single float, a (connect, read) tuple, or None to wait
indefinitely.
# Customise the defaults for all calls
client = GastonClient(
token="gapi-...",
timeout=30,
upload_timeout=(10, 1800), # allow up to 30 min to upload large files
)
# Or override per call (e.g. no read timeout for a very large file)
client.transcribe("huge-recording.mp4", timeout=(10, None))
Exporting
export_media() returns the file in memory as a MediaExport (content,
filename, content_type, plus .text and .save(path)), while
export_media_to_file() streams it straight to disk — prefer it for audio.
# Transcript as plain text (format: text, text_timestamps, csv, srt, audio)
export = client.export_media("me...", format="text", lang="en")
print(export.filename) # filename suggested by the server, e.g. "My interview.txt"
print(export.text)
# Subtitles split into blocks of at most 8 words, prefixed with speaker names
# (speaker names require diarization)
client.export_media_to_file(
"me...", "interview.srt", format="srt", max_words_per_block=8, include_speakers=True
)
# Audio (a finished dubbed track for `lang` if one exists, otherwise the
# original). Passing an existing directory saves it under the server-suggested
# filename.
path = client.export_media_to_file("me...", ".", format="audio", lang="de")
lang defaults to the media's original language. Exporting audio, or any
media longer than 30 minutes, requires a paid plan; otherwise an
AuthenticationError (HTTP 403) is raised. Audio exports use the client's
upload_timeout by default.
Digest
A digest is an AI-generated summary of a recording, optionally with the answer
to a question about it. create_digest() adds the media behind a URL (like
transcribe_url()) and requests the digest; it is generated once the media is
transcribed, so poll get_digest() or let wait_for_digest() do it.
digest = client.create_digest(
"https://youtu.be/dQw4w9WgXcQ",
detail="detailed", # "brief" (default) or "detailed"
question="What does the singer promise?",
answer_lang="de", # language of the summary and answer
)
print(digest.digest_id, digest.digest_state) # e.g. "dg... pending"
# Polls every 10s for up to 15 minutes; raises GastonError on timeout
digest = client.wait_for_digest(digest.digest_id)
if digest.is_failed:
print("Digest failed:", digest.error)
else:
print(digest.summary.text)
for citation in digest.summary.citations:
# marker as used in the text, e.g. "[S12-S15]", with its position in seconds
print(citation.marker, citation.start, citation.end)
if digest.answer is not None:
print(digest.answer.text or f"No answer: {digest.answer.error}")
The full signatures are:
client.create_digest(url, lang=None, dir_id=None, detail="brief", question=None, answer_lang=None)
client.get_digest(digest_id)
client.wait_for_digest(digest_id, timeout=900.0, interval=10.0)
Digest.digest_state is one of pending, generating, ready or error,
with the properties is_ready, is_failed and is_finished. Digest.id and
Digest.state describe the underlying media, and transcription_progress is
reported while it is still being transcribed. Things to know:
create_digest()returns only the ids and states;summary,answer,languageand the rest are filled in byget_digest().- A failed digest is returned, not raised:
is_failedis true anderrorsays why. Exceptions are reserved for failed requests (an unknown digest id raisesNotFoundError; an account with AI features disabled raisesAuthenticationError). - If the summary succeeded but the question could not be answered, the digest
is still
ready:answer.textisNoneandanswer.erroris set. - Requesting the same digest of the same media again returns the existing one.
answer_langis validated by the server, whose list differs fromSUPPORTED_LANGUAGES; an unsupported code raises aBadRequestErrorwith the accepted codes in.details. Questions are limited to 2000 characters.- Transcribing a long recording takes minutes, so keep the
wait_for_digest()timeout generous (passtimeout=Noneto wait indefinitely).
Directories
folder = client.create_directory("Podcasts")
client.update_directory(folder.id, title="Podcast archive")
moved = client.move_media(media_id="me...", dir_id=folder.id) # returns the updated Media
tree = client.directory_tree()
client.delete_directory(folder.id)
Search
client.search(query, from_=0, max_=50, dir_ids=None, lang=None) runs a
full-text search over every sentence in your transcribed media.
Query syntax
The query supports a subset of the Lucene query_string syntax:
| Feature | Example | Notes |
|---|---|---|
Boolean AND |
cats AND dogs |
both terms must appear |
Boolean OR |
cats OR dogs |
either term |
Boolean NOT |
cats NOT dogs |
exclude a term |
| Grouping | (cats OR dogs) AND vet |
combine operators with parentheses |
| Exact phrase | "climate change" |
quoted terms match as a phrase |
| Trailing wildcard | transcri* |
matches transcribe, transcription... |
Leading wildcards (*tion), field selectors, fuzzy (~), boosts (^) and
ranges are not supported and are stripped server-side. Queries must be at least
3 characters.
results = client.search('(invoice OR receipt) AND "due date" NOT draft')
Filtering and pagination
# Search within a single directory
client.search("budget", dir_ids=[42])
# Search across several directories
client.search("budget", dir_ids=[42, 43, 7])
# Restrict to one language, and page through results
page2 = client.search("budget", from_=50, max_=50, lang="en")
Reading results
search() returns a SearchResults object. Iterate it for hits, or read
.total for the overall match count. Each hit is a dict with:
_sentence- the matched sentence plus itsmediametadata (id, title, duration, directory, thumbnail, file, originUrl)._highlight- matched fragments with the hit terms wrapped in<hlt>...</hlt>tags.
results = client.search("climate change", max_=20)
print("total matches:", results.total)
for hit in results:
sentence = hit["_sentence"]
print(sentence["media"]["title"], "|", hit["_highlight"]["body"])
Error handling
All failures raise a subclass of GastonError:
from gaston import GastonClient, AuthenticationError, RateLimitError, NotFoundError
try:
client.transcribe("clip.mp4")
except RateLimitError:
print("File limit reached")
except AuthenticationError:
print("Bad token / disabled account")
except NotFoundError as e:
print("Not found:", e.message)
| Exception | Trigger |
|---|---|
AuthenticationError |
HTTP 403, invalid token / disabled user |
BadRequestError |
HTTP 400, invalid parameters |
NotFoundError |
HTTP 404, resource not found |
RateLimitError |
HTTP 429, usage limit exceeded |
GastonAPIError |
any other API error |
Every exception carries .status_code, .message, .details and the raw
.payload.
Supported languages
from gaston import SUPPORTED_LANGUAGES, TRANSLATION_LANGUAGES
SUPPORTED_LANGUAGES lists transcription source languages; TRANSLATION_LANGUAGES
lists the available translation targets.
Metadata
Release files for gaston 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gaston-0.8.0.tar.gz | 26.2 kB | Without provenance | Details for gaston-0.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gaston-0.8.0-py3-none-any.whl | Python 3 | none | any | Details for gaston-0.8.0-py3-none-any.whl |
Total release size: 46.5 kB
Release files / gaston-0.8.0.tar.gz
| Download URL | gaston-0.8.0.tar.gz |
|---|---|
| Size | 26.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b007f08ea498defddfe3b64fdab4ef2e0da91f2d762b604c6b319d00e0f3bb0b
|
|
BLAKE2b-256 checksum How to use checksums |
673802d30cd18e420acb14fef27d4297c9759c54c46e0b05ac2c9cce1fec0d24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Release files / gaston-0.8.0-py3-none-any.whl
| Download URL | gaston-0.8.0-py3-none-any.whl |
|---|---|
| Size | 20.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9703b8bbac46ed613c6113dd45735456a64072251aec681e4bd665222b5f9a47
|
|
BLAKE2b-256 checksum How to use checksums |
5a3935df2e0fe8f6e40cf68fa305800f063e16c108a197360f1b776f55f9164d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Security for gaston 0.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.