---
canonical_url: "https://docs.composio.dev/toolkits/captions"
markdown_url: "https://docs.composio.dev/toolkits/captions.md"
product: "platform"
version: null
last_updated: null
---

# Captions

Captions provides the Mirage API for generating videos and speech and adding styled captions to videos.

- **Category:** ai content generation
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 8
- **Triggers:** 0
- **Slug:** `CAPTIONS`
- **Version:** 00000000_00

## Tools

### Add Captions

**Slug:** `CAPTIONS_ADD_CAPTIONS`

Start an asynchronous job that transcribes and renders a selected caption style onto an uploaded or existing completed video. Use CAPTIONS_GET_VIDEO_STATUS to monitor the returned job, then CAPTIONS_DOWNLOAD_VIDEO when it completes. This call consumes paid Mirage credits and cannot be cancelled or deleted once submitted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `video` | object | No | MP4 or MOV video upload. The video must use a 9:16 aspect ratio, be at most 50 MB, and be at most 5 minutes long. Provide this or video_id, but not both. |
| `video_id` | string | No | ID of an existing COMPLETE video in video_* format. Provide this or video, but not both. |
| `caption_template_id` | string | Yes | Caption style template ID returned by CAPTIONS_LIST_CAPTION_TEMPLATES. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download Video

**Slug:** `CAPTIONS_DOWNLOAD_VIDEO`

Download the MP4 content of a completed video job and return an offloaded file reference. Use CAPTIONS_GET_VIDEO_STATUS first to confirm the job is COMPLETE.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `video_id` | string | Yes | ID of a completed video in video_* format. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Speech

**Slug:** `CAPTIONS_GENERATE_SPEECH`

Generate WAV speech synchronously from text using a known Mirage voice ID and return an offloaded audio file reference. This call consumes paid Mirage credits and cannot be cancelled or deleted once submitted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to synthesize as speech; must not be empty. |
| `voice_id` | string | Yes | Mirage voice ID to synthesize with. The public API does not provide a voice-list endpoint. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Video

**Slug:** `CAPTIONS_GENERATE_VIDEO`

Start an asynchronous Mirage Video 1 job that animates a portrait image using speech audio. Use the returned job ID with CAPTIONS_GET_VIDEO_STATUS. This call consumes paid Mirage credits and cannot be cancelled or deleted once submitted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `audio_reference` | object | Yes | WAV or MP3 speech audio that drives the portrait animation. Duration must be between 1 and 180 seconds. |
| `image_reference` | object | Yes | JPEG or PNG portrait image to animate. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Caption Template

**Slug:** `CAPTIONS_GET_CAPTION_TEMPLATE`

Retrieve one caption style by ID, including its name and preview video URL.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | Caption template ID in ctpl_* format. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Video Status

**Slug:** `CAPTIONS_GET_VIDEO_STATUS`

Retrieve the current state, progress, and error details for a video generation or captioning job.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `video_id` | string | Yes | Video job ID in video_* format, returned by video generation or captioning. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Caption Templates

**Slug:** `CAPTIONS_LIST_CAPTION_TEMPLATES`

Return one page of available caption styles, including names and preview video URLs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum caption templates to return on this page (1-100). |
| `cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Videos

**Slug:** `CAPTIONS_LIST_VIDEOS`

Return one page of video jobs owned by the connected Mirage account, including each job's status and progress.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum videos to return on this page (1-100). |
| `order` | string ("asc" | "desc") | No | Sort videos by creation time in ascending or descending order. |
| `cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |