CaptionPipe

caption_video

Start captioning one video. Pass exactly one source: inputUrl, a direct https link to a video file (platform pages such as YouTube or TikTok are refused), or jobId from create_upload after the bytes are uploaded. Choose a preset: highlight, clean, boxed, karaoke, word, punch, wordbox, reveal or glow (each is described on the preset field). Optionally send a style to adjust the look: text size, position, padding, words per caption, sentence breaks, capitals, colours or a pop-in. Optionally send a dictionary of names to spell right and a language. Returns a jobId in status probing; poll it with get_caption_job. If the response is lost, replay with the original idempotencyKey and payload or use list_caption_jobs to find recent jobs. The balance is charged by the whole second once the duration is known, and nothing is charged if the job fails.

Input Schema

Name	Required	Description
`jobId`	No	The jobId from create_upload, after the bytes have been uploaded.
`style`	No	Optional adjustments over the preset's look. Omit for the preset as designed.
`preset`	Yes	Caption look. highlight: the spoken word takes the accent. clean: white with an outline. boxed: a plate behind the line. karaoke: a colour sweep fills each word as it is spoken. word: one large word at a time, centred. punch: heavy capitals, thick outline and shadow, a few words at a time, the spoken word in yellow. wordbox: the spoken word on a coloured box. reveal: the line builds word by word as it is spoken. glow: a coloured halo around the text.
`inputUrl`	No	A direct https link to a video file. Platform pages such as YouTube or TikTok are refused.
`language`	No	"auto" to detect, or a BCP-47 language tag such as "en" or "pt-BR".
`dictionary`	No	Optional. Up to 1000 names or terms, each at most 6 words, spelled the way they should appear. Used for this job only.
`highlightColor`	No	Optional. The same as style.highlightColor, kept for existing callers.
`idempotencyKey`	No	Optional. Any string unique to this request; a retry with the same key returns the same result instead of running twice.

Output Schema

Name	Required	Description	Default
`jobId`	Yes
`status`	Yes
`balance`	Yes
`balanceWarning`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 24, 2026

changedInput schema / properties / highlightColor / description

Previous value: -"Optional, highlight preset only. The spoken word's colour as a hex RGB such as #FFE500. Defaults to the CaptionPipe accent."New value: +"Optional. The same as style.highlightColor, kept for existing callers."

changedInput schema / properties / preset / description

Previous value: -"Caption style. highlight, clean or boxed."New value: +"Caption look. highlight: the spoken word takes the accent. clean: white with an outline. boxed: a plate behind the line. karaoke: a colour sweep fills each word as it is spoken. word: one large word at a time, centred. punch: heavy capitals, thick outline and shadow, a few words at a time, the spoken word in yellow. wordbox: the spoken word on a coloured box. reveal: the line builds word by word as it is spoken. glow: a coloured halo around the text."

changedInput schema / properties / preset / enum

Previous value: -[
-  "highlight",
-  "clean",
-  "boxed"
-]New value: +[
+  "highlight",
+  "clean",
+  "boxed",
+  "karaoke",
+  "word",
+  "punch",
+  "wordbox",
+  "reveal",
+  "glow"
+]

addedInput schema / properties / style

