Podcast Transcription with Speaker Labels

Overview

Transcribe multi-speaker audio at scale using the Gnani Prisma v2.5 Batch STT API. This guide walks through every step — from submitting an audio file to receiving a clean, speaker-separated transcript — using podcast transcription as the working example. Audio-first content — podcasts, interview recordings, panel discussions — carries information that stays locked unless it is transcribed. Speaker-level transcription is what separates a readable document from a wall of undifferentiated text. You know who said what, when they said it, and for how long.

Capability	What it enables downstream
Speaker-separated output	Per-speaker text blocks mean editors can review one voice at a time, and content teams can attribute quotes accurately.
Time-aligned segments	Every segment carries a `start_time` and `end_time`, enabling subtitle generation, chapter markers, and clip extraction at a specific timestamp.
9 Indian languages	Transcribe Hindi, Tamil, Telugu, Kannada, Malayalam, Bengali (India and Bangladesh), Marathi, and English without switching providers or pipelines.
Batch processing	Submit up to 100 files in a single job. Run overnight jobs, backfill archives, or process weekly episode batches without managing queues yourself.

Other Use Cases

The same create-start-poll-download pipeline works for any long-form, speaker-rich audio. Any scenario involving long audio files, two speakers, and a need for speaker-separated text maps directly to this pipeline.

Use Case	Description
Journalist Interviews	Transcribe field recordings with interviewer and subject separated. Feed directly into editorial workflows without manual formatting.
Parliamentary & Panel Debates	Attribute statements to the correct speaker for political reporting, fact-checking, or archival. Supports Devanagari and regional scripts natively.
EdTech Lecture Recordings	Transcribe faculty and student exchanges. Generate accessible transcripts for students, search indexes for course platforms, and study material exports.
Legal Depositions & Hearings	Produce verbatim speaker-attributed records of proceedings for court reporter review and archival.
Radio Archive Digitisation	Backfill years of archived broadcasts into searchable, attributed text. Batch processing handles large volumes without manual queuing.
Corporate Town Halls & Earnings Calls	Generate attributed transcripts of leadership Q&A sessions. Surface speaker-specific statements for internal comms or investor relations.
Documentary & Film Production	Auto-generate interview transcripts for rough-cut editing. Export time-coded speaker lines directly to editing software.
Doctor-Patient Consultations	Transcribe recorded consultations with doctor and patient separated. Enable structured documentation workflows for EMR systems.

Two-speaker limit: The Gnani Prisma v2.5 Batch STT API supports a maximum of two distinct speakers per file. It is optimised for two-party audio — interviews, conversations, and one-on-one recordings. Panel discussions with three or more speakers are outside the current scope.

Prerequisites

Requirement	Details
Gnani Prisma v2.5 API key	Available from the Gnani API dashboard. You will use this as the `X-API-Key-ID` header on every request.
Python 3.10+	The pipeline uses f-strings, `pathlib`, and `typing` patterns that require Python 3.10 or later.
Audio files	Supported formats: WAV, MP3, MP4, FLAC, OGG, Opus, M4A, AAC, WebM, AMR. Each file must be 10 MB or smaller. Up to 100 files per job.

# HTTP client (used for create, start, poll, and download calls)
pip install requests

No SDK is required for this pipeline. All calls use the standard HTTP REST endpoints.

Authentication

Header	Required	Description
`X-API-Key-ID`	Yes	Your Gnani Prisma v2.5 API key. Required on every Batch STT request.
`X-API-Request-ID`	No	A UUID you assign for tracing. Useful for correlating your application logs with platform support.

Store your API key as an environment variable. Never hardcode it in source files or commit it to version control.

.env

GNANI_API_KEY=your-api-key-here

loading credentials

import os

API_KEY = os.getenv("GNANI_API_KEY")
HEADERS = {"X-API-Key-ID": API_KEY}

Never hardcode API keys. Do not commit credentials to version control. Use environment variables, a secrets manager, or a vault. Rotate your key immediately if it is exposed.

Limits & Supported Formats

Item	Limit
Max file size	10 MB per file
Max files per job	100 files
Max ZIP compressed size	50 MB
Max ZIP decompressed size	200 MB
Minimum poll interval	10 seconds between status calls for the same `job_id`
Speaker diarization	Maximum 2 speakers per file
`transcript_url` expiry	1 hour — re-call Get Job Files if expired

