Skip to main content

Gaston API Client

PyPI version Python versions License: MIT

A small, typed Python client for the Gaston API: transcription, translation 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")

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

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)

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 its media metadata (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.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gaston 0.7.0
File Size Uploaded Provenance Actions
gaston-0.7.0.tar.gz 20.8 kB Without provenance Details for gaston-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gaston 0.7.0
File Interpreter ABI Platform Actions
gaston-0.7.0-py3-none-any.whl Python 3 none any Details for gaston-0.7.0-py3-none-any.whl

Total release size: 37.7 kB

Release files / gaston-0.7.0.tar.gz

Download URL gaston-0.7.0.tar.gz
Size 20.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e7f8b035f012f9cf047f5051a5fa223bdf54972789a93956c69d12827f4de506
BLAKE2b-256 checksum
How to use checksums
9d97663582c17e154cb1dfcafb6c36737f60951d5a921bfd0f88307f50ff986b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / gaston-0.7.0-py3-none-any.whl

Download URL gaston-0.7.0-py3-none-any.whl
Size 16.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
115e6b0188c0c8fac19308d5a2da7c2db2677fba43bc3e216dc3df42eeafc8ac
BLAKE2b-256 checksum
How to use checksums
aff07681cb4dcf8bf38e18c99f9d362940e8b2f5d5393ee401e1510ecc271a7d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Security for gaston 0.7.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page