AwesomeVideo

Caption video (one call)

caption_video

Idempotent

PREFER THIS for 'add/burn subtitles to this video'. One call runs transcribe -> optional translate -> burn and returns the finished MP4 link plus SRT, VTT, JSON transcript, and credits charged. Source: sourceUrl (public https link: direct file, chat attachment URL, Google Drive or Dropbox share link; YouTube is refused) or fileId (from create_upload / import_url / upload_base64). Price is exactly the sum of the steps, no surcharge: transcribe 1 + burn 4 credits per audio minute (+2 with translateTo); 1 credit = 1 cent; call quote with operation caption first if unsure. Over-limit input (2048 MB fileId, 80 MB sourceUrl, 3 h) fails with 422 limit_exceeded and charged:false; failed jobs refund automatically. wait (default true) blocks up to waitSeconds (default 45, max 50) and returns the finished result; if it is still running you get status queued/running, the job id, step, progress (0-100), eta_seconds and pollAfterSeconds: poll get_job after pollAfterSeconds, or pass webhookUrl / notifyEmail. If it fails after transcribing, resume_job reuses the transcript and charges only the rest. Use platform (tiktok, instagram_reels, youtube_shorts, youtube, ...; see list_platforms) so captions stay clear of the app UI. Person wants to check the text first? Pass review:true: it transcribes now and returns reviewUrl; the burn is charged only on approval. To fix the text yourself, use transcribe -> edit_transcript -> burn_captions.

Input Schema

Name	Required	Description
`wait`	No	Block until done, up to waitSeconds. Default true.
`fileId`	No	Id from create_upload, import_url, or upload_base64.
`preset`	No	Caption style preset id or name (list_presets), or your own saved preset as custom:cp_... (save_custom_preset). Default Clarity.
`review`	No	Human review first: transcribes now, returns reviewUrl for the person; the burn runs and is charged only when they approve. Not with translateTo.
`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.
`glossary`	No	Names and brand terms to spell correctly, e.g. ['AwesomeVideo'].
`language`	No	Spoken language (BCP-47, e.g. es, en). Omit for auto-detect.
`platform`	No	Target platform: tiktok, instagram_reels, youtube_shorts, youtube, ... (aliases reels, shorts). Keeps captions clear of the app UI. Same price.
`faceAvoid`	No	true = move captions off faces (samples faces at 2 fps, same price; result.faceAvoid.faceLayout). Shortcut for styleOverrides.faceAvoid.
`sourceUrl`	No	Public link to the video/audio. Direct https file, chat attachment URL, Google Drive or Dropbox share link. Not YouTube.
`maxCredits`	No	Refuse the job if it would cost more than this many credits.
`webhookUrl`	No	Public https URL, POSTed a signed JSON body when the job finishes.
`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	Email when the job finishes. Free.
`translateTo`	No	Burn subtitles translated to this language (ISO 639-1, e.g. en). Adds 2 credits/min.
`waitSeconds`	No	Default 45, max 50.
`instructions`	No	review only: note shown to the reviewer.
`brandPresetId`	No	Saved brand preset (font, colors, position, 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.
`idempotencyKey`	No	Same key returns the same job instead of charging twice.
`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

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.8/5.0

Behavior5/5

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

Annotations only declare the safety profile (openWorld, idempotent, non-destructive), and the description adds substantial context beyond them: exact credit pricing per step, over-limit thresholds and the 422 limit_exceeded/charged:false behavior, automatic refunds, wait/waitSeconds blocking semantics with progress/eta/pollAfterSeconds, and the review:true approval flow that defers the burn charge. This is far more than the annotations convey.

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 the 'PREFER THIS' routing and the one-call pipeline before pricing and edge cases, which is the right order. It is long, but for a 23-parameter job tool nearly every sentence carries operational information; a few pricing/limit clauses could be compressed.

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

Completeness5/5

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

Covers what an agent needs for a complex async job tool with no output schema: return artifacts, credit cost, size/duration limits, failure and refund behavior, polling contract with pollAfterSeconds, and the human-review variant. Nothing material is left to inference.

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 96%, so the baseline is 3; the description still adds value by tying cost to parameters (translateTo +2 credits/min, faceAvoid and highlightWords same price), clarifying sourceUrl vs fileId sources, and noting review cannot combine with translateTo. It does not add much beyond the already-rich schema for the nested audioVisual/styleOverrides objects.

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 ('add/burn subtitles to this video') and names the exact pipeline it runs (transcribe -> optional translate -> burn) plus what it returns (MP4, SRT, VTT, JSON, credits). It also distinguishes itself from siblings by saying 'PREFER THIS' and naming burn_captions/transcribe/edit_transcript as the manual path.

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

Usage Guidelines5/5

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

Explicit routing: prefer this one-call tool for subtitle requests, use transcribe -> edit_transcript -> burn_captions when the user wants to fix text, use quote first if unsure of cost, poll get_job or pass webhookUrl/notifyEmail if the wait times out, and resume_job if it fails after transcribing. When-not conditions (YouTube refused, audio_visual on video input) are also stated.

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?