Reap
Use when building video automation workflows — creating AI-powered short clips from long-form videos, adding captions, reframing for different aspect ratios, dubbing audio into multiple languages, generating transcriptions, or publishing clips to social media platforms (YouTube, Instagram, TikTok, LinkedIn, X).
How do I install this agent skill?
npx skills add https://docs.reap.video --skill reapIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
Reap Automation API Skill
Product summary
Reap is a REST API for automating video processing: AI clipping (extracting short clips from long videos), caption generation, smart reframing (adapting videos to different aspect ratios), AI dubbing (80+ languages), transcription, and direct publishing to YouTube, Instagram, TikTok, LinkedIn, and X. The API uses Bearer token authentication, runs at https://public.reap.video/api/v1/automation/, and supports webhooks for real-time project completion notifications. Rate limits are per endpoint, per API key: 60/minute for reads, 30/minute for writes, 10/minute for project creation. See the full API reference at https://docs.reap.video/api-reference/1_introduction.
When to use
Reach for this skill when:
- A user asks to extract short clips from a long video (podcast, webinar, keynote, stream)
- You need to add styled captions to a video with emoji and keyword highlighting
- A video needs to be reframed for different platforms (portrait for TikTok/Reels, square for Instagram, landscape for YouTube)
- Audio needs to be dubbed into another language with lip-aware timing
- A transcript or word-level timestamps are needed from video or audio
- Clips need to be published directly to social platforms with per-platform settings
- You're building a batch video processing pipeline that should scale across multiple videos
- Editorial control is needed — the user wants specific types of clips (highlight reel, trailer, quotes, educational moments, etc.) rather than generic virality-driven selection
Quick reference
API endpoints by task
| Task | Endpoint | Method |
|---|---|---|
| Get upload URL | /get-upload-url | POST |
| Upload video | (signed upload URL) | PUT |
| Create clips | /create-clips | POST |
| Create captions | /create-captions | POST |
| Reframe video | /create-reframe | POST |
| Dub audio | /create-dubbing | POST |
| Transcribe | /create-transcription | POST |
| Create editor project | /create-editor | POST |
| Check status | /get-project-status | GET |
| Cancel project | /cancel-project | POST |
| Get clips | /get-project-clips | GET |
| Publish clip | /publish-clip | POST |
| Schedule clips | /schedule-clips | POST |
| Get integrations | /get-integrations | GET |
| Get presets | /get-all-presets | GET |
| Check plan & credits | /get-plan-usage | GET |
| Buy media credits (checkout link) | /top-up-media-credits | GET |
| Billing portal link (admin only) | /manage-subscription | GET |
Video requirements
- Format: MP4 or MOV
- Duration: 2 minutes to 3 hours
- Size: Up to 5 GB
- Best for: Dialogue-rich content (podcasts, interviews, keynotes, webinars)
Project types and typical processing times
| Type | Time | Output |
|---|---|---|
| Clipping | 5–15 min | Multiple short clips with titles, captions, virality scores |
| Captions | 2–5 min | Video with styled captions, emoji, highlights |
| Reframe | 3–8 min | Video reframed for target orientation (portrait/square) |
| Dubbing | 10–20 min | Video with dubbed audio in target language |
| Transcription | 2–5 min | Word-level timestamped transcript |
Authentication
All requests require:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Get your API key from the Reap dashboard under Profile > Settings > API Keys.
Project status values
queued— waiting to processprocessing— actively being processedcompleted— finished successfully, results readyfailed— processing errorcancelled— cancelled while processing; credits refunded automaticallyexpired— results no longer available
Decision guidance
When to use prompt vs topics vs neither
| Scenario | Use | Why |
|---|---|---|
| User wants specific editorial style (highlight reel, trailer, quotes, educational) | prompt | Full natural-language control over clip count, duration, focus, exclusions, tone |
| User wants to bias toward certain themes but not control count/duration | topics | Lighter-weight; AI auto-maps to topic-focused mode |
| User wants AI to pick the most engaging moments (default behavior) | Neither | Falls back to virality-driven selection |
| User wants both theme bias and editorial control | Both prompt and topics | Prompt wins on conflict; topics act as additional guidance |
When to poll vs use webhooks
| Scenario | Use | Why |
|---|---|---|
| Building a production system with multiple concurrent projects | Webhooks | Real-time notifications, no polling loops, no rate limit waste |
| User is waiting synchronously for a result (UI, CLI) | Polling | Acceptable for interactive workflows; use 5–10 second intervals |
| Monitoring a single critical project | Webhooks + fallback polling | Webhooks for speed, polling as safety net if webhook fails |
When to use sourceUrl vs uploadId
| Scenario | Use | Why |
|---|---|---|
| User provides a YouTube URL | sourceUrl | Direct processing without upload step |
| User has a local video file | uploadId | Upload first via /get-upload-url, then reference the ID |
| User provides a direct video URL (not YouTube) | sourceUrl | Works with direct HTTP(S) URLs to video files |
Workflow
Standard clipping workflow
- Get upload URL — Call
POST /get-upload-urlwith a filename. Receive a signed upload URL and upload ID. - Upload video — PUT the video file to the presigned URL. Reap validates the file at project creation, not upload.
- Create clipping project — Call
POST /create-clipswith the upload ID, genre, export settings, and optionalpromptfor editorial control. Receive a project ID and statusprocessing. - Monitor progress — Either poll
GET /get-project-status?projectId=...every 5–10 seconds, or set up a webhook to be notified when the project reaches a terminal state. - Retrieve clips — Once status is
completed, callGET /get-project-clips?projectId=...to fetch all clips with URLs, titles, captions, and virality scores. - Publish (optional) — Call
POST /publish-clipwith a clip ID and integration IDs to post to social platforms.
Batch processing workflow
- Upload multiple videos and create projects in parallel (up to 3 for Creator plan, 10 for Studio).
- Set up a single webhook endpoint to receive notifications for all projects.
- When a webhook fires, fetch the completed project's clips and queue them for publishing.
- Use
POST /schedule-clipsto schedule posts across platforms at optimal times.
Reframing workflow
- Upload video via
POST /get-upload-url+ PUT. - Call
POST /create-reframewith upload ID and targetorientation(portrait, square, landscape). - Poll or webhook for completion.
- Retrieve reframed video from project details.
Caption-only workflow
- Upload video or provide
sourceUrl(YouTube or direct URL). - Call
POST /create-captionswithcaptionsPreset(style ID),enableEmojis,enableHighlights. For a video longer than the duration limit, addselectedStart/selectedEnd(seconds) to caption just that part (paid plans; on the Free plan the whole video must be within the limit). - Poll or webhook for completion.
- Retrieve captioned video from project details.
Edit a video workflow
- Upload the video via
POST /get-upload-url+ PUT, or use a link assourceUrl. - Call
POST /create-editorwith theuploadIdorsourceUrl. Optional:language(auto-detected when absent),resolution(default 1080), andselectedStart/selectedEnd(seconds) to edit just part of a longer video. It needs a paid plan and costs 2 media credits per minute of video, charged at creation. - Poll
GET /get-project-status?projectId=...or wait for the webhook. - When status is
completed, the project is ready to edit in the Reap editor. It holds one clip in draft; the clip has no rendered file (clipUrlis empty) until it is exported from the editor.
Common gotchas
- Forgetting to provide either
sourceUrloruploadId— The API requires exactly one; providing both or neither returns a 400 error. - Uploading but not creating a project — Uploading a file doesn't process it; you must call a create endpoint (
/create-clips,/create-captions, etc.) to start processing. - Polling too aggressively —
get-project-statusallows 60 requests/minute, so a one-second loop sits exactly at the limit with nothing left for retries. Use 2–5 second intervals, honourRetry-Afteron a429, or use webhooks instead. - Not handling webhook timeouts — Your webhook endpoint must respond with HTTP 200 and an empty body within 5 seconds. Slow endpoints will be auto-disabled after 5 consecutive failures.
- Assuming captions are always enabled — Captions are optional; pass
captionsPreset: nullto disable them. Default preset issystem_beastyif not specified. - Ignoring the
promptpreview warning — Thepromptfield is production-ready but AI interpretation may evolve while in preview. Pin tested prompts for critical workflows. - Not checking
billedDuration— The response includesbilledDuration(minutes that will be charged). Verify this matches your expectations before relying on the project. - Trying to publish before completion — Only clips with status
completedcan be published. Attempting to publish aprocessingclip returns a 400 error. - Editing or publishing a cancelled project — Once a project is
cancelled(credits are refunded automatically), it can't be renamed, edited, published, or scheduled — those calls return a 400 error. Reads and/delete-projectstill work. A project is only cancellable via/cancel-projectwhile it's stillprocessing(just after creation, or if it's been stuck for many hours). - Forgetting to set up integrations — Social publishing requires integrations (YouTube, Instagram, TikTok, LinkedIn, X accounts) connected in the dashboard first. Use
GET /get-integrationsto list available ones. - Passing invalid preset IDs — Caption presets must exist in your workspace. Call
GET /get-all-presetsto list valid IDs before using them. - Exceeding concurrent project limits — Creator plan allows 3 concurrent projects, Studio allows 10. Attempting to exceed returns a 429 error; wait for projects to complete.
GET /get-plan-usagereturns yourmaxConcurrentProjects. - Running out of credits mid-batch — Check
GET /get-plan-usagebefore submitting large jobs: it returnsmediaCredits/aiCreditsas{total, used, remaining}. Costs per billed minute: clipping/captions/transcription 1 media credit, reframe/editor 2 media credits, dubbing 0.5 AI credits.GET /top-up-media-creditsreturns a Stripe checkout link (packs of 100) if more are needed. - Sending prompts longer than 1000 characters — Prompts are capped at 1000 characters; longer ones are rejected at validation.
- Sending the legacy
reframeClipsfield — Removed from/create-clips;exportOrientationalone controls cropping (portrait/squareauto-crop the source,landscapekeeps the original framing). The field is silently ignored if sent.
Verification checklist
Before submitting work with the Reap API:
- API key is stored securely (environment variable, not hardcoded)
- All requests include
Authorization: Bearer YOUR_API_KEYheader - Video file meets requirements (MP4/MOV, 2 min–3 hours, ≤5 GB)
- Either
sourceUrloruploadIdis provided, but not both - If using
prompt, it is ≤1000 characters and describes editorial intent clearly - If using captions, the
captionsPresetID exists (verified viaGET /get-all-presets) - If publishing, integrations are set up in the dashboard and IDs are correct
- Webhook endpoint (if used) responds with HTTP 200 + empty body within 5 seconds
- Error handling is in place for 400, 401, 404, 422, 429, and 500 responses
- Processing times are realistic (5–15 min for clipping, 2–5 min for captions, etc.)
- Polling interval is 5–10 seconds (not aggressive), or webhooks are configured
-
billedDurationin the response is checked and expected
Resources
- Full API documentation index: https://docs.reap.video/llms.txt — comprehensive page-by-page navigation for all endpoints
- Quickstart guide: https://docs.reap.video/api-reference/3_quickstart — walk through upload, clip creation, and retrieval in 5 minutes
- Create Clips endpoint: https://docs.reap.video/api-reference/create-clips — detailed reference for AI clipping with prompt examples and editorial modes
- Webhooks guide: https://docs.reap.video/api-reference/webhooks — set up real-time notifications instead of polling
- Authentication: https://docs.reap.video/api-reference/2_authentication — API key management and security best practices
For additional documentation and navigation, see: https://docs.reap.video/llms.txt
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/docs.reap.video/reap">View Reap on skillZs</a>