See Batch STT Introduction — Limits for the full reference.

Supported Audio Formats

.wav · .mp3 · .mp4 · .flac · .ogg · .opus · .m4a · .aac · .webm · .amr

Format	Extension	Notes
WAV	`.wav`	Uncompressed. Highest quality but largest file size.
FLAC	`.flac`	Lossless compression. Good balance of quality and size for archival audio.
AAC / M4A	`.m4a`, `.aac`	Common podcast export format. Well-supported across recording tools.
MP3	`.mp3`	Widely used lossy format.
OGG / Opus	`.ogg`, `.opus`	Efficient compression — recommended for high-volume batch jobs.
WebM / AMR	`.webm`, `.amr`	Supported for mobile and web-captured audio.

Files over 10 MB: Compress or re-encode before upload, or split into smaller segments and stitch transcripts in order after download. The Batch API does not accept individual files larger than 10 MB.

Supported Languages

Pass the BCP-47 code in the language_code field of your job config.

Language	Code	Native Script
Bengali (Bangladesh)	`bn-BD`	বাংলা
Bengali (India)	`bn-IN`	বাংলা
English (India)	`en-IN`	Latin
Hindi	`hi-IN`	हिन्दी
Kannada	`kn-IN`	ಕನ್ನಡ
Malayalam	`ml-IN`	മലയാളം
Marathi	`mr-IN`	मराठी
Tamil	`ta-IN`	தமிழ்
Telugu	`te-IN`	తెలుగు

ITN not supported on Batch STT. Inverse Text Normalization (spoken numbers, currency, dates) is not available in the Batch Jobs API. Use REST STT if you need ITN on short clips.

Pipeline

Creating a job does not start transcription. You must call /start after upload.

Step	Endpoint	Reference
1. Create	`POST /stt/v3/batch/jobs`	Create Job
2. Start	`POST /stt/v3/batch/jobs/{job_id}/start`	Start Job
3. Poll	`GET /stt/v3/batch/jobs/{job_id}`	Get Job Status
4. List files	`GET /stt/v3/batch/jobs/{job_id}/files?status=COMPLETED`	Get Job Files
5. Download	`GET <transcript_url>`	JSON with `full_transcript` + `segments`

Create the job

POST to /stt/v3/batch/jobs with a multipart body: a config JSON field and one or more files. Receive a job_id with status CREATED. Transcription has not started yet.

Start the job

POST to /stt/v3/batch/jobs/{job_id}/start. Status moves to STARTING, then QUEUED → IN_PROGRESS → COMPLETED.

Poll for completion

GET /stt/v3/batch/jobs/{job_id} every 10 seconds until status reaches a terminal state (COMPLETED, PARTIAL_FAILURE, FAILED, or CANCELLED).

Fetch transcript URLs

GET /stt/v3/batch/jobs/{job_id}/files?status=COMPLETED. Each completed file includes a transcript_url (valid for 1 hour).

Download and parse

GET each transcript_url to retrieve JSON with full_transcript and segments. Group by speaker_id, build per-speaker text blocks with timestamps, and save output files.

Step 1 — Create Job

create_job()

import json
import os
import requests
from pathlib import Path

BATCH_JOBS = "https://api.vachana.ai/stt/v3/batch/jobs"

def create_job(
    audio_paths: list[str],
    language_code: str = "hi-IN",
    with_diarization: bool = True,
    num_speakers: int = 2,
) -> str:
    api_key = os.getenv("GNANI_API_KEY")
    headers = {"X-API-Key-ID": api_key}

    config = {
        "model": "gnani-prisma-v2.5",
        "language_code": language_code,
        "mode": "transcribe",
        "with_diarization": with_diarization,
        "is_multi_channel": False,
    }
    if with_diarization:
        config["num_speakers"] = num_speakers

    files = [
        ("config", (None, json.dumps(config), "application/json")),
    ]
    for path in audio_paths:
        files.append(("files", (Path(path).name, open(path, "rb"), "audio/wav")))

    resp = requests.post(BATCH_JOBS, headers=headers, files=files)

    for key, (_, fh, _) in files:
        if key == "files":
            fh.close()

    resp.raise_for_status()
    job_id = resp.json()["job_id"]
    print(f"Created job. job_id: {job_id}")
    return job_id

Multiple files: Add additional ("files", ...) tuples. Up to 100 files per job, each 10 MB or smaller.

