---
title: "Add Captions to a Video"
method: POST
path: "/v1/videos/captions"
tags: ["Video Captions"]
---

# Add Captions to a Video

`POST /v1/videos/captions`

Create a captioned video from either an uploaded video file or an existing video ID.

You must provide exactly one of:
- `video`: A video file upload (.mp4 or .mov), max 50mb
- `video_id`: An existing video ID to add captions to

If providing `video_id`, the source video must have status COMPLETE before it can be captioned.

To fetch the captioned video, use the `GET videos/{video_id}` endpoint.

## Headers

- `x-api-key` string, required — API Key for authentication

## Response `200`

Returns a Video object representing the captioning job

- MAVideo — Represents a video object. A video can be created via generation (an image appearance reference plus audio) or captioning (adding captions to an existing video).
  - `id` string, required — Video generation job ID
  - `object` 'video'
  - `status` 'PROCESSING' | 'COMPLETE' | 'FAILED' | 'CANCELLED', required — Current state of the video
  - `created_at` integer, required — When the video was created (unix timestamp)
  - `completed_at` integer, nullable — When processing completed (unix timestamp)
  - `progress` integer, nullable — Progress percentage (0-100)
  - `error` MAVideoError — Error payload that explains why generation failed, if applicable
    - `code` string, required — Error code
    - `message` string, required — Error message
  - `model` 'mirage-video-1-latest', nullable — Model used for generation (only for source='generation')
  - `source_video_id` string, nullable — The input video that was captioned (only for source='caption')
  - `caption_template_id` string, nullable — Caption style template used (only for source='caption')
  - `share_link_url` string, nullable — Public share link for a completed internal video, when enabled.
  - `video_id` string, required — [Deprecated] Use "id" instead.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mirage/apis/mirage-video-api.md) · [All operations](https://skmtc.net/mirage/apis/mirage-video-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mirage/mirage-video-api/revisions/021b1eec81a4/schema)