Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.mirage.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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. 
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. 
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. 
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

Last modified on March 27, 2026