Step 2 — Start Job

start_job()

BATCH_START = "https://api.vachana.ai/stt/v3/batch/jobs/{job_id}/start"

def start_job(job_id: str) -> None:
    api_key = os.getenv("GNANI_API_KEY")
    headers = {"X-API-Key-ID": api_key}
    url = BATCH_START.format(job_id=job_id)

    resp = requests.post(url, headers=headers)
    resp.raise_for_status()
    print(f"Start accepted. status: {resp.json()['status']}")

Step 3 — Poll

poll_until_complete()

import time
from typing import Optional

BATCH_STATUS  = "https://api.vachana.ai/stt/v3/batch/jobs/{job_id}"
POLL_INTERVAL = 10  # seconds — minimum recommended interval

TERMINAL_STATUSES = {"COMPLETED", "PARTIAL_FAILURE", "FAILED", "START_FAILED", "CANCELLED"}

def poll_until_complete(job_id: str) -> Optional[str]:
    api_key = os.getenv("GNANI_API_KEY")
    headers = {"X-API-Key-ID": api_key}
    url     = BATCH_STATUS.format(job_id=job_id)

    print(f"Polling job {job_id} every {POLL_INTERVAL}s...")

    while True:
        time.sleep(POLL_INTERVAL)

        resp = requests.get(url, headers=headers)
        resp.raise_for_status()
        payload = resp.json()
        status  = payload["status"]

        completed = payload.get("completed_files", 0)
        total     = payload.get("total_files", "?")
        print(f"  [{status}]  {completed}/{total} files complete")

        if status in TERMINAL_STATUSES:
            if status == "COMPLETED":
                print(f"Job complete. {completed} file(s) transcribed.")
                return status
            print(f"Job ended with status: {status}")
            return status

Minimum poll interval: 10 seconds. Do not poll more frequently than every 10 seconds for the same job_id.

Step 4 — Fetch Transcript URLs

fetch_completed_files()

BATCH_FILES = "https://api.vachana.ai/stt/v3/batch/jobs/{job_id}/files"

def fetch_completed_files(job_id: str) -> list[dict]:
    api_key = os.getenv("GNANI_API_KEY")
    headers = {"X-API-Key-ID": api_key}
    url     = BATCH_FILES.format(job_id=job_id)

    resp = requests.get(url, headers=headers, params={"status": "COMPLETED"})
    resp.raise_for_status()
    return resp.json().get("files", [])

Step 5 — Download & Parse

download_and_parse()

import json
from pathlib import Path
from typing import Dict

def download_transcript(transcript_url: str) -> dict:
    resp = requests.get(transcript_url)
    resp.raise_for_status()
    return resp.json()

def parse_transcript(transcript: dict, original_path: str, output_dir: Path) -> dict:
    fname    = Path(original_path).stem
    segments = transcript.get("segments", [])

    if not segments:
        print(f"Skipping {fname}: no segments")
        return {}

    lines, speaker_times, segment_meta = [], {}, []

    for seg in segments:
        spk   = seg.get("speaker_id", "UNKNOWN")
        text  = seg.get("text", "").strip()
        start = seg.get("start_time", 0.0)
        end   = seg.get("end_time",   0.0)

        ts = f"{int(start // 60):02d}:{int(start % 60):02d}"
        lines.append(f"[{ts}] SPEAKER_{spk}: {text}")
        speaker_times[spk] = speaker_times.get(spk, 0.0) + (end - start)
        segment_meta.append({
            "segment_id":        seg.get("segment_id"),
            "speaker_id":        spk,
            "start_time":        start,
            "end_time":          end,
            "text":              text,
            "language_detected": seg.get("language_detected"),
        })

    transcript_path = output_dir / f"{fname}_transcript.txt"
    transcript_path.write_text("\n".join(lines), encoding="utf-8")

    metadata_path = output_dir / f"{fname}_metadata.json"
    metadata_path.write_text(json.dumps({
        "filename":          original_path,
        "full_transcript":   transcript.get("full_transcript"),
        "duration_seconds":  transcript.get("duration_seconds"),
        "speaker_talk_time": {f"SPEAKER_{k}": round(v, 2) for k, v in speaker_times.items()},
        "segments":          segment_meta,
    }, indent=2, ensure_ascii=False), encoding="utf-8")

    print(f"Parsed: {fname} → {len(lines)} segments, {len(speaker_times)} speaker(s)")
    return {
        "transcript_path": str(transcript_path),
        "metadata_path":   str(metadata_path),
    }

