API & MCP

Let your code or AI agent caption videos. Send a video, choose a caption style and position, and download the finished MP4 when the job completes. Jobs use your plan's monthly uploads and appear in My projects, where you can still fine-tune them in the editor.

Your API keys

Connect an AI agent (MCP)

Add the hosted MCP server to any MCP client (Claude, Cursor, etc.) and pass your key as a bearer token:

{
  "mcpServers": {
    "animatecaptions": {
      "type": "http",
      "url": "https://animatecaptions.com/api/mcp",
      "headers": { "Authorization": "Bearer ac_live_YOUR_KEY" }
    }
  }
}

Tools: list_caption_styles, create_caption_job, start_caption_job, get_caption_job, wait_for_caption_job, download_captioned_video, list_caption_jobs, get_account. When the server runs locally (stdio), agents can pass a local file_path and download straight to disk.

REST API

Base URL https://animatecaptions.com/api/v1. Authenticate with Authorization: Bearer ac_live_….

1. Create a job from a public URL

curl -X POST https://animatecaptions.com/api/v1/jobs \
  -H "Authorization: Bearer $AC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/clip.mp4",
    "style": "beast",
    "position": "bottom",
    "customization": { "font_size": "large", "highlight_color": "#FFD400" }
  }'

…or upload a file

# 1) create → response has upload.url
curl -X POST https://animatecaptions.com/api/v1/jobs -H "Authorization: Bearer $AC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"clip.mp4","file_size":10485760,"style":"punch","position":{"x":50,"y":80}}'

# 2) PUT the bytes (Content-Type must match upload.headers)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --upload-file clip.mp4

# 3) start processing
curl -X POST https://animatecaptions.com/api/v1/jobs/$JOB_ID/start -H "Authorization: Bearer $AC_API_KEY"

2. Poll status, then download

curl https://animatecaptions.com/api/v1/jobs/$JOB_ID -H "Authorization: Bearer $AC_API_KEY"
# status: awaiting_upload → queued → transcribing → rendering → completed | failed

curl -L -o captioned.mp4 https://animatecaptions.com/api/v1/jobs/$JOB_ID/download \
  -H "Authorization: Bearer $AC_API_KEY"

Job options

• style: caption style id (default beast). Full list: GET /api/v1/styles (no key needed).
• position: "top", "middle", "bottom", or {"x": 0-100, "y": 0-100} (centre of the captions, % of the frame).
• customization: font_size (small|medium|large), font_family, primary_color, highlight_color, active_word_color, uppercase, stroke_width, stroke_color, background_color, animation, ai_highlighter.
• theme_id: apply one of your saved themes. language: auto (default) or a language code.

Other endpoints

• GET /api/v1/jobs: list jobs (?limit=, ?before=, ?source=api)
• DELETE /api/v1/jobs/{id}: delete a job and its files
• GET /api/v1/me: plan, usage and limits

Errors are returned as {"error": {"code", "message"}}. Limits follow your plan: video length, file size (500 MB free / 2 GB paid), monthly uploads, and a watermark on the free plan.