Guide · API and MCP

How to add subtitles to a video with an API

One HTTP call, two cases. If you only have the video, the API writes the subtitles and burns them in. If you already have an SRT or VTT file, it burns yours as is. Both return the finished MP4; the automatic one also returns SRT and VTT (the burn does with combined: true). No FFmpeg, about $0.05 per minute. AI agents do the same over MCP, for example from Claude.

Pick the call

You haveREST (MCP tool)PriceYou get
Only the videoPOST /v1/captionscaption_video5 credits/min (about $0.05)MP4 with burned subtitles + SRT, VTT, JSON
The video and an SRT or VTT filePOST /v1/captions/burnburn_captions4 credits/min (about $0.04)MP4 with your subtitles burned in (+ SRT, VTT with combined: true)
The video, and you only need the subtitle filePOST /v1/transcribetranscribe1 credit/min (about $0.01)SRT, VTT or JSON with word timestamps

1 credit = 1 US cent, billed per second. Converting SRT to VTT and back needs no call: use the free subtitle toolbox.

Step by step

  1. 1. Get an API key

    Create a key at awesomevideoeditor.com/account, or from a terminal with no sign-up. The response shows token once: save it as $AV_KEY. A new key starts with 0 credits. While the trial runs it can claim 10 free welcome credits: solve the small proof-of-work from GET /v1/keys/challenge and send it to POST /v1/keys/welcome (details on /facts and in llms.txt). Without credits, a paid call answers 402 with a checkout link and nothing is charged.

    curl -X POST https://api.awesomevideoeditor.com/v1/keys/anonymous -H "Content-Type: application/json" -d '{"name":"my-app"}'
  2. 2. No subtitle file yet: caption the video in one call

    Send a public link to the video (direct file, Google Drive, Dropbox or OneDrive share link) as sourceUrl and a caption style as preset. The API transcribes the speech, burns styled subtitles into the frames and returns the MP4 plus SRT, VTT and a JSON transcript with word timings. wait: true holds the request up to 45 seconds by default (waitSeconds up to 50), so short clips come back finished. 5 credits per minute; the 8-second sample costs 2.

    curl -X POST https://api.awesomevideoeditor.com/v1/captions \
      -H "Authorization: Bearer $AV_KEY" -H "Content-Type: application/json" \
      -d '{"sourceUrl":"https://awesomevideoeditor.com/samples/cc0-interview-es.mp4","preset":"hormozi-pop","wait":true}'
  3. 3. Already have an SRT or VTT: burn it as is

    Send the video as mediaUrl (or a fileId from an upload) and the text of your subtitle file in subtitles: SRT, WebVTT or JSON cues, up to 1.5 MB. The file's text goes in the JSON body, not a link to it; jq --rawfile does the escaping. Your timings and wording are kept; nothing is transcribed. preset picks the look. 4 credits per minute of video.

    jq -n --rawfile srt captions.srt \
      '{mediaUrl: "https://example.com/interview.mp4", subtitles: $srt, preset: "builtin:karaoke", combined: true}' |
    curl -X POST https://api.awesomevideoeditor.com/v1/captions/burn \
      -H "Authorization: Bearer $AV_KEY" -H "Content-Type: application/json" -d @-
  4. 4. Poll the job and download the MP4

    The burn call answers 202 with a job id. Poll GET /v1/jobs/{id} after pollAfterSeconds until status is succeeded, or pass webhookUrl to get the finished job POSTed to you. result.url is the MP4. result.files has the SRT and VTT for a caption job, and for a burn job sent with combined: true. Links are signed and expire after 24 hours, so download them right away. Failed jobs are refunded.

    curl https://api.awesomevideoeditor.com/v1/jobs/$JOB_ID -H "Authorization: Bearer $AV_KEY"

What comes back

Real responses for the 8-second CC0 sample, trimmed (both recipes run on November 18, 2026).

Caption the video (no subtitle file)

200  (answered after 24 s)
{
  "id": "c0339030-...",
  "kind": "caption",
  "status": "succeeded",
  "audioSeconds": 8,
  "creditsCharged": 2,
  "result": {
    "url": "https://api.awesomevideoeditor.com/v1/jobs/c0339030-.../result?...",
    "language": "es",
    "preset": { "id": "builtin:hormozi-pop", "name": "Hormozi Pop" },
    "files": [
      { "name": "mp4", "contentType": "video/mp4", "url": "..." },
      { "name": "srt", "text": "1\n00:00:00,000 --> 00:00:02,380\nen la escuela es súper diferente al mundo\n..." },
      { "name": "vtt", "text": "WEBVTT\n\n00:00:00.000 --> 00:00:02.380\n..." }
    ]
  }
}

