Auto Subtitle Generator API

Overview

Auto Subtitle Generator transcribes speech and embeds captions in the video. Use a preset or custom formatting to style them.

How It Works

Upload video - Provide a video with spoken content
The API transcribes the speech.
Subtitles generated - Formatted subtitles with accurate timing
Download video - Retrieve video with embedded subtitles

Use Cases

Social media content - Add captions for better engagement and accessibility
Educational videos - Make content accessible to all learners
Marketing videos - Increase view time with subtitled content
International content - Transcribe videos in multiple languages
Add captions for accessibility. Review transcription and timing before publishing.

Best Practices

Video Quality

Use clear audio - Better audio quality produces more accurate transcriptions.

Minimize background noise - Clean audio improves accuracy
Clear speech - Well-enunciated words transcribe better
Single speaker preferred - Best results with one speaker at a time
Avoid music overlap - Heavy music can interfere with transcription

Language Support

The API has no language-selection parameter. Review generated captions for names, accents, and technical terms, and choose a font that supports your language.

Subtitle styling

Choose karaoke, cinematic, minimalist, or highlight with style.template. Use style.custom_config to override a template. If you omit the template, custom configuration must include font, text_color, vertical_position, and horizontal_position.

Code Examples

Basic Auto Subtitle

from magic_hour import Client
from os import getenv

client = Client(token=getenv("MAGIC_HOUR_API_KEY"))

result = client.v1.auto_subtitle_generator.generate(
    assets={
        "video_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/jude_bellingham_greeting.mp4"
    },
    start_seconds=0,
    end_seconds=8,
    style={"template": "karaoke"},
    name="Subtitled Video",
    wait_for_completion=True,
    download_outputs=True,
    download_directory="."
)

if result.status == "complete":
    print(f"✅ Subtitles complete!")
    print(f"Downloaded to: {result.downloaded_paths}")
    print(f"Credits charged: {result.credits_charged}")
else:
    print(f"Job ended with status: {result.status}")
    if result.error:
        print(f"Error: {result.error.message}")

import { Client } from "magic-hour";

const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY });

const result = await client.v1.autoSubtitleGenerator.generate(
  {
    assets: {
      videoFilePath:
        "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/obamamicdrop.mov",
    },
    startSeconds: 0,
    endSeconds: 2,
    style: { template: "karaoke" },
    name: "Subtitled Video",
  },
  {
    waitForCompletion: true,
    downloadOutputs: true,
    downloadDirectory: ".",
  }
);

if (result.status === "complete") {
  console.log(`✅ Subtitles complete!`);
  console.log(`Downloaded to: ${result.downloadedPaths}`);
} else {
  console.error(`Job ended with status: ${result.status}`);
  if (result.error) console.error(result.error.message);
}

Output Format

Retrieve the captioned video from the completed video project’s downloads array. The API has no SRT/VTT export-format option.

Pricing

Cost depends on the selected video segment. The create response contains an estimate in credits_charged; check the completed job for the final total. See Billing for current pricing.

Try this in our Google Colab Cookbook: Run this API with sample code. Just add your API key.

API Reference