Video Clipping API for Developers: Contracts, Keys and the Job Model

Point a clipping API at a two-hour VOD and short vertical files come back with captions already baked into the pixels. That is the pitch. The engineering questions underneath it are narrower and more useful: what exactly does a call return, what do you have to persist, and what happens in the gap between submitting a video and having something worth publishing?

ClipSpeedAI answers those through an MCP server rather than a table of REST routes. One endpoint — https://api.clipspeed.ai/mcp, spoken over streamable HTTP — authenticated either by OAuth, for clients that can redirect a user through a browser, or by an Authorization: Bearer header carrying an API key, for CLIs and server code. Ten tools sit behind that single URL, covering recorded video, live streams, caption styling, discovery and one publishing action. An npm package also exists.

This page is written for whoever has to make that work in production. It covers the shape of the data coming back, the key lifecycle including revocation, a curl session that tells you the truth about your credentials, a schema-first Node client, the job state machine you will end up building, and the places the integration bites. ClipSpeedAI shows up as one approach among three — build the pipeline, buy a REST job queue, or connect an agent — with its limits stated. If the protocol itself is unfamiliar, What Is MCP? Model Context Protocol Explained is the prerequisite.

Start from what comes back, not from the render chain

Explanations of clipping usually walk forward through the pipeline: fetch the source, transcribe it, propose segments, score them, reframe to vertical, draw captions, encode. That order is useful for judging whether a vendor's output is any good. It is close to useless for writing code, because none of those stages appear in your integration. Your code is shaped entirely by the far end of the chain — the object check_clips hands back.

Each finished clip comes with a title, a viral score and a download URL, and the file itself is a 9:16 vertical render with captions burned in. Four design consequences fall directly out of that one sentence, and between them they account for most of the decisions you will make.

• The score is a sort key and nothing more. It exists so a caller can take the top few instead of reviewing forty. Read real values off real responses before you write any comparison against it — do not assume a range, a maximum, or a pass mark, because none is documented and a hard-coded threshold written against a guess will silently discard everything or nothing.
• Captions are pixels, not metadata. Burned-in text survives re-upload to any platform, which is the point, but it also means style is an input decision made before the render, never an edit made after. That is why the caption template id matters more than it looks — see the section on template ids below.
• Treat the download URL as something to copy, not something to embed forever. If clips are part of your product, fetch each file and put it in your own storage keyed by your own id. Hot-linking someone else's URL indefinitely makes your product's durability a function of their retention policy, which you do not control and should not assume.
• The title is a first draft. If titling matters for the surface you publish to, creator_pack exists to give you alternates per clip along with hooks and suggested posting times, and it is keyed by the same projectId.

Pipeline knowledge still earns its keep, just in a different place: evaluation. When you compare any two clipping products, the differences that matter are whether clip boundaries land on sentence edges instead of mid-word, whether the vertical crop follows a speaker who moves rather than sitting in a static centre crop, and whether caption timing tracks the actual speech. Those are watchable in about five minutes on your own footage. Feature lists are not.

The ten tools, in roughly the order you meet them

Here are the real tool names and what each is for. Argument names are deliberately absent from this table: call tools/list against the endpoint and read each tool's inputSchema, which is the contract, rather than trusting names copied out of any article including this one.

Two things about the shape of this surface are worth reading deliberately, because they tell you how the authors expect it to be used.

First, submitting and collecting are separate calls, joined by a projectId. That split is not an oversight. A rendering job takes real time, and neither an HTTP client nor an agent can sit blocked for the length of a render — so the work is handed back as a handle, and the handle is the thing your integration is actually built around. MCP Tool Design: Writing Tools an Agent Can Actually Use goes into why long jobs have to be exposed this way to be usable at all.

Second, the live tools form an explicit lifecycle — start, check, extend, stop — with a subscriptionId as the through-line, rather than reusing the recorded path with a flag. That is the correct call: a recording has a known end and a stream does not, and pretending otherwise would push the difference into your error handling instead of into the API.

Keys: format, what the server keeps, and how revocation works

For anything running without a browser — a cron job, a worker, a CLI session — you authenticate with an API key in an Authorization: Bearer header. The key lifecycle is small enough to describe completely, which is worth doing because it determines how you rotate credentials.

Keys are created either in the app under Account → API & Integrations → Generate API Key, or directly with POST /auth/api-keys. The value you get looks like this:

csai_live_<48 hexadecimal characters>

