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_keyfrom 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_keyPackages 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")