# Captions — how to use (mcp.ai)

Connect your Captions account and use 8 tools for AI content generation straight from your AI agent. Connect with your own API key. Captions provides the Mirage API for generating videos and speech and adding styled captions to videos.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_captions?ms=1787293380000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `captions_add_captions`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/captions`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/captions/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/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_D
  - body: { video?: object, video_id?: string, caption_template_id: string }
- `POST https://api.mcp.ai/api/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.
  - body: { video_id: string }
- `POST https://api.mcp.ai/api/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 s
  - body: { text: string, voice_id: string }
- `POST https://api.mcp.ai/api/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
  - body: { audio_reference: object, image_reference: object }
- `POST https://api.mcp.ai/api/captions/get/caption/template` — Retrieve one caption style by ID, including its name and preview video URL.
  - body: { template_id: string }
- `POST https://api.mcp.ai/api/captions/get/video/status` — Retrieve the current state, progress, and error details for a video generation or captioning job.
  - body: { video_id: string }
- `POST https://api.mcp.ai/api/captions/list/caption/templates` — Return one page of available caption styles, including names and preview video URLs.
  - body: { limit?: integer, cursor?: string }
- `POST https://api.mcp.ai/api/captions/list/videos` — Return one page of video jobs owned by the connected Mirage account, including each job's status and progress.
  - body: { limit?: integer, order?: string, cursor?: string }

## Example prompts
- "What can I do in Captions?"
- "Show me a summary of my Captions account"

## More
- Page: https://mcp.ai/captions
- Agent spec (llms.txt): https://mcp.ai/captions/llms.txt
- Postman collection: https://mcp.ai/captions/postman.json