# e.g. the prefix csai_live_ followed by 48 hex chars,
# which is 24 random bytes rendered as hex.

That full value is shown once, at creation, and cannot be retrieved afterwards. Only the prefix is stored for display — the first 18 characters plus an ellipsis — which is enough to tell two keys apart in a list and not enough to use one. Losing the value means creating a new key, not recovering the old one, so capture it into your secret manager at the moment of creation rather than intending to come back for it.

GET /auth/api-keys lists what exists. The response carries, per key: id, name, key_prefix, plan, rate_limit, requests_today, total_requests, last_request_at, is_active and created_at. Those last few fields are more useful than they first appear. A per-key request counter plus a last-used timestamp is a working attribution tool: give every environment and every service its own named key and you can answer "which of my deployments is generating this traffic" from the list endpoint alone, without adding any telemetry of your own. It also makes dead keys obvious — a key with a stale last_request_at is a key nothing is using, and an unused credential is one you can retire.

DELETE /auth/api-keys/:id revokes. Revocation is real: it flips is_active to false and stamps revoked_at. Because a key can be genuinely killed, safe rotation is the ordinary three-step — create the replacement, deploy it everywhere and confirm traffic has moved to the new key's counters, then delete the old one. Doing it in that order means no window where anything is authenticating with a credential you have already given up on.

Each key also carries its own rate_limit. That is the detail most integrations discover late, and it has a direct consequence for the polling loop described further down: a client that hammers check_clips in a tight loop spends its per-key budget on repeated "not ready" answers. Back off, and the budget goes to work that matters.

Storage hygiene is the usual, with one wrinkle specific to this protocol. Several MCP clients keep server configuration in a plain JSON file, sometimes inside the repository you are working in, so check what your client writes to disk before you commit anything after adding a server. Keep the key in an environment variable or a secret manager, and use different keys for laptops and deployed services so revoking one never takes the other down. Because the server is hosted rather than a process on your machine, that key is a network credential — Remote MCP vs Local MCP Servers covers why that distinction changes the threat model.

Getting connected in one command

With a key in hand, adding the server from a terminal is a single command. This is the canonical install from the product's own documentation:

claude mcp add --transport http clipspeed https://api.clipspeed.ai/mcp \
  --header "Authorization: Bearer <API_KEY>"

After that the ten tools appear in the session and can be driven in plain language — "clip this VOD and give me the five best" is a complete instruction, and the model picks the tools. ClipSpeedAI MCP for Claude Code: Complete Setup Guide covers verification and the failure cases in full.

Graphical clients mostly differ in where the credential lives rather than in what they talk to. Claude on claude.ai connects through a one-click OAuth custom connector, so no key is ever pasted anywhere; that flow is written up in ClipSpeedAI MCP for Claude (claude.ai): Complete Setup Guide. Claude Desktop stores server config locally. For every other client, the shape is the same — register ClipSpeedAI as an HTTP MCP server pointed at the endpoint above, with your key in the Authorization header — but the file it goes in, the field names and the menu path are that vendor's business and change with their releases, so follow the client's own MCP documentation for the exact syntax rather than a snippet from here. If you are deciding which editor to drive this from at all, Claude Code vs Cursor for MCP Workflows compares the two head to head.

What "supported" means, client by client

Support is tiered, and the tiers mean different things.

Verified end to end. Claude on claude.ai, Claude Code, Claude Desktop and Windsurf. These have been driven through the full flow. Windsurf's setup is documented in ClipSpeedAI MCP for Windsurf: Complete Setup Guide.

Compatible, verification in progress. Cursor, Codex, OpenClaw and Hermes. They speak the same streamable HTTP MCP with the same Bearer header, so the integration should work by construction — but it has not been confirmed end to end by ClipSpeedAI, and "should work by construction" is a weaker statement than "we ran it". Cursor users have ClipSpeedAI MCP for Cursor: Complete Setup Guide as a starting point. There is a corresponding write-up for the Codex CLI, and separate ones again for OpenClaw and for the Hermes agent, each following its own client's configuration conventions.

Rolling out, vendor-gated. ChatGPT, where availability depends on OpenAI's own MCP connector rollout rather than on anything in ClipSpeedAI. ClipSpeedAI MCP for ChatGPT: Complete Setup Guide tracks the current state.

One endpoint serves all of them, and in principle any other client that speaks streamable HTTP MCP — though the tiers above are what has actually been verified, and an unverified client is a thing to pilot rather than a thing to build a launch on. If you need certainty this week, pick from the first tier.

