Takesly

Takesly API

Clip, caption and publish from your own tools.

Introduction

Takesly API

Turn long videos into short clips with captions, and schedule the results to social platforms. The API mirrors the dashboard, including credit quotes, duplicate protection and signed downloads.

  • Create an API key in Dashboard → API.
  • Include it as a Bearer token on every request.
  • The REST API is included with every paid plan.
  • Each request is scoped to the workspace that owns the key.

Quickstart

Clip your first video

bash
curl -X POST https://www.takesly.com/api/v1/clip \
  -H "Authorization: Bearer pb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=...",
    "aspect_ratio": "9:16",
    "caption_style": "hormozi",
    "caption_color": "#39E508"
  }'

A successful request returns 202 plus a job_id and a locked credit quote. Poll the job every 30–60 seconds.

bash
curl https://www.takesly.com/api/v1/clip/JOB_ID \
  -H "Authorization: Bearer pb_sk_..."

When status is complete, each clip contains a signed download_url, an inline preview_url, and a thumbnail_url.

Response format

What a job looks like

json
{
  "job_id": "b6f2f2c0-...",
  "status": "complete",
  "mode": "clipping",
  "progress": 100,
  "clips_ready": 5,
  "clips_total": 5,
  "source_title": "How I grew to 100k subscribers",
  "aspect_ratio": "9:16",
  "caption_style": "hormozi",
  "ai_credits_used": 10,
  "clips": [{
    "clip_id": "c81...",
    "title": "The one habit that changed everything",
    "duration": 42.6,
    "download_url": "https://.../download/1?download_token=...",
    "preview_url": "https://.../download/1?download_token=...&inline=1",
    "thumbnail_url": "https://.../thumbnail/1?download_token=..."
  }],
  "download_endpoint": "/api/v1/clip/b6f2.../download/all"
}

Download URLs are signed, expire after about one hour, and are bound to a single clip. Preview URLs never count as a download. A complete download streams the whole file before it is counted.

Errors

Error codes

Every error uses the same envelope with a stable error code and a human-readable message.

CodeHTTPMeaning
invalid_api_key401The key is missing, malformed, or revoked.
subscription_required403An active paid plan is required.
insufficient_credits402Not enough credits; response includes the needed amount.
video_too_short / video_too_long400Clipping accepts 5 minutes to 3 hours; captions up to 20 minutes.
video_unavailable400Private, removed, members-only, or unsupported source.
source_temporarily_blocked503Upstream download source is rate limiting us.
rate_limit429Too many requests or concurrent jobs.
cannot_cancel409A post has already started publishing.
not_found404The job, clip, post or automation is not in this workspace.

Rate limits: 5 clipping requests per minute, 3 concurrent clipping jobs, and 20 failed clipping requests per hour. Auth failures are limited to 10 per minute per key prefix.

Clipping

Endpoints

MethodPathPurpose
GET/statusCredits and plan
GET/usageDetailed usage
GET/usage/historyCredit transaction history
POST/clipStart a clipping job
GET/clip/:job_idJob status and clips
GET/clip/:job_id/download/allSigned links for all clips
GET/clip/:job_id/download/:indexDownload one clip
GET/clip/:job_id/thumbnail/:indexClip thumbnail

Request body

  • video_url — required. YouTube, Twitch, Kick, Vimeo, or a direct MP4 URL.
  • aspect_ratio — 9:16 (default), 1:1, 16:9.
  • caption_style — default hormozi. See the caption styles below.
  • caption_color — #RRGGBB, default #39E508.

Duplicates

Submitting the same URL + aspect ratio + caption style while a job is active (or after a recent success) returns the existing job with duplicate: true. No extra credits are charged.

Partial results

Some source sections can fail independently. The job can return complete with fewer clips than the expected total. The locked quote is not reduced.

Captions

Caption any video

bash
curl -X POST https://www.takesly.com/api/v1/caption \
  -H "Authorization: Bearer pb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=...",
    "caption_style": "highlighted",
    "caption_color": "#FFE94A"
  }'

Captions are burned in, the video dimensions are preserved, and the source length must be 20 minutes or less. The job returns mode: "captions" and one clip covering the full source.

Automations

Watch a channel

Automations watch a YouTube channel, clip each new eligible upload, and schedule the clips to connected destinations.

  • GET /automations/destinations — accounts available to receive clips.
  • POST /automations — channel URL, destinations, ratio, captions, 1–5 posting times.
  • GET /automations / GET /automations/:id — list and details with recent runs.
  • PATCH /automations/:id — update settings.
  • POST /automations/:id/pause|resume and DELETE /automations/:id.

Plan limits: Creator 1 automation, Pro 5. New uploads are checked against your credit balance and the per-day budget; if credits run out the automation pauses automatically.

Scheduling

Schedule to 5 platforms

json
POST /api/v1/schedule
{
  "posts": [{
    "platform": "tiktok",
    "caption": "Three seconds is all you get.",
    "scheduled_at": "2026-11-20T15:00:00Z",
    "media_url": "https://www.takesly.com/api/v1/clip/JOB/download/1?download_token=...",
    "platform_settings": { "privacy": "public" }
  }]
}

Up to 25 posts per request. Media is required for Instagram and TikTok. Posts can only be cancelled while their status is scheduled; otherwise the API returns 409 cannot_cancel.

Credits

How billing works

One AI credit equals one AI prompt, AI edit, or clipping minute. Clipping and captions charge one credit per started source minute. The quote is locked before work starts. Failed jobs and no-speech videos are refunded automatically.

Credits reset at the start of each billing period. Extra credits from packs never expire, but they are not refundable. Check GET /usage before large jobs.

MCP server

Connect your AI assistant

Point Claude, ChatGPT, or Cursor at https://www.takesly.com/api/mcp. Sign in with OAuth; an API key is not required for MCP.

The server exposes 17 tools: clip, caption, status, download, usage, schedule/list/cancel posts, list destinations, resolve channel, and create/list/get/update/pause/resume/delete automations.

Read the MCP guide

Changelog

Recent changes

1.26.0Automations

Channel automations with per-day budgets, pause/resume, and run history.

1.25.0Scheduling

Multi-platform scheduling API with per-platform validation.

1.24.0Captions

Captions endpoint for videos up to 20 minutes; source dimensions preserved.

1.22.0MCP

OAuth-protected MCP server with 17 tools.

1.20.0Credits

Locked quotes, duplicate protection, and automatic refunds.