Skip to main content
Glama
Sign In

CaptionPipe

by com.captionpipe
OverviewDiscussionsAdmin

render_captions

Burn the same video again from edited words. Send the job's words.json with corrections applied, every word with its startMs and endMs in order (keep confidence if you want it in the new words.json); no speech model runs, what you send is what gets burned. Optionally change the preset or the style; a style sent replaces the job's whole, and none keeps it. Free within the job's allowance (3 on a paid account, 1 on the trial) and within 24 hours of completion. Returns the job at once with render.status accepted; poll get_caption_job until it is completed, when the artifact links switch to the new version. A retry is safe only when it carries the same idempotencyKey and the same body; without a key, each accepted call reserves a re-render from the allowance. Completion spends it; failure returns it. After 3 failed re-renders the job is paused for investigation, with rerenderFailureLimitReached true; do not automatically retry. Re-renders count toward the account's concurrent job limit while they run.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "jobId": "<jobId>",
      "words": "<words>"
    },
    "name": "render_captions"
  }
}

Input Schema

NameRequiredDescriptionDefault
jobIdYesA job id returned by this API.
styleNoOptional. Replaces the job's style as a whole; omit it to keep the job's style unchanged.
wordsYesThe edited words.json: every word with its timing, in order.
presetNoOptional. Defaults to the job's preset.
highlightColorNoOptional. The same as style.highlightColor, kept for existing callers.
idempotencyKeyNoOptional. Any string unique to this request; a retry with the same key returns the same result instead of running twice.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / highlightColor / description
      Previous value: -"Optional, highlight preset only. The spoken word's colour as a hex RGB. Defaults to the job's colour."New value: +"Optional. The same as style.highlightColor, kept for existing callers."
    • 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. Replaces the job's style as a whole; omit it to keep the job's style unchanged.",