Reading the wire with curl

Before writing client code, look at the actual protocol. MCP over HTTP is JSON-RPC 2.0 in a POST body, so curl is enough to confirm that your key works and your network path is clear.

A spec-compliant session opens with an initialize request, followed by a notifications/initialized notification, and the server may hand back a session id header that later requests are expected to echo. So start there, with -i so you can see the response headers:

curl -isS https://api.clipspeed.ai/mcp \
  -H "Authorization: Bearer $CLIPSPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"<SPEC_REVISION>",
                 "capabilities":{},
                 "clientInfo":{"name":"curl","version":"0"}}}'

Substitute the spec revision string your client library targets for <SPEC_REVISION>. Having to look that up by hand is itself a hint that curl is an inspection tool here, not an integration strategy — an SDK fills that field in for you. If the response carries a session id header, echo it on the next call:

curl -sS https://api.clipspeed.ai/mcp \
  -H "Authorization: Bearer $CLIPSPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <id from the initialize response, if one was returned>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Note the Accept header on both calls. Streamable HTTP servers may answer with server-sent events rather than a single JSON body, and a client that accepts only application/json can be turned away for that reason alone — which produces a confusing failure that has nothing to do with your credentials.

Three outcomes are worth distinguishing. A 401 means the key is missing, malformed or revoked. A tool list means credentials and network path are both good, and every remaining problem lives in your client code. A JSON-RPC error mentioning session or initialization means the server wants the full handshake — at which point stop fighting it in a shell and move to an SDK client, which is what the handshake exists for. How MCP Servers Work: Architecture and Request Flow walks the whole exchange if you want the frame-by-frame version.

The tools/list response is also the answer to "what arguments does this tool take". Every tool ships an inputSchema, and that schema — not documentation, not an example — is the contract.

A Node client that reads schemas instead of guessing