Full Script

podcast_transcription.py

import json
import os
import time
import requests
from pathlib import Path
from typing import Dict, List, Optional

BATCH_JOBS    = "https://api.vachana.ai/stt/v3/batch/jobs"
BATCH_START   = "https://api.vachana.ai/stt/v3/batch/jobs/{job_id}/start"
BATCH_STATUS  = "https://api.vachana.ai/stt/v3/batch/jobs/{job_id}"
BATCH_FILES   = "https://api.vachana.ai/stt/v3/batch/jobs/{job_id}/files"
POLL_INTERVAL = 10
OUTPUT_DIR    = "outputs"

TERMINAL_STATUSES = {"COMPLETED", "PARTIAL_FAILURE", "FAILED", "START_FAILED", "CANCELLED"}

Path(OUTPUT_DIR).mkdir(exist_ok=True)


def create_job(
    audio_paths: List[str],
    language_code: str = "hi-IN",
    with_diarization: bool = True,
    num_speakers: int = 2,
) -> str:
    api_key = os.getenv("GNANI_API_KEY")
    headers = {"X-API-Key-ID": api_key}

    config = {
        "model": "gnani-prisma-v2.5",
        "language_code": language_code,
        "mode": "transcribe",
        "with_diarization": with_diarization,
        "is_multi_channel": False,
    }
    if with_diarization:
        config["num_speakers"] = num_speakers

    files = [("config", (None, json.dumps(config), "application/json"))]
    for path in audio_paths:
        files.append(("files", (Path(path).name, open(path, "rb"), "audio/wav")))

    resp = requests.post(BATCH_JOBS, headers=headers, files=files)
    for key, (_, fh, _) in files:
        if key == "files":
            fh.close()

    resp.raise_for_status()
    job_id = resp.json()["job_id"]
    print(f"Created {len(audio_paths)} file(s). job_id: {job_id}")
    return job_id


def start_job(job_id: str) -> None:
    api_key = os.getenv("GNANI_API_KEY")
    headers = {"X-API-Key-ID": api_key}
    resp = requests.post(BATCH_START.format(job_id=job_id), headers=headers)
    resp.raise_for_status()
    print(f"Start accepted. status: {resp.json()['status']}")


def poll_until_complete(job_id: str) -> Optional[str]:
    api_key = os.getenv("GNANI_API_KEY")
    headers = {"X-API-Key-ID": api_key}
    url     = BATCH_STATUS.format(job_id=job_id)

    print(f"Polling every {POLL_INTERVAL}s...")
    while True:
        time.sleep(POLL_INTERVAL)
        resp    = requests.get(url, headers=headers)
        resp.raise_for_status()
        payload = resp.json()
        status  = payload["status"]
        print(f"  [{status}]  {payload.get('completed_files', 0)}/{payload.get('total_files', '?')} files")
        if status in TERMINAL_STATUSES:
            return status if status == "COMPLETED" else None


def fetch_completed_files(job_id: str) -> list:
    api_key = os.getenv("GNANI_API_KEY")
    headers = {"X-API-Key-ID": api_key}
    resp = requests.get(
        BATCH_FILES.format(job_id=job_id),
        headers=headers,
        params={"status": "COMPLETED"},
    )
    resp.raise_for_status()
    return resp.json().get("files", [])


def parse_transcript(transcript: dict, original_path: str, output_dir: Path) -> Dict[str, str]:
    fname    = Path(original_path).stem
    segments = transcript.get("segments", [])
    if not segments:
        return {}

    lines, speaker_times, segment_meta = [], {}, []
    for seg in segments:
        spk   = seg.get("speaker_id", "UNKNOWN")
        text  = seg.get("text", "").strip()
        start = seg.get("start_time", 0.0)
        end   = seg.get("end_time",   0.0)
        ts    = f"{int(start // 60):02d}:{int(start % 60):02d}"
        lines.append(f"[{ts}] SPEAKER_{spk}: {text}")
        speaker_times[spk] = speaker_times.get(spk, 0.0) + (end - start)
        segment_meta.append({
            "segment_id": seg.get("segment_id"),
            "speaker_id": spk,
            "start_time": start,
            "end_time":   end,
            "text":       text,
        })

    transcript_path = output_dir / f"{fname}_transcript.txt"
    transcript_path.write_text("\n".join(lines), encoding="utf-8")

    metadata_path = output_dir / f"{fname}_metadata.json"
    metadata_path.write_text(json.dumps({
        "filename":          original_path,
        "full_transcript":   transcript.get("full_transcript"),
        "duration_seconds":  transcript.get("duration_seconds"),
        "speaker_talk_time": {f"SPEAKER_{k}": round(v, 2) for k, v in speaker_times.items()},
        "segments":          segment_meta,
    }, indent=2, ensure_ascii=False), encoding="utf-8")

    print(f"Saved: {transcript_path.name}")
    return {"transcript_path": str(transcript_path), "metadata_path": str(metadata_path)}