Burn your own SRT

202
{ "id": "6fd2815f-...", "kind": "burn", "status": "queued", "pollAfterSeconds": 5 }
GET /v1/jobs/6fd2815f-...   (succeeded 17 s after the start)
{
  "id": "6fd2815f-...",
  "kind": "burn",
  "status": "succeeded",
  "audioSeconds": 8,
  "costCents": 1,
  "result": {
    "url": "https://api.awesomevideoeditor.com/v1/jobs/6fd2815f-.../result?...",
    "preset": { "id": "builtin:karaoke", "name": "Karaoke" },
    "files": [
      { "name": "mp4", "contentType": "video/mp4", "url": "..." },
      { "name": "srt", "text": "1\n00:00:00,500 --> 00:00:03,000\nSubtitles from my own SRT file\n..." },
      { "name": "vtt", "text": "WEBVTT\n\n00:00:00.500 --> 00:00:03.000\n..." }
    ]
  }
}

Full schema: OpenAPI. Caption looks with real renders: styles.

From an AI agent (MCP)

Add the server URL to Claude, Cursor, ChatGPT or any MCP client. It connects without a key; the agent creates one with the free create_key tool. Then ask in plain words.

https://api.awesomevideoeditor.com/mcp
“Add subtitles to this video: https://example.com/interview.mp4”
caption_video
“Burn the subtitles from captions.srt into interview.mp4 and give me the file.”
burn_captions (subtitles = the file's text)
“Make Spanish subtitles for this English video and burn them in.”
caption_video with translateTo: es

Setup per client: MCP guides.

The FFmpeg way, for comparison

This burns a file you already have, if your FFmpeg build has libass and the fonts installed. It does not write the subtitles, animate words or keep them clear of app UI, and you run the machine.

ffmpeg -i interview.mp4 -vf "subtitles=captions.srt" -c:a copy captioned.mp4

More on that trade-off: FFmpeg subtitles vs a caption API.

Questions

Can I add subtitles from my own SRT file with the API?
Yes. POST /v1/captions/burn (MCP burn_captions) takes the video (mediaUrl or fileId) and the text of your SRT, WebVTT or JSON cues in subtitles, up to 1.5 MB, and burns them with your timings and wording. It costs 4 credits (about $0.04) per minute of video and nothing is transcribed.
Can the API make the subtitles for me?
Yes. POST /v1/captions (MCP caption_video) transcribes the speech with Whisper, optionally translates it (translateTo), burns styled subtitles and returns the MP4 plus SRT, VTT and JSON in one call. 5 credits per minute (about $0.05), 7 with translation. Language is detected automatically.
Burned-in or a separate subtitle track?
The MP4 has the subtitles burned into the frames, so they show everywhere, including social apps that ignore sidecar files. Every job also returns SRT and VTT, so you can attach those as a selectable track in your own player instead.
How much does it cost?
1 credit = 1 US cent, billed per second with each step rounded up to the next cent: 5 credits per minute to transcribe and burn, 4 to burn an existing file, 1 to transcribe only. The 8-second sample costs 2 credits captioned, 1 burned from an SRT. Failed jobs are refunded. Prices are live at GET /v1/pricing.
What video links and sizes work?
A public https link (direct MP4 or MOV, Google Drive, Dropbox or OneDrive share link) up to 80 MB, or an upload up to 2048 MB and 3 hours (POST /v1/uploads/url, multipart for big files). YouTube, TikTok and Instagram page links are refused with charged: false; download the file and upload it.
Why not run FFmpeg myself?
You can: ffmpeg -i in.mp4 -vf subtitles=captions.srt out.mp4 burns a file if your build has libass and the fonts. It does not write the subtitles, animate words or keep them out of TikTok's UI, and it needs a machine. The API does the transcription, the styled burn and the hosting in one call.
Does it work from an AI agent?
Yes. Connect the MCP server at https://api.awesomevideoeditor.com/mcp (no key needed to connect; the agent can create one with the free create_key tool) and ask in plain words. The agent picks caption_video for a video alone and burn_captions when you give it a subtitle file.

More

Sample clip: “Entrevista Maricarmen Canales - TECMTY” by NachoCHOCO, CC0, via Wikimedia Commons.