Get started with video captions

Automatically transcribe audio and render animated stylized captions onto vertical video with the Mirage video captions API and caption template IDs.

Overview

With the Mirage API, you can automatically transcribes your video’s audio and renders beautifully animated captions directly onto the video. Choose from a variety of caption templates to match your brand or creative vision.

Prerequisites

Create an API key in the platform dashboard.

1) Choose a Caption Template

Adding captions to videos requires a caption template. Browse all available templates in the caption templates gallery or fetch them programatically.

Example Template: Heat

Caption Template ID

ctpl_DxflLOnuKkb198FNdI9E

2) Add Captions to a Video

Submit your video along with a caption template ID. You can either upload a video file directly or reference an existing video ID from a previous generation.

Python

import requests

url = "https://api.mirage.app/v1/videos/captions"
headers = {
    "x-api-key": "<api-key>"
}
files = {
    "video": open("input.mp4", "rb")
}
data = {
    "caption_template_id": "ctpl_DxflLOnuKkb198FNdI9E"
}

# Or use an existing video ID instead of uploading:
data = {
    "caption_template_id": "ctpl_DxflLOnuKkb198FNdI9E",
    "video_id": "video_abc123def456"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Response (example)

{
  "id": "video_cap789xyz",
  "object": "video",
  "status": "PROCESSING",
  "created_at": 1730822600,
  "progress": 0,
  "source_video_id": null,
  "caption_template_id": "ctpl_DxflLOnuKkb198FNdI9E"
}

3) Check Job Status

Poll until status becomes COMPLETE.

Python

import requests

url = f"https://api.mirage.app/v1/videos/{video_id}"
headers = {
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)
print(response.json())

Status values

• QUEUED
• PROCESSING
• COMPLETE
• FAILED
• CANCELLED

4) Download the Video

Once status is COMPLETE, download your captioned video.

Python

import requests

url = f"https://api.mirage.app/v1/videos/{video_id}/content"
headers = {
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers, allow_redirects=True)

with open("captioned.mp4", "wb") as f:
    f.write(response.content)

Video requirements

• Aspect ratio: 9:16 (vertical/portrait)
• Max file size: 50 MB
• Max duration: 5 minutes
• Formats: MP4, MOV

API Reference

• Add Captions
• List Caption Templates
• Retrieve Caption Template
• Retrieve Video
• Retrieve Video Content