Submit a long video for clipping, either by public link in url (YouTube, Twitch, Kick, Vimeo, Zoom, Google Drive, Dropbox, Loom, LinkedIn, Facebook, Rumble, Dailymotion, Medal.tv, or a direct https link to a video file; Google Drive and Dropbox links must be shared publicly) or, for a local file, by upload_id after katto_upload_video and the PUT of the file. Pass exactly one of url or upload_id. Consumes 1 video from your monthly quota — check katto_get_usage first. Clips are produced asynchronously; returns a job id, then poll katto_get_job every 30-60 s until status is 'completed', or pass webhook_url to be notified (url jobs only). Pass idempotency_key when you might retry a url job, so a retry never spends a second video (an upload can only be started once anyway). Fails if the URL is unsupported, the uploaded file is missing, or the video is longer than your plan allows.

Read-only. Get the status, progress and clips of a job by id. Clips come ranked by virality score (0-100, highest first; ties broken by clip_index). Each clip is { url, captions_url, title, score, clip_index, hd }: when status is 'completed' every url is a finished, downloadable clip; hd is true once the 1080p high-quality render is ready. hd=false does NOT mean broken — the url already works, the 1080p is just still rendering in the background (and stays the standard render on the free plan). The job-level hd_ready flag turns true once every clip is hd, i.e. the URLs are final and won't be swapped again (status='completed' fires earlier). Returns 404 for an unknown id.

Read-only. List your recent jobs, newest first. Paginate with 'cursor' (pass the previous next_cursor); optional 'status' filter. Returns { jobs: [{id, status, source, created_at, completed_at}], next_cursor }.

Read-only convenience: the clips of a job as { url, captions_url, title, score, clip_index, hd }, ranked by score (highest first). hd=true means the 1080p render is ready; hd=false means the url is the standard render (HD still finishing, or the free plan). Empty until the first clip is ready.

Read-only. Your current plan and monthly video quota: { plan, videos_used, videos_limit, videos_remaining }. Call before katto_create_clip_job to confirm remaining quota.

Read-only. The transcript of a completed job as timestamped segments [{ start, end, text }]. Returns 404 while the job is still processing.

Cancel a still-running job (queued/processing) and refund the video back to your monthly quota. Safe to retry (idempotent). Returns an error if the job already finished, failed, or was cancelled.

Read-only. The account behind this key: plan, this key's scopes (read/write), and monthly quota { videos_used, videos_limit, videos_remaining }.

Read-only. The link sources Katto can clip from (YouTube, Twitch, Kick, Vimeo, Zoom, Google Drive, Dropbox, Loom, LinkedIn, Facebook, Rumble, Dailymotion, Medal.tv, or a direct https link to a video file), each with an example URL. Use it to confirm a URL is supported before calling katto_create_clip_job; for a local file use katto_upload_video instead.

Read-only. The valid values for the optional config.clipLength on katto_create_clip_job (target clip-duration buckets). Note: clipLength is fixed at creation and cannot be changed by re-render.

Read-only. The valid caption_style preset names for katto_rerender_clip (id + label), e.g. 'hormozi' for bold word-by-word highlight. Call this before re-rendering so you pass a real preset instead of guessing.

Re-render one already-finished clip with a new reframe layout and/or caption style (get valid caption_style values from katto_list_caption_styles). Free — does NOT use video quota. Each call starts a new render (not idempotent); the original clip is kept. Returns a rerender_id; poll katto_get_rerender for the new clip url.

Re-render one finished clip dubbed into one or more of 19 languages (en, es, fr, it, pt, hi, ja, zh, de, ko, nl, pl, ru, tr, id, vi, th, uk, ar). Creator feature (requires an active subscription); does NOT use your monthly video quota. Each call starts a new render (not idempotent). Returns a rerender_id; poll katto_get_rerender for the result.

Read-only. Poll a re-render started by katto_rerender_clip or katto_dub_clip. Returns { status, clip_url, captions_url, dub_urls } — dub_urls is { lang: url } and is where a DUB lands (clip_url stays the undubbed re-render), null otherwise — clip_url is null until status is 'completed'.

Read-only. Your saved brand kits (colors, caption font and position, default layout, watermark url).

Read-only. Returns your webhook signing SECRET — treat it as a credential (do not display or log it) — plus how to verify Katto's signed completion callbacks (HMAC-SHA256 of {timestamp}.{body}). Pass webhook_url on a job to receive them.

Create a NEW clip from any time range of a completed job's source video, when the user wants a moment Katto did not pick. start_seconds/end_seconds are SOURCE-video seconds (take them from katto_get_transcript segments); the clip must last 3-180 s. Does NOT use video quota. Limits: at most 10 created clips per video, one clip in preparation at a time (409 'Another clip is being prepared' = wait and retry), and only within 7 days of the job (410 after that: the source is no longer kept). Captions come from the words Katto already timed; has_captions=false means that range had none and the clip renders without captions. Not idempotent: each call queues another clip. Returns expected_clip_index; poll katto_get_clips every 15-30 s until a clip with that clip_index appears.

Render more clips from a job's reserve: moments Katto scored but did not render, best first. Use when the user wants more clips from the same video. Does NOT use video quota. count is 1-10 (default 5), capped by what is left. Returns { status: 'queued'|'pending'|'empty', requested, remaining }: 'pending' means a request is already running (do not call again), 'empty' means the reserve is used up. New clips are appended to the job; poll katto_get_clips.

