OpenClip

Caption Video Tool

caption_video

Destructive

Caption a whole short video (up to 3 minutes) in a caption_preset and get back a captioned MP4. OpenClip transcribes it (the spoken language is detected automatically), times the captions to the words, and renders it with the same renderer as render_clip. This is Quick Captions for agents: use it for a finished short video or a UGC clip.

To use a ChatGPT attachment: select it with create_upload's file parameter and wait for uploaded: true. For other local files, call create_upload and PUT the bytes to its upload_url first. Then pass that video id here. Do NOT call complete_upload (that starts the clip pipeline instead). A Quick Captions video from list_videos works too. Videos from the clip pipeline (submit_video / complete_upload) are captioned per clip with render_clip. Discover preset keys with list_caption_presets.

Metered like the Quick Captions editor: no credits are used; free accounts get 2 captioned videos per month, paid plans are unlimited. Captioning the same video again (a new preset, a retry) does not count again, but once the free month's 2 are used nothing more renders that month.

Processing is ASYNCHRONOUS:

processing: the video is being transcribed and the render starts on its own. Poll get_video_status while downloading, uploaded, or processing. Stop on pending_credits, failed, or download_failed. On completed, poll get_render_status.
rendering: the render is in flight. Poll get_render_status with this video until it reports completed and a rendered_clip URL.
not_dispatched: the renderer is unavailable right now; try again later. Poll every 10-15 seconds for at most 15 minutes, then report the current state. A null rendered_clip URL is normal while rendering; keep polling. After transcription completes, if renders is empty or its entry is not_rendered, call caption_video once more with the same video and preset to finish the original request or surface its exact restriction. Do not repeat this recovery call. If it returns a tool error, read get_render_status once: the queued render may have started meanwhile. Follow rendering or completed within the original deadline; otherwise report that error and stop. Stop on failed, skipped, not_dispatched, or a second empty/not_rendered result. Explain the result and offer a retry. Never re-caption a completed output unless the user requests it. Share only a completed rendered_clip URL.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`video`	Yes	The video id (hashid) from create_upload (no complete_upload needed) or list_videos.
`caption_preset`	Yes	The caption preset key from list_caption_presets (invalid keys are rejected).

Output Schema

TableJSON Schema

Name	Required	Description
`video`	Yes	The video id (hashid). Poll get_video_status / get_render_status with it.
`status`	Yes	`processing`: transcribing, poll get_video_status then get_render_status; `rendering`: poll get_render_status; `not_dispatched`: nothing is in flight, try again later.
`viral_moment`	Yes	The id (hashid) of the whole-video moment being rendered. Null while the video is still processing.

Schema Changelog

Changes observed during successful MCP inspections.

AddedSep 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing metering (2 free per month, paid unlimited), idempotency (re-captioning the same video doesn't recount), the asynchronous state machine (processing/rendering/not_dispatched), polling cadence and deadline, and a bounded recovery call. This is exactly the operational context annotations cannot carry.

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

Conciseness4/5

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

Purpose and routing are front-loaded and the async rules are bulleted, so it is navigable. It is nonetheless very long with some repetition in the polling/recovery instructions, leaving room to tighten.

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?

Given an output schema exists, return values need not be explained; the description instead covers the async lifecycle, error/terminal states, metering, and retry/recovery policy. An agent has everything needed to call it and interpret results correctly.

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 two parameters are already documented; the description mostly restates video/preset sources but adds the non-obvious workflow constraint that create_upload does not require complete_upload first. That workflow nuance is the only genuine added value over the schema.

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

Purpose5/5

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

States a specific verb, resource, and scope: 'Caption a whole short video (up to 3 minutes) in a caption_preset and get back a captioned MP4.' It explicitly distinguishes itself from the sibling render_clip by noting that clip-pipeline videos are captioned per clip, so an agent can tell the two apart without opening either schema.

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?

Gives explicit routing: use it 'for a finished short video or a UGC clip,' source uploads via create_upload (with an explicit 'Do NOT call complete_upload' exclusion), and names render_clip as the alternative for clip-pipeline videos. Both when-to-use and when-not-to-use are spelled out.

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

All OpenClip tools Inspect

Try in Browser

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?