Capsubs API

# pip install requests
import os
import time
import requests

BASE = "https://capsubs.com"
HEADERS = {"X-API-Key": os.environ["CAPSUBS_API_KEY"]}

# 1. Upload
with open("video.mp4", "rb") as f:
    r = requests.post(f"{BASE}/api/v1/captions/auto", headers=HEADERS,
                      files={"file": f}, data={"style": "default"})
r.raise_for_status()
job = r.json()

# 2. Wait until it's done
while job["status"] not in ("completed", "failed"):
    time.sleep(5)
    r = requests.get(f"{BASE}/api/v1/jobs/{job['id']}", headers=HEADERS)
    r.raise_for_status()
    job = r.json()

if job["status"] == "failed":
    raise SystemExit(job["error_message"])

# 3. Download
r = requests.get(job["output_url"], headers=HEADERS)
r.raise_for_status()
with open("captioned.mp4", "wb") as out:
    out.write(r.content)

{
  "id": "3f0c6c1e-8a51-4c47-9d0b-6b2f1f0f7a9e",
  "status": "pending",
  "progress": 0,
  "message": "Job created. Processing will begin shortly.",
  "created_at": "2026-01-20T12:00:00+00:00"
}

{
  "id": "3f0c6c1e-8a51-4c47-9d0b-6b2f1f0f7a9e",
  "status": "completed",
  "progress": 100,
  "original_filename": "video.mp4",
  "output_url": "https://capsubs.com/api/v1/jobs/3f0c6c1e-8a51-4c47-9d0b-6b2f1f0f7a9e/download",
  "duration_seconds": 31.2,
  "word_count": 84,
  "error_message": null,
  "tts_enabled": true,
  "created_at": "2026-01-20T12:00:00+00:00",
  "processing_started_at": "2026-01-20T12:00:01+00:00",
  "completed_at": "2026-01-20T12:00:40+00:00"
}

curl -X POST "https://capsubs.com/api/v1/captions/auto" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@video.mp4" \
  -F 'style={"style":"boxed","position":"top","highlight_color":"#39FF14","max_words_per_line":2}'

curl -X POST "https://capsubs.com/api/v1/captions/auto" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@video.mp4" \
  -F "tts_enabled=true" \
  -F "tts_voice=nova" \
  -F "mute_original_audio=true"

curl -X POST "https://capsubs.com/api/v1/captions/custom" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@video.mp4" \
  -F 'captions={"words":[{"text":"Hello","start":0.0,"end":0.4},{"text":"world","start":0.4,"end":0.9}]}'

curl -X POST "https://capsubs.com/api/v1/captions/batch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "videos=@video1.mp4" \
  -F "videos=@video2.mp4" \
  -F "style=classic"

# Response: {"jobs": [{"id": ...}, {"id": ...}], "total": 2, "message": "..."}

# Files over 95 MB (up to 1 GB): send them in parts, then caption the upload_id.
import os
import requests

BASE = "https://capsubs.com"
HEADERS = {"X-API-Key": os.environ["CAPSUBS_API_KEY"]}
path = "long-video.mp4"

# 1. Start an upload: tells you the part size and how many parts to send
r = requests.post(f"{BASE}/api/v1/uploads", headers=HEADERS,
                  json={"filename": os.path.basename(path), "size": os.path.getsize(path)})
r.raise_for_status()
upload = r.json()  # {"upload_id": "...", "chunk_size": 52428800, "chunks": 3}

# 2. Send each part as the raw request body (parts are numbered from 0)
with open(path, "rb") as f:
    for index in range(upload["chunks"]):
        r = requests.put(f"{BASE}/api/v1/uploads/{upload['upload_id']}/chunks/{index}",
                         headers=HEADERS, data=f.read(upload["chunk_size"]))
        r.raise_for_status()

# 3. Caption it: same fields as a normal upload, with upload_id instead of file
r = requests.post(f"{BASE}/api/v1/captions/auto", headers=HEADERS,
                  data={"upload_id": upload["upload_id"], "style": "default"})
r.raise_for_status()
job = r.json()  # then poll and download as usual

curl -X POST "https://capsubs.com/api/v1/webhooks/" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/capsubs-webhook", "events": ["job.completed", "job.failed"]}'

# The response includes "secret": use it to check each delivery's signature.

{
  "event": "job.completed",
  "job_id": "3f0c6c1e-8a51-4c47-9d0b-6b2f1f0f7a9e",
  "timestamp": "2026-01-20T12:00:40.123456",
  "data": {
    "status": "completed",
    "output_url": "https://capsubs.com/api/v1/jobs/3f0c6c1e-8a51-4c47-9d0b-6b2f1f0f7a9e/download",
    "output_filename": "processed_3f0c6c1e_input.mp4",
    "word_count": 84,
    "duration_seconds": 31.2
  }
}
// job.failed: "data": { "status": "failed", "error": "..." }

import hashlib, hmac

def is_from_capsubs(secret: str, headers, raw_body: bytes) -> bool:
    timestamp = headers["X-Capsubs-Timestamp"]
    expected = "sha256=" + hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, headers["X-Capsubs-Signature"])