Step 1 of clipping a LOCAL file (when the user has a file, not a public link). Pass the exact filename, MIME type and size in bytes; the size is checked against the plan's upload limit and the monthly quota is checked (not yet spent). Returns { upload_id, upload_url, headers, expires_in, next_steps }. Then: (2) HTTP PUT the raw file bytes to upload_url with exactly the returned Content-Type header (e.g. curl -X PUT -H 'Content-Type: video/mp4' --upload-file ./file.mp4 '<upload_url>'), before expires_in seconds; (3) call katto_create_clip_job with upload_id: that verifies the file arrived, spends 1 video of quota and starts clipping; (4) poll katto_get_job with id = upload_id. You need a tool that can make an HTTP PUT with a file body (shell, code execution); if you have none, give the user the upload_url and the curl command.

Translate one finished clip's burned-in captions into one of 19 languages and re-render it with them; word timings are kept and the original clip is preserved. Only the captions change: for a translated VOICE use katto_dub_clip. Creator feature (requires an active Creator subscription; otherwise an error with code upgrade_required and a pricing link to give the user). Does NOT use video quota. Not idempotent: each call starts a new render. Returns a rerender_id; poll katto_get_rerender until status is 'completed' for the new clip_url.

Change a clip's title. Without 'title', Katto's AI writes a new scroll-stopping title in the clip's language (optional style: energetic, descriptive, fun, shocking); each AI regeneration uses one unit of the plan's monthly title-regeneration allowance (an error with 'limit' when it is used up). With 'title', that exact text is saved and nothing is spent. Synchronous: returns { title, clip_index, regenerated }. Does NOT use video quota.

Publish a finished clip to one of the user's connected social accounts (YouTube, TikTok, LinkedIn, Instagram, Bluesky, Mastodon, Threads), now or at schedule_at (future, at most 7 days ahead). Call katto_list_connected_accounts first to see which platforms are connected (and not in need of a reconnect); katto_generate_post_text can draft the caption. This posts PUBLICLY on the user's behalf and cannot be undone from Katto: before calling, show the user the clip, the platform, the caption (and TikTok privacy level) and get their explicit confirmation; never publish on your own initiative or retry a publish blindly (each call is a new post). Requires a paid plan; scheduling requires Creator. If the platform is not connected you get an error with code platform_not_connected and a connect_url: ask the user to connect it in the Katto dashboard, then retry. TikTok requires privacy_level chosen by the user (no default) and disclosure of commercial content (brand_content / brand_organic); until Katto's TikTok app is audited, TikTok only accepts posts to a private account. Returns { status: 'published', result } or { status: 'scheduled', scheduled_post_id, scheduled_at }.

Read-only. Which of the 7 publishable platforms (youtube, tiktok, linkedin, instagram, bluesky, mastodon, threads) the user has connected in the Katto dashboard: { connections: [{ platform, connected, display_name, reconnect_required, connected_at }], connect_url }. Call it BEFORE katto_publish_clip to pick a platform that will work: if the one the user wants shows connected=false or reconnect_required=true, ask them to (re)connect it at connect_url instead of attempting the publish. Never returns tokens.

Read-only. The user's scheduled social posts (from katto_publish_clip with schedule_at, or the dashboard calendar), newest first: { scheduled_posts: [{ id, job_id, clip_index, platform, scheduled_at, status, title, error, posted_at, created_at }], next_cursor }. status: pending = waiting for its time, posting = being published, posted = done, failed = see error. Paginate with cursor = the previous next_cursor; optional status filter.

Cancel a scheduled post before it goes out: it is removed from the calendar and will not be published (same as deleting it in the dashboard calendar). Only pending or failed posts can be cancelled; one already posting or posted returns an error (a published post cannot be taken down from Katto). Confirm with the user which post (platform, clip, time) before cancelling. Safe to retry: a second call returns 'not found'. Returns { id, status: 'cancelled', previous_status }.

Write publish-ready post text for one clip with AI, tailored to each platform's tone and character limits, in the clip's language: { clip_index, posts: { [platform]: { title, description, hashtags } } }. title is only filled for YouTube (for the other platforms the caption is description, hashtags included). Omit platform to get all seven at once. Nothing is posted or saved and no video quota is used: show the text to the user, then pass it to katto_publish_clip (caption, or title/description for YouTube). Each call is a new AI generation (identical requests within an hour return the cached text).

Trim or extend one finished clip by moving its start and/or end, then re-render it. Offsets are in seconds, relative to the clip's ORIGINAL bounds (two calls do not add up): positive extends (start earlier / end later), negative trims. The result must last 3-180 s and stay inside the source video. Extending re-cuts from the source, which Katto keeps 7 days: after that only trimming works (410). Captions for an extended part come from words Katto already timed or the transcript sentence. Does NOT use video quota; the original clip is kept. Not idempotent: each call starts a new render. Returns { rerender_id, status_url, start_seconds, end_seconds, duration_seconds, extended }; poll katto_get_rerender for the new clip_url.

Add a hook, big bold text over the first seconds that stops the scroll, to one finished clip and re-render it. Pass text to use your own (max 80 characters, 3-7 words reads best) or omit it and Katto's AI writes one from the clip in its language. position: top (default) or center; duration: 1-10 s (default 4). Styled like the editor's AI Hook (white, boxed, pop-in). Does NOT use video quota; the original clip is kept. Not idempotent: each call starts a new render, and a re-render starts from the original clip, so calling it again replaces the hook rather than stacking two. Returns { rerender_id, hook_text, generated, status_url }; poll katto_get_rerender for the new clip_url.

Record the user's verdict on a clip: rating good or bad, with an optional reason in their words. Same signal as the thumbs up/down on the Katto results page; it is used to improve which moments Katto picks. Only rate when the user expressed an opinion, never on your own. Rating again records the new verdict (the latest one counts). Returns { ok, clip_index, rating }.