opentranscription

Python client for the OpenTranscription API. Upload a file, transcribe it against any model in the catalogue, and wait for the result.

pip install opentranscription

Usage

from opentranscription import OpenTranscription

ot = OpenTranscription(api_key=os.environ["OT_API_KEY"])

job = ot.transcribe(
    "earnings-call.mp3",
    # Primary plus backups, tried in order when a provider fails. Use `model`
    # instead for a single id, or for auto/best, auto/cheapest, auto/fastest.
    models=["assemblyai/best", "deepgram/nova-3"],
    language="en",
    diarization=True,
    # Names and jargon the model has the weakest prior for, which are usually
    # the reason you wanted the transcript.
    custom_words=["EBITDA", "Sanjay Bhattacharya", "Nasdaq", "ARR"],
)

done = ot.wait_for_job(job["id"])
print(done["transcript"]["text"])

transcribe does three things: requests a signed upload URL, PUTs the bytes straight to storage, and creates the job. The API key never travels to the storage host.

The first argument is a path, an open binary file, or raw bytes with file_name= alongside it.

async

The same surface, awaited. Both classes come from one package and share their implementation.

from opentranscription import AsyncOpenTranscription

async with AsyncOpenTranscription(api_key=os.environ["OT_API_KEY"]) as ot:
    job = await ot.transcribe("earnings-call.mp3", model="auto/best")
    done = await ot.wait_for_job(job["id"])

Use the context manager, on either class, or the connection pool outlives the work. The sync client also has close(), the async one aclose().

Request fields

The audio is required. Everything else is optional, and leaving a field out is not the same as passing False or None: left out means the server's own default applies.

That last row is why the defaults are NOT_GIVEN rather than None. None already means something to the API on two of these fields, so it cannot also mean "the caller said nothing".

The field list is checked against the published OpenAPI document on every test run. A field the API adds that this client does not offer fails the build by name, and so does one this client offers that the API no longer accepts.

API

OpenTranscription(api_key, base_url=..., timeout=..., http_client=..., sleep=...) accepts your own httpx.Client when you need custom transport, proxies, or retries, and an injectable sleep so tests need no real waiting. base_url defaults to https://opentranscription.io.

Passing your own client means your settings, not ours: the follow_redirects default this sets is yours to decide. The audio upload opts out of redirects per request either way, so that one is not yours to get wrong.

Rate limits (429) are retried automatically, up to four waits. The API sends X-RateLimit-Reset (an epoch second) and that is what paces the retry; Retry-After is honoured first if a response ever carries one. A single transcribe can trip a ten-per-minute limit on its own, since it is an upload, a create, and then a poll every couple of seconds.

Errors

• ApiError is any request the API did not answer properly: a non-2xx response, or a 2xx whose body is not JSON (a base_url pointing at a locale-prefixed page such as https://opentranscription.io/en gets the website's HTML with a 200). It carries status and, when the API sent one, code. A 402 also carries payment, a dict with balance_credits and required_credits (1 credit = $0.01), checkout_url (a billing page that needs a signed-in browser, not a payment link) and, when free minutes ran out, reset_at; hand the user that URL, since only they can add credits. payment is None on every other error.
• JobFailedError means the job ran and failed, so retrying the request is pointless. It carries code (also on job["error_code"]), which is what tells you whether to re-encode the audio, pick another model, or give up.
• Both subclass OpenTranscriptionError.

Branch on code, not on the message, which is prose and may be reworded.

Getting a key

Create one in your dashboard, or run npx @opentranscription/cli login to mint one through the browser.

Requires Python 3.10 or newer, and httpx.

License

MIT