Varmirdocs
Docs/Guides/Python

Python

Use the official varmir package, or call the API with requests.

SDK

The official SDK (Python 3.10+, MIT, source) wraps every endpoint, raises typed errors, and handles live streaming. AsyncVarmir has the same methods as coroutines.

shell
pip install varmir
export VARMIR_API_KEY=mstk_your_key
from varmir import Varmir, InsufficientCreditsError

client = Varmir()  # reads VARMIR_API_KEY
try:
    r = client.transcribe("call.wav", language="uk", translate_to="en")
except InsufficientCreditsError:
    print("Top up credits")
else:
    print(r["text"])
    print(r["translation"]["text"])

Without the SDK

Any Python 3 with requests works. Keep the key in an environment variable, not in code.

shell
pip install requests
export VARMIR_KEY=mstk_your_key

Packages with names similar to varmir from other publishers aren't ours.

Transcribe a file

Python
import os
import requests

API = "https://api.varmir.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VARMIR_KEY']}"}

with open("meeting.mp3", "rb") as f:
    r = requests.post(
        f"{API}/transcribe",
        headers=HEADERS,
        files={"audio": f},
        data={"translate_to": "en"},   # optional
        timeout=600,                   # long files take a while
    )
r.raise_for_status()
result = r.json()
print(result["language"], result["text"])
if result["translation"]:
    print(result["translation"]["text"])
print("charged:", result["charged_sec"], "s")

Handle errors

Every error returns {"error": {"code", "message"}}. Retry 429 and 503 after the Retry-After header; fix everything else. See Rate limits & errors.

Python
import time

RETRYABLE = {429, 503}

def transcribe(path, retries=3, **fields):
    for attempt in range(retries + 1):
        with open(path, "rb") as f:
            r = requests.post(f"{API}/transcribe", headers=HEADERS,
                              files={"audio": f}, data=fields, timeout=600)
        if r.ok:
            return r.json()
        err = r.json()["error"]            # {"code": ..., "message": ...}
        if r.status_code in RETRYABLE and attempt < retries:
            time.sleep(int(r.headers.get("Retry-After", 5)))
            continue
        # insufficient_credits, invalid_audio, invalid_api_key, ...
        raise RuntimeError(f"{err['code']}: {err['message']}")

Balance & usage

Both calls are free and limited to 30 per minute per key.

Python
me = requests.get(f"{API}/me", headers=HEADERS, timeout=30).json()
print("quota left:", me["quota"]["remaining_sec"], "s")
print("credits left:", me["credits"]["balance_sec"], "s")

usage = requests.get(f"{API}/usage", headers=HEADERS,
                     params={"days": 7}, timeout=30).json()
print("last 7 days:", usage["total_sec"], "s in", usage["total_requests"], "requests")