The official TypeScript SDK deals with the initialize exchange, session ids and SSE framing so you do not have to. Connect with the streamable HTTP transport and pass the Authorization header through the transport's request options:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://api.clipspeed.ai/mcp'),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.CLIPSPEED_API_KEY}` } } }
);

const client = new Client({ name: 'my-clipper', version: '1.0.0' });
await client.connect(transport);

// The schemas are the contract. Print them once, build against them.
const { tools } = await client.listTools();
for (const t of tools) {
  console.log(t.name, JSON.stringify(t.inputSchema, null, 2));
}

const submitted = await client.callTool({
  name: 'submit_to_clipspeed',
  arguments: { /* fill in from submit_to_clipspeed.inputSchema */ }
});
console.log(submitted.content);

Two caveats attach to this snippet. It is written against the TypeScript SDK's streamable-HTTP client as it stands at the time of writing; import paths and transport option shapes have moved between SDK releases, so pin a version in your package.json and check that release's README if anything here does not resolve. And the official Python SDK follows the same connect-then-list-tools shape, though its API surface is its own — read its documentation rather than transliterating the lines above.

The listTools() loop is the actual lesson. Print the schemas once, build your argument objects from what you see, and you get two things: correctness today, and resilience when the server adds an optional field later. Guessing argument names from prose is how integrations break on a Tuesday for no visible reason.

The job state machine you are going to build anyway

Nobody renders video synchronously. Transcription, scoring, reframing and encoding all cost time proportional to source length, so submitting and collecting are separate acts, joined by a projectId. Rather than a polling loop bolted onto a request handler, model it as states you persist — that framing survives restarts, and a restart is exactly when naive polling loses work.

• requested — you have a source URL and your own request id, written to your database before you call anything. If the process dies here you know a submit may or may not have happened, and you can reconcile.
• submitted — the call returned and you have the projectId. Write it immediately. The render continues server-side whether or not your process is alive; losing the projectId means losing access to work that is still running and still being paid for.
• polling — check_clips on an increasing interval. "Not ready" is a normal state, not an exception. The single most common bug in this class of integration is a client that turns in-progress into a thrown error, catches it up the stack, and retries the submit — producing duplicate projects, duplicate spend and eventually duplicate posts.
• ready — clips in hand. Copy the files to your own storage, record the score and title alongside your own ids, and stop polling.
• failed — a terminal condition on the source, distinct from a transient network error on the check. The next section separates those.

Make submission idempotent on your side by keying your records on source URL plus your own request id. The server has no way to know that your retry is a retry and not a second genuine request for the same video, so that guarantee has to live in your code. And back off between checks, both because nothing useful changes in the first moments and because polling spends the per-key rate limit described earlier.

When an agent is driving rather than your own code, this same split is what makes the workflow possible: the model calls submit, tells the user it is running, and calls check later in the conversation or on a schedule. AI Agent Video Automation: End-to-End Workflows shows that loop wired up end to end.

Caption style is an id you pass in, not a thing you fix later

Because captions are rendered into the pixels, the styling decision happens before the render. There is no post-hoc restyle — a different look means a different render. That makes list_templates more load-bearing than a cosmetic endpoint usually is.

The template ids are exactly these six:

karaoke
hormozi
beasty
fire
youshaei
cinematic

Whichever you choose goes back in as captionStyle. Two practical notes follow from that. First, pin one id per publishing surface and store it in your own configuration rather than letting each call pick — consistency across episodes is most of what makes a clip feed look like a channel instead of a pile of files. Second, when you evaluate output quality, hold the template constant. Comparing a karaoke render against a cinematic one tells you which style you prefer, not which boundaries or crops are better, and those are the things actually worth measuring.

Call list_templates at least once from your own account rather than hard-coding the six ids forever: it is the authoritative list, and a list that can gain entries is one you want to read rather than assume.

Live sessions: the subscriptionId is the integration

A recording has a known end. A stream does not, and that single difference is why clip_livestream gets its own lifecycle rather than a flag on the recorded path.

You open a session against a live stream and get back a subscriptionId. That id is the entire handle: check_livestream polls it, extend_livestream extends it, stop_livestream ends it. Persist it the same way you persist a projectId, and for the same reason.

A status of monitoring means the stream is still live and still being clipped — a healthy steady state, not a pending one, and your code should treat it as such rather than as something to wait out. Clips appear as moments happen, so the integration wants to be event-shaped: check periodically, take whatever is ready, keep going. You cannot ask for "the best moment of the stream" up front, because the best moment may not have happened yet. That inverts the mental model people bring from recorded video, where ranking the whole set at the end is the natural move.

extend_livestream exists because a session is opened for a bounded duration. Read extend_livestream.inputSchema from tools/list for what the actual bounds and arguments are, and extend while the session is still active rather than assuming a finished one can be revived. When you are done, stop_livestream ends the session and the clips already produced are kept and stay downloadable — stopping is not discarding, which means there is no reason to leave a session running over a stream that has already ended. Livestream Clipping API: Clip While You Stream goes deeper into the session mechanics.

publish_to_youtube is the one door that opens outward

Nine of the ten tools do things inside your own account. One does not. publish_to_youtube takes a projectId, optionally a clipId, a title and a privacyStatus, and puts a video on a public platform under someone's name.

Its default is private, which is the right default and worth preserving. Public requires you to ask for it explicitly through privacyStatus — so in an automated path, the failure mode of forgetting an argument is an unlisted upload rather than a bad clip on a real channel. Do not paper over that by wiring a public value in as a constant somewhere central.

The structural point matters more than the argument. A key handed to an agent grants every tool that key can reach, and an autonomous loop with this tool in range can publish without anyone reading the output first. Put a human confirmation in front of it, publish one clip at a time rather than in a batch, and keep publishing credentials on a separate key from the one your ingest worker uses — the counters on that key then tell you exactly how many outward actions have ever been taken, which is a number worth being able to check. The general principle here — that the risky tools in any server are the ones with effects outside your own account, and they deserve different handling from the read-only ones — is the subject of MCP Security: Scopes, Keys and Safe Tool Design.

Failures that stop the loop versus failures that mean "later"

Video pipelines fail in a small number of recognisable ways. Classify them once, in one place, and the integration becomes dull in the good sense.

• Source unreachable or geo-restricted. The URL opens in your browser and not from a server. Terminal — fail fast and put the source URL in the error message, because this one is diagnosed by looking at the link and nothing else.
• No speech on the source. A pipeline built on a transcript has little to work with on a silent or music-only video. Expect few clips or none. That is an outcome, not a crash, and code that treats an empty result set as an exception will retry forever against a video that will never produce anything.
• Very long sources. Duration drives both time and cost. Decide deliberately whether a four-hour VOD goes in whole or in segments, rather than discovering the answer through a bill.
• Transient network error on a check. Retry the check. Never retry the submit — that is the path to duplicate projects.
• Rate limit reached on the key. Each key carries its own limit and its own daily counter, both visible from the list endpoint. Reaching it means backing off, not re-submitting, and it is usually a symptom of a poll interval that is too tight.
• Stream went offline before your session ended. Stop the session; do not extend it. There is nothing left to clip, and the clips already made survive the stop.

The single distinction to encode is between errors that should stop the loop and states that only mean come back later. Collapsing those two into one category is how integrations end up with duplicate jobs, doubled spend and, if a publishing tool is in reach, double-posted clips.

Three ways to get clips, and the case for each

These are genuinely different products rather than better and worse versions of the same one, so pick on shape rather than on features.

Build it. ffmpeg, a speech-to-text model, your own segmentation, your own scoring, your own face and speaker tracking. Right when clipping is the product rather than a feature, when you need control over every stage, or when volume makes per-clip pricing uneconomic. Be honest about where the time goes: boundary selection and subject-tracked reframing are the hard parts, and neither is a weekend. Everything else on that list is plumbing you can assemble in days.

Buy a hosted REST job queue. You POST a URL, you get a job id, you receive a webhook or you poll. Right when clipping sits inside a deterministic system you own — a CMS ingest step, a nightly batch, a queue worker — and when you need exact retry semantics and first-class webhooks. Judge candidates on the pipeline stages described at the top of this page and on their own published terms, not on anyone's comparison table.

Connect an agent over MCP. You describe the goal and the model picks the tools. Right when the caller is an AI client, when the workflow is exploratory rather than fixed, and when one integration needs to work across several surfaces without you writing a client for each. Wrong when you need strict determinism, because the model decides what to call and in what order. MCP vs REST API: When to Use Each sets out that trade-off properly, and MCP vs Function Calling: What Actually Differs explains why the protocol is not just tool-calling with a new name.

ClipSpeedAI is in the third category. If what you want is a plain job queue with webhooks and idempotency keys as first-class features, an MCP endpoint is not the natural fit and you will be building that layer yourself around the polling model. If your caller is an agent, it is a natural fit. Best MCP Servers for Video and Content Workflows surveys what else lives in that category.

What it costs to integrate against

Worth knowing before you write code, because two of these facts affect your test strategy rather than your budget.

The plan ladder tops out at Ultra, $49/mo. Pro sits at $29/mo and Starter at $15/mo, and committing annually halves whichever you pick. Access begins with a one-time $1 charge that opens a three-day trial — the dollar is taken today, and the plan you selected starts billing after the third day unless you cancel before then. There is no free plan. There is a free demo: one demo, on a video shorter than 30 minutes.

Three consequences for an engineering team:

• No free tier means no zero-cost CI. An automated test that hits the live endpoint on every commit has a running cost. Budget for it, or mock the transport in CI and keep a single scheduled test against the real endpoint.
• One demo, capped at 30 minutes, is an evaluation tool. It is enough to judge boundaries, crop and caption quality on your own footage, which is the decision it exists to support. It is not enough to load-test or to profile behaviour on long sources.
• Webhooks and idempotency are your layer. The model here is submit-and-check. If your architecture assumes push notification and server-side deduplication, that gap is yours to close, and the state machine above is what closing it looks like.

A full build: weekly episode in, five reviewed clips out

Concrete case. A creator ships a two-hour episode every week and wants five clips per episode, reviewed by a human before anything is public. Here is the whole thing, in order, with the state machine wired in.

1. Pick the source. Either your own list of episode URLs, or discover_trending when the job is to ride something recent — remembering that it looks at roughly the last three weeks, which makes it a timeliness tool rather than an archive search.
2. Choose the caption style once. Read list_templates, pick an id, store it in config. It goes in as captionStyle on every submit so the feed stays visually consistent week to week.
3. Write the request row, then submit. Source URL plus your own request id first, then submit_to_clipspeed, then persist the projectId the moment it comes back.
4. Poll with backoff. check_clips on the projectId. In-progress is a normal state. Transient errors retry the check and never the submit.
5. Copy and rank. Pull each download URL into your own storage. Sort by viral score, take the top five, and remember that the score is a ranking signal — you are using it to order candidates, not to decide anything on its own.
6. Enrich, optionally. creator_pack on the same projectId gives suggested titles, hooks and posting times per clip, which is the difference between five files and five posts ready to schedule.
7. Human review. Put the five in front of a person. This is the gate that makes the rest of the automation safe.
8. Publish, one at a time. Only after approval, publish_to_youtube with an explicit clipId and title. Leave the private default alone unless the human said public.

The live variant swaps steps three and four: clip_livestream against the stream, persist the subscriptionId, poll check_livestream — where "monitoring" means it is working — extend_livestream while the session is still active if the stream runs long, and stop_livestream at the end, which keeps everything already produced.

None of the above requires writing code, incidentally. The same sequence runs conversationally from any connected client, which is the case MCP for Creators: Automating Video Without Code is about. Writing the code buys you determinism, retries you control and a database row for every clip — which is worth it when the workflow runs weekly forever, and overkill when it runs twice. For a wider look at what else can be assembled from tools like these, MCP for Video Editing and Clipping Workflows is the broader survey.

Frequently asked questions

Is ClipSpeedAI a REST API or an MCP server?

An MCP server, at https://api.clipspeed.ai/mcp over streamable HTTP. You call it with JSON-RPC through an MCP client or SDK rather than through conventional REST routes. If your caller is an AI agent or an MCP-capable editor, that shape helps. If you specifically want a POST-and-webhook job queue, it is a different shape from what you may be expecting, and you will be building the webhook and idempotency layer yourself around a submit-and-check model.

Do I need a separate integration for each editor?

No — it is one endpoint and one Bearer-key pattern, and only the config syntax differs per client. But support is tiered. Claude Code, Claude Desktop, Windsurf and Claude on claude.ai are verified end to end. Cursor, Codex, OpenClaw and Hermes use the same pattern but have not been verified end to end by ClipSpeedAI. Claude on claude.ai uses a one-click OAuth connector instead of a key. ChatGPT depends on OpenAI's own MCP connector rollout and is not yet verified.

What does a ClipSpeedAI API key look like, and can I get it back later?

Keys start with csai_live_ followed by 48 hexadecimal characters. The full value is shown once, at creation, and cannot be retrieved afterwards — the server stores only the prefix for display in your key list. Copy it into a secret manager at the moment you generate it. If you lose it, create a new key rather than trying to recover the old one.

If a key leaks, can I actually revoke it?

Yes. DELETE /auth/api-keys/:id revokes the key: it sets is_active to false and stamps revoked_at. Because revocation is real, rotate in the safe order — create the replacement, deploy it and confirm traffic has moved to the new key's request counters, then delete the old one. GET /auth/api-keys shows per-key rate_limit, requests_today, total_requests and last_request_at, which is enough to confirm the switch happened before you pull the trigger.

How do I find the exact arguments each tool takes?

Call tools/list against the endpoint. Every tool ships an inputSchema, and that schema is the contract — more reliable than argument names copied from documentation or from an article, and resilient when the server adds optional fields later. In a Node client, listTools() gives you the same thing at runtime; print it once and build your argument objects from what you see.

What caption styles are available and how do I pick one?

list_templates returns the caption-style templates. The ids are karaoke, hormozi, beasty, fire, youshaei and cinematic, and you pass the one you want back in as captionStyle. Choose before the render, not after: captions are burned into the pixels, so changing style means rendering again. Pin one id per publishing surface so a feed looks consistent across episodes.

How long does a clipping job take?

It depends on the source — transcription, scoring, reframing and encoding all scale with duration. That is why the API is asynchronous: submit_to_clipspeed hands back a handle and check_clips fetches results against the projectId when they are ready. Persist the projectId immediately, poll on an increasing interval, and treat in-progress as a normal state rather than an error.

Will publishing put a clip on a public channel by accident?

publish_to_youtube defaults to private. Public requires you to set privacyStatus explicitly, so a forgotten argument produces an unlisted upload rather than a live post. Keep that default, put a human confirmation in front of the tool, publish one clip at a time, and consider giving publishing its own API key so the per-key request counter tells you exactly how many outward actions have ever been taken.

Is there a free tier for testing?

There is no free plan. There is a single free demo on a video under 30 minutes, which is enough to judge boundary, crop and caption quality on your own footage but not enough to load-test. Beyond that, a one-time $1 charge opens a three-day trial that converts to your chosen plan unless you cancel; Ultra is $49/mo, Pro $29/mo and Starter $15/mo, with annual billing halving those. If you want CI hitting the live endpoint on every commit, that has a running cost — mock the transport in CI and keep one scheduled test against the real server.

Related reading