Blog / transcribe-video-python

How to Transcribe a Video in Python With an API (URL to SRT)

Quick answer

A complete Python script that turns a video URL into an SRT file: create a transcript job, poll with a timeout, handle failures, and download the result.

2026-10-05 | 8 min read | ReelWords Team

ReelWords illustration of a Python script turning a video URL into a timestamped SRT transcript.

There are two ways to transcribe a video in Python. You can run a speech model on your own machine, which means installing FFmpeg, downloading model weights, and extracting audio first. Or you can send the video's URL to an API and get the transcript back. This tutorial takes the second route and ends with a script of about sixty lines that turns a video URL into an SRT file.

The API used here is ReelWords, which accepts public URLs from YouTube, TikTok, Instagram, X, and Facebook as well as direct links to media files. The pattern (create a job, poll, download) is the same for most asynchronous transcription APIs.

Before you transcribe a video in Python: setup

You need Python 3.9 or later, the requests library, and an API key.

pip install requests
export REELWORDS_KEY="rw_your_key_here"

Create the key in your ReelWords account under API keys. Keep it in an environment variable or a secrets manager, never in source control.

The three endpoints involved:

StepRequestSuccess
CreatePOST /api/v1/transcript-jobs201 with a job object
PollGET /api/v1/transcript-jobs/{id}200 with current status
DownloadGET /api/v1/transcript-jobs/{id}/download?format=srt200 with the file body

All requests go to https://api.reelwords.ai with an x-api-key header. The full schemas are in the API docs.

Step 1: Create the transcript job

import os
import requests

BASE = "https://api.reelwords.ai/api/v1"
session = requests.Session()
session.headers["x-api-key"] = os.environ["REELWORDS_KEY"]


def create_job(video_url, language=None):
    payload = {"url": video_url}
    if language:
        payload["language"] = language  # optional BCP-47 hint, e.g. "en"
    response = session.post(f"{BASE}/transcript-jobs", json=payload, timeout=30)
    response.raise_for_status()
    return response.json()["id"]

A requests.Session reuses the connection and carries the header on every call. raise_for_status() turns 400, 401, and 402 responses into exceptions, so a bad URL, a bad key, or an exhausted allowance stops the script instead of producing a confusing error later.

Step 2: Poll until the job finishes

The job's status moves from started to processing, then to complete or failed. The API does not send webhooks, so the client polls.

import time


class TranscriptFailed(Exception):
    pass


def wait_for_job(job_id, timeout=600):
    deadline = time.monotonic() + timeout
    delay = 2.0
    while time.monotonic() < deadline:
        response = session.get(f"{BASE}/transcript-jobs/{job_id}", timeout=30)
        response.raise_for_status()
        job = response.json()
        if job["status"] == "complete":
            return job
        if job["status"] == "failed":
            raise TranscriptFailed(
                f"{job.get('failureReason')}: {job.get('failureMessage')}"
            )
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout} seconds")

Three choices here are worth copying into any polling loop:

  1. A deadline. Without one, a stuck job hangs your script indefinitely.
  2. A growing delay. Starting at two seconds catches fast jobs, and backing off to fifteen avoids hammering the API during long ones.
  3. An explicit failure path. A failed job carries failureReason and failureMessage. Surface them; do not retry blindly, since a private or deleted video will fail the same way again.

Step 3: Read the segments

A completed job includes the transcript as structured data, so you can use it without downloading a file:

def print_segments(job):
    for segment in job["result"]["segments"]:
        print(f"[{segment['start']:7.2f} - {segment['end']:7.2f}] {segment['text']}")

Each segment has start and end in seconds and a text string. The job also reports title, durationSeconds, language, segmentCount, and transcriptSource, which is native_captions when the platform's own caption track was used and gemini_asr when the audio was transcribed.

Step 4: Download SRT, VTT, or text

def download(job_id, fmt="srt", path=None):
    response = session.get(
        f"{BASE}/transcript-jobs/{job_id}/download",
        params={"format": fmt},
        timeout=60,
    )
    response.raise_for_status()
    path = path or f"{job_id}.{'txt' if fmt.startswith('txt') else fmt}"
    with open(path, "w", encoding="utf-8") as handle:
        handle.write(response.text)
    return path

fmt can be srt, vtt, txt, or txt_timestamps. Writing with encoding="utf-8" matters on Windows, where the default encoding can corrupt accented characters and emoji. If you are unsure which subtitle format your player needs, see SRT vs VTT.

The complete script

import sys

if __name__ == "__main__":
    url = sys.argv[1]
    job_id = create_job(url, language="en")
    print(f"Created job {job_id}")

    job = wait_for_job(job_id)
    print(f"{job['segmentCount']} segments from {job['transcriptSource']}")

    saved = download(job_id, "srt")
    print(f"Saved {saved}")

Put the three functions above it in transcribe.py and run:

python transcribe.py "https://www.youtube.com/watch?v=VIDEO_ID"

Transcribing many videos

For a list of URLs, create all the jobs first and poll them together. The work happens on the server, so client-side threads add little.

def transcribe_many(urls):
    pending = {create_job(url): url for url in urls}
    results = {}
    while pending:
        for job_id in list(pending):
            job = session.get(f"{BASE}/transcript-jobs/{job_id}", timeout=30).json()
            if job["status"] in ("complete", "failed"):
                results[pending.pop(job_id)] = job
        if pending:
            time.sleep(5)
    return results

Before a large batch, check your remaining allowance:

usage = session.get(f"{BASE}/transcript-jobs/usage", timeout=30).json()
print(usage["remaining"], "of", usage["limit"], "left on", usage["planTier"])

A 402 from create_job means the allowance is used up. Stop the batch at that point; retrying will not help. Add a production deadline to the loop above, as in wait_for_job.

When to run a local model instead

A local model such as Whisper makes sense when the video cannot leave your network, when you already have GPU capacity, or when the files are on disk and not at a public URL. It costs you an FFmpeg dependency, model downloads, and audio extraction, which we cover in how to extract audio from a video URL. For a wider look at hosted options and their prices, see the speech-to-text API comparison. If you work in JavaScript, the Node.js pipeline guide covers the same architecture.

FAQ

How do I transcribe a video in Python without FFmpeg?

Use an API that accepts the video URL. The service retrieves the media and returns text, so nothing needs to be installed locally beyond requests.

Can Python transcribe a YouTube video from its link?

Yes. Post the watch-page URL to the transcript-jobs endpoint. If the video has captions, those are used; otherwise the audio is transcribed.

How do I get an SRT file in Python?

Call the download endpoint with format=srt after the job completes and write response.text to a UTF-8 file.

Why do I get a 409 when downloading?

The job has not completed. Poll the job until status is complete before requesting a download.

Should I use asyncio for this?

Only if the rest of your application is async. The waiting happens on the server, so a simple loop that polls several jobs is enough for most batch scripts.

How do I transcribe a local video file?

The transcript endpoint takes a URL. Upload the file to storage that serves it over public HTTPS and pass that link, or use the ReelWords web app to upload directly.

How accurate is the transcript?

It depends on the audio and on whether a native caption track existed. Review names, numbers, and specialist terms before publishing; our guide to fixing inaccurate auto captions has a checklist.

Ready to run it? Create an API key, see ReelWords features, compare plans on pricing, or check the FAQ.