+  "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"
+}
    • changedOutput schema / oneOf
      Previous value: -[
-  {
-    "properties": {
-      "artifacts": {
-        "properties": {
-          "ass": {
-            "properties": {
-              "expiresAt": {
-                "type": "string"
-              },
-              "url": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "url",
-              "expiresAt"
-            ],
-            "type": "object"
-          },
-          "mp4": {
-            "properties": {
-              "expiresAt": {
-                "type": "string"
-              },
-              "url": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "url",
-              "expiresAt"
-            ],
-            "type": "object"
-          },
-          "srt": {
-            "properties": {
-              "expiresAt": {
-                "type": "string"
-              },
-              "url": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "url",
-              "expiresAt"
-            ],
-            "type": "object"
-          },
-          "vtt": {
-            "properties": {
-              "expiresAt": {
-                "type": "string"
-              },
-              "url": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "url",
-              "expiresAt"
-            ],
-            "type": "object"
-          },
-          "wordsJson": {
-            "properties": {
-              "expiresAt": {
-                "type": "string"
-              },
-              "url": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "url",
-              "expiresAt"
-            ],
-            "type": "object"
-          }
-        },
-        "required": [
-          "mp4",
-          "srt",
-          "vtt",
-          "ass",
-          "wordsJson"
-        ],
-        "type": "object"
-      },
-      "balance": {
-        "properties": {
-          "paidRemainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "remainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "reservedSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "topUpUrl": {
-            "anyOf": [
-              {
-                "format": "uri",
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "trialRemainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "remainingSeconds",
-          "trialRemainingSeconds",
-          "paidRemainingSeconds",
-          "reservedSeconds",
-          "topUpUrl"
-        ],
-        "type": "object"
-      },
-      "balanceWarning": {
-        "anyOf": [
-          {
-            "properties": {
-              "code": {
-                "const": "low_balance",
-                "type": "string"
-              },
-              "message": {
-                "type": "string"
-              },
-              "topUpUrl": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "code",
-              "message",
-              "topUpUrl"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "chargedSeconds": {
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "dictionaryCapacityApplied": {
-        "anyOf": [
-          {
-            "anyOf": [
-              {
-                "const": 0,
-                "type": "number"
-              },
-              {
-                "const": 1000,
-                "type": "number"
-              }
-            ]
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "durationSeconds": {
-        "anyOf": [
-          {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "error": {
-        "type": "null"
-      },
-      "expiresAt": {
-        "type": "string"
-      },
-      "jobId": {
-        "type": "string"
-      },
-      "preset": {
-        "enum": [
-          "highlight",
-          "clean",
-          "boxed"
-        ],
-        "type": "string"
-      },
-      "render": {
-        "anyOf": [
-          {
-            "properties": {
-              "error": {
-                "anyOf": [
-                  {
-                    "properties": {
-                      "code": {
-                        "enum": [
-                          "unauthenticated",
-                          "job_not_found",
-                          "invalid_source",
-                          "invalid_request",
-                          "upload_incomplete",
-                          "upload_url_expired",
-                          "checksum_mismatch",
-                          "file_size_limit_exceeded",
-                          "invalid_media",
-                          "probe_failed",
-                          "unsupported_ratio",
-                          "unsupported_input",
-                          "duration_limit_exceeded",
-                          "trial_duration_limit_exceeded",
-                          "insufficient_balance",
-                          "trial_concurrency_limit",
-                          "concurrency_limit",
-                          "unsupported_source_url",
-                          "url_fetch_failed",
-                          "rerenders_exhausted",
-                          "rerender_window_expired",
-                          "processing_unavailable"
-                        ],
-                        "type": "string"
-                      },
-                      "details": {
-                        "additionalProperties": {},
-                        "default": {},
-                        "propertyNames": {
-                          "type": "string"
-                        },
-                        "type": "object"
-                      },
-                      "message": {
-                        "type": "string"
-                      },
-                      "retryable": {
-                        "type": "boolean"
-                      }
-                    },
-                    "required": [
-                      "code",
-                      "message",
-                      "retryable"
-                    ],
-                    "type": "object"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "status": {
-                "enum": [
-                  "accepted",
-                  "completed",
-                  "failed"
-                ],
-                "type": "string"
-              },
-              "version": {
-                "maximum": 9007199254740991,
-                "minimum": 2,
-                "type": "integer"
-              }
-            },
-            "required": [
-              "version",
-              "status",
-              "error"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "rerenderFailureLimitReached": {
-        "default": false,
-        "type": "boolean"
-      },
-      "rerendersRemaining": {
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "retryAfterSeconds": {
-        "anyOf": [
-          {
-            "exclusiveMinimum": 0,
-            "maximum": 9007199254740991,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "status": {
-        "const": "completed",
-        "type": "string"
-      }
-    },
-    "required": [
-      "jobId",
-      "preset",
-      "durationSeconds",
-      "retryAfterSeconds",
-      "balance",
-      "balanceWarning",
-      "rerendersRemaining",
-      "dictionaryCapacityApplied",
-      "status",
-      "chargedSeconds",
-      "artifacts",
-      "expiresAt",
-      "error",
-      "render"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "artifacts": {
-        "type": "null"
-      },
-      "balance": {
-        "properties": {
-          "paidRemainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "remainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "reservedSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "topUpUrl": {
-            "anyOf": [
-              {
-                "format": "uri",
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "trialRemainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "remainingSeconds",
-          "trialRemainingSeconds",
-          "paidRemainingSeconds",
-          "reservedSeconds",
-          "topUpUrl"
-        ],
-        "type": "object"
-      },
-      "balanceWarning": {
-        "anyOf": [
-          {
-            "properties": {
-              "code": {
-                "const": "low_balance",
-                "type": "string"
-              },
-              "message": {
-                "type": "string"
-              },
-              "topUpUrl": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "code",
-              "message",
-              "topUpUrl"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "chargedSeconds": {
-        "type": "null"
-      },
-      "dictionaryCapacityApplied": {
-        "anyOf": [
-          {
-            "anyOf": [
-              {
-                "const": 0,
-                "type": "number"
-              },
-              {
-                "const": 1000,
-                "type": "number"
-              }
-            ]
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "durationSeconds": {
-        "anyOf": [
-          {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "error": {
-        "properties": {
-          "code": {
-            "enum": [
-              "unauthenticated",
-              "job_not_found",
-              "invalid_source",
-              "invalid_request",
-              "upload_incomplete",
-              "upload_url_expired",
-              "checksum_mismatch",
-              "file_size_limit_exceeded",
-              "invalid_media",
-              "probe_failed",
-              "unsupported_ratio",
-              "unsupported_input",
-              "duration_limit_exceeded",
-              "trial_duration_limit_exceeded",
-              "insufficient_balance",
-              "trial_concurrency_limit",
-              "concurrency_limit",
-              "unsupported_source_url",
-              "url_fetch_failed",
-              "rerenders_exhausted",
-              "rerender_window_expired",
-              "processing_unavailable"
-            ],
-            "type": "string"
-          },
-          "details": {
-            "additionalProperties": {},
-            "default": {},
-            "propertyNames": {
-              "type": "string"
-            },
-            "type": "object"
-          },
-          "message": {
-            "type": "string"
-          },
-          "retryable": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "code",
-          "message",
-          "retryable"
-        ],
-        "type": "object"
-      },
-      "expiresAt": {
-        "type": "null"
-      },
-      "jobId": {
-        "type": "string"
-      },
-      "preset": {
-        "enum": [
-          "highlight",
-          "clean",
-          "boxed"
-        ],
-        "type": "string"
-      },
-      "rerendersRemaining": {
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "retryAfterSeconds": {
-        "anyOf": [
-          {
-            "exclusiveMinimum": 0,
-            "maximum": 9007199254740991,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "status": {
-        "const": "failed",
-        "type": "string"
-      }
-    },
-    "required": [
-      "jobId",
-      "preset",
-      "durationSeconds",
-      "retryAfterSeconds",
-      "balance",
-      "balanceWarning",
-      "rerendersRemaining",
-      "dictionaryCapacityApplied",
-      "status",
-      "chargedSeconds",
-      "artifacts",
-      "expiresAt",
-      "error"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "artifacts": {
-        "type": "null"
-      },
-      "balance": {
-        "properties": {
-          "paidRemainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "remainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "reservedSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "topUpUrl": {
-            "anyOf": [
-              {
-                "format": "uri",
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "trialRemainingSeconds": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "remainingSeconds",
-          "trialRemainingSeconds",
-          "paidRemainingSeconds",
-          "reservedSeconds",
-          "topUpUrl"
-        ],
-        "type": "object"
-      },
-      "balanceWarning": {
-        "anyOf": [
-          {
-            "properties": {
-              "code": {
-                "const": "low_balance",
-                "type": "string"
-              },
-              "message": {
-                "type": "string"
-              },
-              "topUpUrl": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "code",
-              "message",
-              "topUpUrl"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "chargedSeconds": {
-        "type": "null"
-      },
-      "dictionaryCapacityApplied": {
-        "anyOf": [
-          {
-            "anyOf": [
-              {
-                "const": 0,
-                "type": "number"
-              },
-              {
-                "const": 1000,
-                "type": "number"
-              }
-            ]
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "durationSeconds": {
-        "anyOf": [
-          {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "error": {
-        "type": "null"
-      },
-      "expiresAt": {
-        "type": "null"
-      },
-      "jobId": {
-        "type": "string"
-      },
-      "preset": {
-        "enum": [
-          "highlight",
-          "clean",
-          "boxed"
-        ],
-        "type": "string"
-      },
-      "rerendersRemaining": {
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "retryAfterSeconds": {
-        "anyOf": [
-          {
-            "exclusiveMinimum": 0,
-            "maximum": 9007199254740991,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "status": {
-        "enum": [
-          "upload_pending",
-          "probing",
-          "reserved",
-          "processing"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "jobId",
-      "preset",
-      "durationSeconds",
-      "retryAfterSeconds",
-      "balance",
-      "balanceWarning",
-      "rerendersRemaining",
-      "dictionaryCapacityApplied",
-      "status",
-      "chargedSeconds",
-      "artifacts",
-      "expiresAt",
-      "error"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "artifacts": {
+        "properties": {
+          "ass": {
+            "properties": {
+              "expiresAt": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "url",
+              "expiresAt"
+            ],
+            "type": "object"
+          },
+          "mp4": {
+            "properties": {
+              "expiresAt": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "url",
+              "expiresAt"
+            ],
+            "type": "object"
+          },
+          "srt": {
+            "properties": {
+              "expiresAt": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "url",
+              "expiresAt"
+            ],
+            "type": "object"
+          },
+          "vtt": {
+            "properties": {
+              "expiresAt": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "url",
+              "expiresAt"
+            ],
+            "type": "object"
+          },
+          "wordsJson": {
+            "properties": {
+              "expiresAt": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "url",
+              "expiresAt"
+            ],
+            "type": "object"
+          }
+        },
+        "required": [
+          "mp4",
+          "srt",
+          "vtt",
+          "ass",
+          "wordsJson"
+        ],
+        "type": "object"
+      },
+      "balance": {
+        "properties": {
+          "paidRemainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "remainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "reservedSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "topUpUrl": {
+            "anyOf": [
+              {
+                "format": "uri",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "trialRemainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "remainingSeconds",
+          "trialRemainingSeconds",
+          "paidRemainingSeconds",
+          "reservedSeconds",
+          "topUpUrl"
+        ],
+        "type": "object"
+      },
+      "balanceWarning": {
+        "anyOf": [
+          {
+            "properties": {
+              "code": {
+                "const": "low_balance",
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "topUpUrl": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "code",
+              "message",
+              "topUpUrl"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "chargedSeconds": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "dictionaryCapacityApplied": {
+        "anyOf": [
+          {
+            "anyOf": [
+              {
+                "const": 0,
+                "type": "number"
+              },
+              {
+                "const": 1000,
+                "type": "number"
+              }
+            ]
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "durationSeconds": {
+        "anyOf": [
+          {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "error": {
+        "type": "null"
+      },
+      "expiresAt": {
+        "type": "string"
+      },
+      "jobId": {
+        "type": "string"
+      },
+      "preset": {
+        "enum": [
+          "highlight",
+          "clean",
+          "boxed",
+          "karaoke",
+          "word",
+          "punch",
+          "wordbox",
+          "reveal",
+          "glow"
+        ],
+        "type": "string"
+      },
+      "render": {
+        "anyOf": [
+          {
+            "properties": {
+              "error": {
+                "anyOf": [
+                  {
+                    "properties": {
+                      "code": {
+                        "enum": [
+                          "unauthenticated",
+                          "job_not_found",
+                          "invalid_source",
+                          "invalid_request",
+                          "upload_incomplete",
+                          "upload_url_expired",
+                          "checksum_mismatch",
+                          "file_size_limit_exceeded",
+                          "invalid_media",
+                          "probe_failed",
+                          "unsupported_ratio",
+                          "unsupported_input",
+                          "duration_limit_exceeded",
+                          "trial_duration_limit_exceeded",
+                          "insufficient_balance",
+                          "trial_concurrency_limit",
+                          "concurrency_limit",
+                          "unsupported_source_url",
+                          "url_fetch_failed",
+                          "rerenders_exhausted",
+                          "rerender_window_expired",
+                          "processing_unavailable"
+                        ],
+                        "type": "string"
+                      },
+                      "details": {
+                        "additionalProperties": {},
+                        "default": {},
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "type": "object"
+                      },
+                      "message": {
+                        "type": "string"
+                      },
+                      "retryable": {
+                        "type": "boolean"
+                      }
+                    },
+                    "required": [
+                      "code",
+                      "message",
+                      "retryable"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "status": {
+                "enum": [
+                  "accepted",
+                  "completed",
+                  "failed"
+                ],
+                "type": "string"
+              },
+              "version": {
+                "maximum": 9007199254740991,
+                "minimum": 2,
+                "type": "integer"
+              }
+            },
+            "required": [
+              "version",
+              "status",
+              "error"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "rerenderFailureLimitReached": {
+        "default": false,
+        "type": "boolean"
+      },
+      "rerendersRemaining": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "retryAfterSeconds": {
+        "anyOf": [
+          {
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "status": {
+        "const": "completed",
+        "type": "string"
+      },
+      "style": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "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"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "jobId",
+      "preset",
+      "style",
+      "durationSeconds",
+      "retryAfterSeconds",
+      "balance",
+      "balanceWarning",
+      "rerendersRemaining",
+      "dictionaryCapacityApplied",
+      "status",
+      "chargedSeconds",
+      "artifacts",
+      "expiresAt",
+      "error",
+      "render"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "artifacts": {
+        "type": "null"
+      },
+      "balance": {
+        "properties": {
+          "paidRemainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "remainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "reservedSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "topUpUrl": {
+            "anyOf": [
+              {
+                "format": "uri",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "trialRemainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "remainingSeconds",
+          "trialRemainingSeconds",
+          "paidRemainingSeconds",
+          "reservedSeconds",
+          "topUpUrl"
+        ],
+        "type": "object"
+      },
+      "balanceWarning": {
+        "anyOf": [
+          {
+            "properties": {
+              "code": {
+                "const": "low_balance",
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "topUpUrl": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "code",
+              "message",
+              "topUpUrl"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "chargedSeconds": {
+        "type": "null"
+      },
+      "dictionaryCapacityApplied": {
+        "anyOf": [
+          {
+            "anyOf": [
+              {
+                "const": 0,
+                "type": "number"
+              },
+              {
+                "const": 1000,
+                "type": "number"
+              }
+            ]
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "durationSeconds": {
+        "anyOf": [
+          {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "error": {
+        "properties": {
+          "code": {
+            "enum": [
+              "unauthenticated",
+              "job_not_found",
+              "invalid_source",
+              "invalid_request",
+              "upload_incomplete",
+              "upload_url_expired",
+              "checksum_mismatch",
+              "file_size_limit_exceeded",
+              "invalid_media",
+              "probe_failed",
+              "unsupported_ratio",
+              "unsupported_input",
+              "duration_limit_exceeded",
+              "trial_duration_limit_exceeded",
+              "insufficient_balance",
+              "trial_concurrency_limit",
+              "concurrency_limit",
+              "unsupported_source_url",
+              "url_fetch_failed",
+              "rerenders_exhausted",
+              "rerender_window_expired",
+              "processing_unavailable"
+            ],
+            "type": "string"
+          },
+          "details": {
+            "additionalProperties": {},
+            "default": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "message": {
+            "type": "string"
+          },
+          "retryable": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "retryable"
+        ],
+        "type": "object"
+      },
+      "expiresAt": {
+        "type": "null"
+      },
+      "jobId": {
+        "type": "string"
+      },
+      "preset": {
+        "enum": [
+          "highlight",
+          "clean",
+          "boxed",
+          "karaoke",
+          "word",
+          "punch",
+          "wordbox",
+          "reveal",
+          "glow"
+        ],
+        "type": "string"
+      },
+      "rerendersRemaining": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "retryAfterSeconds": {
+        "anyOf": [
+          {
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "status": {
+        "const": "failed",
+        "type": "string"
+      },
+      "style": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "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"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "jobId",
+      "preset",
+      "style",
+      "durationSeconds",
+      "retryAfterSeconds",
+      "balance",
+      "balanceWarning",
+      "rerendersRemaining",
+      "dictionaryCapacityApplied",
+      "status",
+      "chargedSeconds",
+      "artifacts",
+      "expiresAt",
+      "error"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "artifacts": {
+        "type": "null"
+      },
+      "balance": {
+        "properties": {
+          "paidRemainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "remainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "reservedSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "topUpUrl": {
+            "anyOf": [
+              {
+                "format": "uri",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "trialRemainingSeconds": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "remainingSeconds",
+          "trialRemainingSeconds",
+          "paidRemainingSeconds",
+          "reservedSeconds",
+          "topUpUrl"
+        ],
+        "type": "object"
+      },
+      "balanceWarning": {
+        "anyOf": [
+          {
+            "properties": {
+              "code": {
+                "const": "low_balance",
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "topUpUrl": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "code",
+              "message",
+              "topUpUrl"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "chargedSeconds": {
+        "type": "null"
+      },
+      "dictionaryCapacityApplied": {
+        "anyOf": [
+          {
+            "anyOf": [
+              {
+                "const": 0,
+                "type": "number"
+              },
+              {
+                "const": 1000,
+                "type": "number"
+              }
+            ]
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "durationSeconds": {
+        "anyOf": [
+          {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "error": {
+        "type": "null"
+      },
+      "expiresAt": {
+        "type": "null"
+      },
+      "jobId": {
+        "type": "string"
+      },
+      "preset": {
+        "enum": [
+          "highlight",
+          "clean",
+          "boxed",
+          "karaoke",
+          "word",
+          "punch",
+          "wordbox",
+          "reveal",
+          "glow"
+        ],
+        "type": "string"
+      },
+      "rerendersRemaining": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "retryAfterSeconds": {
+        "anyOf": [
+          {
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "status": {
+        "enum": [
+          "upload_pending",
+          "probing",
+          "reserved",
+          "processing"
+        ],
+        "type": "string"
+      },
+      "style": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "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"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "jobId",
+      "preset",
+      "style",
+      "durationSeconds",
+      "retryAfterSeconds",
+      "balance",
+      "balanceWarning",
+      "rerendersRemaining",
+      "dictionaryCapacityApplied",
+      "status",
+      "chargedSeconds",
+      "artifacts",
+      "expiresAt",
+      "error"
+    ],
+    "type": "object"
+  }
+]
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

The description adds substantial behavior beyond the annotations: allowance consumption and return on failure, immediate accepted status, artifact link switching, concurrent job accounting, and pause-after-three-failures behavior. These details are consistent with the annotations, including conditional idempotency rather than unconditional idempotency.

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 purpose is front-loaded, followed by operational constraints in a logical sequence. Despite its length, the density is warranted by the complexity, and each sentence carries relevant usage or safety information.

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 mutation tool with a rich schema, annotations, and an output schema, the description covers the critical invocation, polling, allowance, failure, and retry context. Nothing essential for correct use is missing.

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 100%, so the schema already defines the parameters thoroughly. The description still adds useful semantic context: words must be ordered with timing, confidence may be kept, style replaces the whole job style when sent, and preset defaults to the existing job preset.

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?

The description states a specific action and resource: 'Burn the same video again from edited words.' It clarifies that no speech model runs and that the supplied words are exactly what gets burned, distinguishing this from caption_video and get_caption_job.

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 clear when-to-use guidance: send the edited words.json, optionally change preset or style, and poll get_caption_job until completion. It also states explicit when-not and safety conditions, including the allowance window, idempotency retry rule, and do-not-retry behavior after three failures.

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

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