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())

const formData = new FormData();
formData.append("caption_template_id", "ctpl_DxflLOnuKkb198FNdI9E");
formData.append("video", await fs.readFile("input.mp4"));

// Or use an existing video ID instead of uploading:
// formData.append("video_id", "video_abc123def456");

const response = await fetch("https://api.mirage.app/v1/videos/captions", {
  method: "POST",
  headers: {
    "x-api-key": "<api-key>"
  },
  body: formData
});

const data = await response.json();
console.log(data);

curl --request POST \
  --url https://api.mirage.app/v1/videos/captions \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form caption_template_id=ctpl_DxflLOnuKkb198FNdI9E \
  --form video=@input.mp4

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())

const response = await fetch(`https://api.mirage.app/v1/videos/${videoId}`, {
  method: "GET",
  headers: {
    "x-api-key": "<api-key>"
  }
});

const data = await response.json();
console.log(data);

curl --request GET \
  --url https://api.mirage.app/v1/videos/{video_id} \
  --header 'x-api-key: <api-key>'

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)

const response = await fetch(`https://api.mirage.app/v1/videos/${videoId}/content`, {
  method: "GET",
  headers: {
    "x-api-key": "<api-key>"
  },
  redirect: "follow"
});

curl --request GET \
  --url https://api.mirage.app/v1/videos/{video_id}/content \
  --header 'x-api-key: <api-key>' \
  --location \
  --output output.mp4

Video requirements

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

Using the API

Video Captioning

Video Generation

Reference

Get started with video captions

Overview

Prerequisites

1) Choose a Caption Template

2) Add Captions to a Video

3) Check Job Status

4) Download the Video

Video requirements

API Reference

​Overview

​Prerequisites

​1) Choose a Caption Template

​2) Add Captions to a Video

​3) Check Job Status

​4) Download the Video

​Video requirements

​API Reference

Overview

Prerequisites

1) Choose a Caption Template

2) Add Captions to a Video

3) Check Job Status

4) Download the Video

Video requirements

API Reference