if __name__ == "__main__":
    job_id = create_job(
        audio_paths=["/path/to/episode_01.wav"],
        language_code="hi-IN",
        with_diarization=True,
        num_speakers=2,
    )
    start_job(job_id)

    if poll_until_complete(job_id):
        output_dir = Path(OUTPUT_DIR) / f"job_{job_id}"
        output_dir.mkdir(parents=True, exist_ok=True)

        outputs = {}
        for file_entry in fetch_completed_files(job_id):
            transcript_url = file_entry.get("transcript_url")
            if not transcript_url:
                continue
            transcript = requests.get(transcript_url).json()
            result = parse_transcript(transcript, file_entry["original_path"], output_dir)
            if result:
                outputs[Path(file_entry["original_path"]).stem] = result

        print(f"\nDone. {len(outputs)} transcript(s) saved to {output_dir}/")

Sample Output

outputs/
└── job_019fa79e-81f9-7a8a-a446-6eff16ddec30/
    ├── episode_01_transcript.txt   ← speaker-labelled, time-stamped transcript
    └── episode_01_metadata.json    ← full_transcript, talk time, segment detail

episode_01_transcript.txt

[00:00] SPEAKER_1: नमस्ते, मैं हूँ रवि शर्मा और आज हम बात करेंगे भारत के स्टार्टअप इकोसिस्टम के बारे में।
[00:07] SPEAKER_2: हाँ रवि जी, बहुत अच्छा विषय है। पिछले पाँच साल में बहुत कुछ बदला है।
[00:14] SPEAKER_1: बिल्कुल। दो लाख करोड़ से ज़्यादा की फंडिंग आई है 2024 में।
[00:22] SPEAKER_2: और यूनिकॉर्न्स की संख्या भी 100 के पार पहुँच गई है।

episode_01_metadata.json

{
  "filename": "episode_01.wav",
  "full_transcript": "नमस्ते, मैं हूँ रवि शर्मा...",
  "duration_seconds": 2847.5,
  "speaker_talk_time": {
    "SPEAKER_1": 1423.8,
    "SPEAKER_2": 1389.2
  },
  "segments": [
    {
      "segment_id": 0,
      "speaker_id": 1,
      "start_time": 0.0,
      "end_time": 6.8,
      "text": "नमस्ते, मैं हूँ रवि शर्मा..."
    }
  ]
}

Related docs: Batch STT Introduction · Create Job · Start Job · Get Job Status · Get Job Files

Gnani APIs

APIs

Use Cases

Podcast Transcription with Speaker Labels

Overview

Other Use Cases

Prerequisites

Authentication

Limits & Supported Formats

Supported Audio Formats

Supported Languages

Pipeline

Step 1 — Create Job

Step 2 — Start Job

Step 3 — Poll

Step 4 — Fetch Transcript URLs

Step 5 — Download & Parse

Full Script

Sample Output

​Overview

​Other Use Cases

​Prerequisites

​Authentication

​Limits & Supported Formats

​Supported Audio Formats

​Supported Languages

​Pipeline

​Step 1 — Create Job

​Step 2 — Start Job

​Step 3 — Poll

​Step 4 — Fetch Transcript URLs

​Step 5 — Download & Parse

​Full Script

​Sample Output

Overview

Other Use Cases

Prerequisites

Authentication

Limits & Supported Formats

Supported Audio Formats

Supported Languages

Pipeline

Step 1 — Create Job

Step 2 — Start Job

Step 3 — Poll

Step 4 — Fetch Transcript URLs

Step 5 — Download & Parse

Full Script

Sample Output