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 limit: 10 requests/minute per API key. 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

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

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 process
• processing — actively being processed
• completed — finished successfully, results ready
• failed — processing error
• cancelled — cancelled while processing; credits refunded automatically
• expired — results no longer available

Decision guidance

When to use prompt vs topics vs neither

When to poll vs use webhooks

When to use sourceUrl vs uploadId

Workflow

Standard clipping workflow

1. Get upload URL — Call POST /get-upload-url with a filename. Receive a presigned S3 URL and upload ID.
2. Upload video — PUT the video file to the presigned URL. Reap validates the file at project creation, not upload.
3. Create clipping project — Call POST /create-clips with the upload ID, genre, export settings, and optional prompt for editorial control. Receive a project ID and status processing.
4. 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.
5. Retrieve clips — Once status is completed, call GET /get-project-clips?projectId=... to fetch all clips with URLs, titles, captions, and virality scores.
6. Publish (optional) — Call POST /publish-clip with a clip ID and integration IDs to post to social platforms.

Batch processing workflow

1. Upload multiple videos and create projects in parallel (up to 3 for Creator plan, 10 for Studio).
2. Set up a single webhook endpoint to receive notifications for all projects.
3. When a webhook fires, fetch the completed project's clips and queue them for publishing.
4. Use POST /schedule-clips to schedule posts across platforms at optimal times.

Reframing workflow

1. Upload video via POST /get-upload-url + PUT.
2. Call POST /create-reframe with upload ID and target orientation (portrait, square, landscape).
3. Poll or webhook for completion.
4. Retrieve reframed video from project details.

Caption-only workflow

1. Upload video or provide sourceUrl (YouTube or direct URL).
2. Call POST /create-captions with captionsPreset (style ID), enableEmojis, enableHighlights.
3. Poll or webhook for completion.
4. Retrieve captioned video from project details.

Common gotchas

• Forgetting to provide either sourceUrl or uploadId — 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 — Polling every second wastes your rate limit (10 req/min). Use 5–10 second intervals or 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: null to disable them. Default preset is system_beasty if not specified.
• Ignoring the prompt preview warning — The prompt field is production-ready but AI interpretation may evolve while in preview. Pin tested prompts for critical workflows.
• Not checking billedDuration — The response includes billedDuration (seconds that will be charged). Verify this matches your expectations before relying on the project.
• Trying to publish before completion — Only clips with status completed can be published. Attempting to publish a processing clip 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-project still work. A project is only cancellable via /cancel-project while it's still processing (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-integrations to list available ones.
• Passing invalid preset IDs — Caption presets must exist in your workspace. Call GET /get-all-presets to 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-usage returns your maxConcurrentProjects.
• Running out of credits mid-batch — Check GET /get-plan-usage before submitting large jobs: it returns mediaCredits/aiCredits as {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-credits returns 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 reframeClips field — Removed from /create-clips; exportOrientation alone controls cropping (portrait/square auto-crop the source, landscape keeps 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 YOURAPIKEY header
• Video file meets requirements (MP4/MOV, 2 min–3 hours, ≤5 GB)
• Either sourceUrl or uploadId is provided, but not both
• If using prompt, it is ≤1000 characters and describes editorial intent clearly
• If using captions, the captionsPreset ID exists (verified via GET /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
• billedDuration in 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