Skip to main content

Python recipes

Install dependency:

pip install requests

End-to-end submit + poll​

See the full production-ready example on Your first request.

Batch analysis from a folder​

from pathlib import Path
from concurrent.futures import ThreadPoolExecutor
import os, time, requests

API_BASE = "https://platform.zenhire.ai"
API_KEY  = os.environ["ZENHIRE_API_KEY"]

def submit(audio_path: Path) -> str:
    with audio_path.open("rb") as f:
        r = requests.post(
            f"{API_BASE}/api/v1/speech/analyze",
            headers={"X-API-Key": API_KEY},
            files={"audio": f},
            data={"language": "en", "externalId": audio_path.stem},
            timeout=60,
        )
    r.raise_for_status()
    return r.json()["id"]

def poll(request_id: str) -> dict:
    while True:
        time.sleep(15)
        r = requests.get(
            f"{API_BASE}/api/v1/speech/analyze/{request_id}",
            headers={"X-API-Key": API_KEY}, timeout=30,
        )
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "15")))
            continue
        r.raise_for_status()
        d = r.json()
        if d["status"] in ("success", "partial", "failed"):
            return d

def analyze(audio_path: Path) -> dict:
    return poll(submit(audio_path))

audio_files = list(Path("recordings/").glob("*.mp3"))
with ThreadPoolExecutor(max_workers=8) as pool:
    for path, result in zip(audio_files, pool.map(analyze, audio_files)):
        print(f"{path.name}: {result['status']} "
              f"overall={result.get('scores',{}).get('overall')}")

Look up runs by externalId​

import requests, os

API_KEY = os.environ["ZENHIRE_API_KEY"]

def runs_for_candidate(external_id: str) -> list[dict]:
    r = requests.get(
        "https://platform.zenhire.ai/api/v1/speech/runs",
        headers={"X-API-Key": API_KEY},
        params={"externalId": external_id, "limit": 100},
    )
    r.raise_for_status()
    return r.json()["runs"]

Check credits before submitting a big batch​

import requests, os

API_KEY = os.environ["ZENHIRE_API_KEY"]

def credits() -> int:
    r = requests.get(
        "https://platform.zenhire.ai/api/v1/credits",
        headers={"X-API-Key": API_KEY},
    )
    r.raise_for_status()
    return r.json()["creditBalance"]

if credits() < 100:
    raise SystemExit("Top up before running this batch")