Added value: +{
+  "additionalProperties": false,
+  "description": "Optional adjustments over the preset's look. Omit for the preset as designed.",
+  "properties": {
+    "animation": {
+      "description": "How each caption arrives: none (the default), or pop (scales in with a small overshoot).",
+      "enum": [
+        "none",
+        "pop"
+      ],
+      "type": "string"
+    },
+    "boxColor": {
+      "description": "The plate colour on boxed, default black. wordbox's box marks the spoken word, so highlightColor sets it.",
+      "pattern": "^#?[0-9a-fA-F]{6}$",
+      "type": "string"
+    },
+    "boxPadding": {
+      "description": "Box padding as a percent of the text size, 5 to 60, on boxed (default 22) and wordbox (default 18).",
+      "maximum": 60,
+      "minimum": 5,
+      "type": "integer"
+    },
+    "breakOnSentence": {
+      "description": "Start a new caption after every . ! ? or …, so no caption spans two sentences. Default off.",
+      "type": "boolean"
+    },
+    "fontSize": {
+      "description": "Text size as a percent of the preset's own size, 50 to 200, default 100. Above 100 it is a maximum: a word too wide for the frame is shrunk to fit. Bigger text puts fewer words on each caption.",
+      "maximum": 200,
+      "minimum": 50,
+      "type": "integer"
+    },
+    "highlightColor": {
+      "description": "The spoken word's colour as a hex RGB such as #FFE500: its text on highlight and punch, the sweep on karaoke, its box on wordbox. Defaults to the CaptionPipe accent (yellow on punch).",
+      "pattern": "^#?[0-9a-fA-F]{6}$",
+      "type": "string"
+    },
+    "maxWords": {
+      "description": "At most this many words on screen at once, 1 to 12. Default unlimited (a character budget applies), 1 on word, 3 on punch.",
+      "maximum": 12,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "offsetY": {
+      "description": "Distance from the bottom or top edge, as a percent of the frame height, 0 to 45. Default 22 on a portrait video, 12 on 16:9. Ignored when position is middle.",
+      "maximum": 45,
+      "minimum": 0,
+      "type": "number"
+    },
+    "outlineColor": {
+      "description": "The outline colour as a hex RGB, or the halo's on glow. Default black, violet on glow. Ignored by boxed, whose plate replaces the outline.",
+      "pattern": "^#?[0-9a-fA-F]{6}$",
+      "type": "string"
+    },
+    "paddingX": {
+      "description": "Space kept clear at each side, as a percent of the frame width, 0 to 20. Default 9 on a portrait video (clear of TikTok's side icons), 6 on 16:9.",
+      "maximum": 20,
+      "minimum": 0,
+      "type": "number"
+    },
+    "position": {
+      "description": "Where captions sit: bottom, middle or top. Default middle on word, bottom on every other preset.",
+      "enum": [
+        "bottom",
+        "middle",
+        "top"
+      ],
+      "type": "string"
+    },
+    "textColor": {
+      "description": "The text colour as a hex RGB. Default white.",
+      "pattern": "^#?[0-9a-fA-F]{6}$",
+      "type": "string"
+    },
+    "uppercase": {
+      "description": "Burn the captions in capitals. Default off, on for punch. The SRT, VTT and words.json keep normal case.",
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}

First observedSep 13, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the annotations, the description discloses important behavior: the operation is asynchronous, returns a jobId in probing status, must be polled, charges the balance by whole second once duration is known, and charges nothing on failure. It also explains retry behavior with idempotencyKey. These details materially help an agent manage the job lifecycle.

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

Conciseness5/5

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

The description is dense but well front-loaded: it starts with the core action and source requirement, then covers presets, optional style, return handling, retry behavior, and billing. Every sentence contributes operational context with no filler.

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?

For a complex job-starting tool with an output schema and rich annotations, the description is complete enough to call it correctly. It covers input selection, job lifecycle, polling, idempotent replay, and billing, while leaving return-value structure to the output schema.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description adds a useful high-level summary of source rules, presets, style categories, dictionary, and language, but does not meaningfully extend parameter semantics beyond what the structured schema already provides.

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

Purpose4/5

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

The description states a specific verb and resource: starting captioning for one video, with source, preset, and style inputs. It distinguishes the tool from create_upload, get_caption_job, and list_caption_jobs by explaining the upload-to-job flow and polling path, but it does not mention the sibling render_captions, so the distinction from that tool is left implicit.

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?

It gives explicit instructions on exactly one source: a direct https video file URL or a jobId from create_upload. It names platform pages that are refused, tells the caller to choose a preset, says when to poll with get_caption_job, and provides recovery guidance using idempotencyKey or list_caption_jobs.

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

All CaptionPipe 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?