AwesomeVideo

Burn captions

burn_captions

Idempotent

Burn captions into video with native ffmpeg and an ASS script generated from an AwesomeVideo preset. This is the paid server path and costs more per audio minute than transcription. The container uses a fast x264 preset, scales to a moderate resolution, copies the original audio, and scales to zero after the job. Pass subtitles (SRT, VTT, or JSON) or a transcription job id, plus a preset id or name. A key that cannot pay gets 402 insufficient_balance with requiredCents and howToBuy. For a render that costs AwesomeVideo nothing, call prepare_client_burn instead and burn in the browser or a future WebMCP client. Pass platform (tiktok, instagram_reels, youtube_shorts, youtube, ...) when the user names where the video goes, e.g. "subtítulos para TikTok" → platform=tiktok: captions move inside that app's safe zone (style unchanged, same price) and the result includes safe_zone {platform, margins}, plus a warning if the video shape does not match (e.g. 16:9 for TikTok; use shorts to crop to 9:16).

Input Schema

Name	Required	Description
`fileId`	No
`preset`	No	Preset id or name, or custom:cp_... for your own saved preset. Use presetId or presetName too.
`autoFit`	No	Default true: caption size, words per caption (4 on 9:16, 5 on 1:1, 7 on 16:9), and a default safe zone follow the video shape, so text reads the same at 720p and 1080p and stays clear of app UI. Pass false only when the user wants the preset's exact fixed pixel sizes. Same price.
`combined`	No	Also return SRT, VTT, and transcript JSON. Same burn price.
`mediaUrl`	No
`platform`	No	Where the video will be posted: tiktok, instagram_reels, youtube_shorts, facebook_reels, snapchat_spotlight, linkedin, youtube, x (aliases like reels, instagram, shorts, snap, twitter; case-insensitive). Keeps captions out of that app's buttons and text. If the user says "para TikTok" / "for Reels", pass it; if they did not say and it matters, ask. Same price. Unknown values return 422 invalid_platform before any charge. See list_platforms.
`presetId`	No
`faceAvoid`	No	true = move captions off faces (samples faces at 2 fps, same price; result.faceAvoid.faceLayout). Shortcut for styleOverrides.faceAvoid.
`subtitles`	No	SRT, VTT, or JSON cues.
`maxCredits`	No
`presetName`	No
`webhookUrl`	No
`audioVisual`	No	Audio-only input (mp3/m4a/wav...): render the web editor's audio export (visualizer + captions) on the server, same price as the burn. On a video input it returns 422 audio_visual_needs_audio_input (not charged). Omit it on audio to get the default bars.
`notifyEmail`	No
`brandPresetId`	No	Saved font, color, position, and optional logo.
`highlightColor`	No	#RRGGBB for highlightWords. Default #FACC15.
`highlightWords`	No	Shortcut: words or phrases to color in every caption (accent/case-insensitive), e.g. ["AwesomeVideo", "gratis"]. Maps to styleOverrides.wordHighlights rule {id:"custom", words, color}. Same price.
`styleOverrides`	No	Per-call style changes deep-merged onto the preset (same fields as list_presets style; null removes a field), validated with the renderer schema and bundled fonts. Example {"fontSize":72,"maxWordsPerCaption":2,"wordEntrance":"bounce"}. Same price. No need to save_custom_preset. Every field with examples: get_style_reference.
`durationSeconds`	No
`transcriptionJobId`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 31, 2026

addedInput schema / properties / audioVisual

Added value: +{
+  "additionalProperties": {},
+  "description": "Audio-only input (mp3/m4a/wav...): render the web editor's audio export (visualizer + captions) on the server, same price as the burn. On a video input it returns 422 audio_visual_needs_audio_input (not charged). Omit it on audio to get the default bars.",
+  "properties": {
+    "aspect": {
+      "description": "Frame shape; default from platform, else 9:16.",
+      "enum": [
+        "9:16",
+        "16:9",
+        "1:1",
+        "4:5"
+      ],
+      "type": "string"
+    },
+    "background": {
+      "description": "Frame background color #RRGGBB (gradient/blur via config).",
+      "type": "string"
+    },
+    "config": {
+      "additionalProperties": {},
+      "description": "Variant config fields (colors, gradient, blur, bar count, position...). Same names and defaults as list_audio_visuals.",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "enabled": {
+      "description": "false: background + captions, no visualizer.",
+      "type": "boolean"
+    },
+    "height": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "overlays": {
+      "description": "Up to 8 image (imageUrl, PNG/JPEG/WebP <=5 MB) or text items {kind, x, y, width, height, start, end, ...} in frame pixels.",
+      "items": {
+        "additionalProperties": {},
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "maxItems": 8,
+      "type": "array"
+    },
+    "presetId": {
+      "description": "bars only: minimal | neon | bold | spotify.",
+      "type": "string"
+    },
+    "variant": {
+      "description": "Visualizer (default bars). list_audio_visuals shows each one's defaults.",
+      "enum": [
+        "bars",
+        "ribbon",
+        "rings",
+        "spectrogram",
+        "skyline",
+        "silkline",
+        "ivory",
+        "halo",
+        "needle",
+        "mono"
+      ],
+      "type": "string"
+    },
+    "width": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "type": "object"
+}

First observedOct 31, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: discloses paid pricing relative to transcription, x264 preset/resolution/audio-copy/scale-to-zero container behavior, the 402 insufficient_balance payload shape (requiredCents, howToBuy), 422 codes for invalid_platform and audio_visual_needs_audio_input, and that safe-zone/platform/autoFit/combined add no cost. Annotations only cover readOnly/idempotent, so this adds substantial undisclosed behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and cost, then error contract, then the alternative tool, then platform logic — a sensible order. The platform sentence is long and carries a bilingual example and a warning aside, which is slightly heavy against the value it delivers.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter render tool with no output schema, it covers billing, errors, safe-zone output shape, and the client-side alternative. The main gap is never stating that one of fileId/mediaUrl (or an upload id) is required despite 'required: 0', leaving the agent to guess the valid input combinations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 55%, and the description compensates by explaining the input-substitution rule (subtitles SRT/VTT/JSON or transcriptionJobId, plus preset id or name) and the semantic effect of platform. Still, key parameters (fileId, mediaUrl, maxCredits, presetId vs presetName precedence) are never explained in either place.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Burn captions into video') and explains the mechanism (native ffmpeg + ASS script from an AwesomeVideo preset), which distinguishes it from prepare_client_burn and caption_video. An agent can immediately tell this is the server-side paid render path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes to prepare_client_burn when cost matters ('For a render that costs AwesomeVideo nothing') and gives a clear rule for platform ('pass it when the user names where the video goes ... if they did not say and it matters, ask'). It does not contrast with sibling caption_video or transcribe, so not quite a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AwesomeVideo tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?