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
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.
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
{
"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.
| Code | HTTP | Meaning |
|---|---|---|
| invalid_api_key | 401 | The key is missing, malformed, or revoked. |
| subscription_required | 403 | An active paid plan is required. |
| insufficient_credits | 402 | Not enough credits; response includes the needed amount. |
| video_too_short / video_too_long | 400 | Clipping accepts 5 minutes to 3 hours; captions up to 20 minutes. |
| video_unavailable | 400 | Private, removed, members-only, or unsupported source. |
| source_temporarily_blocked | 503 | Upstream download source is rate limiting us. |
| rate_limit | 429 | Too many requests or concurrent jobs. |
| cannot_cancel | 409 | A post has already started publishing. |
| not_found | 404 | The 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
| Method | Path | Purpose |
|---|---|---|
| GET | /status | Credits and plan |
| GET | /usage | Detailed usage |
| GET | /usage/history | Credit transaction history |
| POST | /clip | Start a clipping job |
| GET | /clip/:job_id | Job status and clips |
| GET | /clip/:job_id/download/all | Signed links for all clips |
| GET | /clip/:job_id/download/:index | Download one clip |
| GET | /clip/:job_id/thumbnail/:index | Clip 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— defaulthormozi. 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
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|resumeandDELETE /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
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 guideChangelog
Recent changes
Channel automations with per-day budgets, pause/resume, and run history.
Multi-platform scheduling API with per-platform validation.
Captions endpoint for videos up to 20 minutes; source dimensions preserved.
OAuth-protected MCP server with 17 tools.
Locked quotes, duplicate protection, and automatic refunds.