Skip to main content
Glama
Sign In

CaptionPipe

by com.captionpipe
OverviewDiscussionsAdmin

get_caption_job

Read-onlyIdempotent

Poll a known job. If the job ID was lost, use list_caption_jobs to find it. While it runs, retryAfterSeconds says how long to wait before calling again. When status is completed, artifacts holds signed links to the captioned MP4, SRT, VTT, ASS and words.json, valid until expiresAt (24 hours after completion), and chargedSeconds is final. After a render_captions call, render says which version was asked for last and whether it is still rendering, done, or failed; the links always belong to the newest finished version, and preset describes the newest request. When status is failed, error says why and nothing was charged. dictionaryCapacityApplied is the dictionary capacity the speech vendor honoured (1000 on the primary vendor, 0 on the fallback), not a count of terms. Every response includes the caller's balance.

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>"
    },
    "name": "get_caption_job"
  }
}

Input Schema

NameRequiredDescriptionDefault
jobIdYesA job id returned by this API.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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.5/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses real behavior: retryAfterSeconds governs polling, artifact links are signed and expire 24 hours after completion, links always reflect the newest finished render version, failures charge nothing, and dictionaryCapacityApplied is a vendor capacity (1000/0) rather than a term count. These are non-obvious semantics an agent could easily misread.

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

Conciseness3/5

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

It is front-loaded with the core action, but the remainder is one long run-on block enumerating response fields (artifacts, expiresAt, render, preset, error, dictionaryCapacityApplied, balance). Since an output schema exists, much of that enumeration duplicates structured data and hurts scannability.

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 one-parameter polling tool with annotations and an output schema, everything an agent needs is covered: what it does, when to retry, what artifacts appear, when links expire, what failure means, and billing implications.

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% and the single jobId is documented there, so the schema carries the load. The description still adds value by explaining where to obtain the ID when it is missing, which is the only realistic failure mode for this parameter.

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?

Opening sentence 'Poll a known job' states a specific verb and resource, and the description explicitly routes to list_caption_jobs when the ID is lost, distinguishing it from that sibling. An agent can tell this is the single-job status/artifact retrieval endpoint without opening the schema.

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?

It gives a concrete recovery path ('If the job ID was lost, use list_caption_jobs') and a concrete polling cadence rule ('retryAfterSeconds says how long to wait before calling again'). It does not state when not to use it (e.g. that render_captions is what starts a job), but the operational context is clear.

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