Developer API

Automate your video creation workflow with our production-grade App API. Use our API to programmatically import videos, track render progress, and integrate CutCap AI into your own applications.

Authentication

All API requests must be authenticated using an API Key. You can manage your keys in Profile & Settings.

🔑 Using your API Key

Include your key in the Authorization header of every request:

Authorization: Bearer sk_live_your_api_key_here

---

Credit System

Our API is fully integrated with our unified credit system.

• Deduction: Credits are deducted when a video is successfully processed or rendered.
• Balance Check: Every API response includes a X-Remaining-Credits header.
• Insufficient Credits: If your balance is zero, the API will return 402 Payment Required.

---

📁 API Reference

1. Create/Import Video

POST /api/app/videos

The core endpoint for triggering our AI pipeline. This will start downloading the video, transcribing it, and optionally applying styles or extracting highlights.

Full Schema

---

Detailed Settings Guide

📺 Resolution & Quality

High-resolution rendering is available based on your subscription tier.

• 720p: Fast rendering, optimized for web preview.
• 1080p: Digital standard, recommended for TikTok and Reels.
• 2k: Quad HD (QHD), perfect for high-end digital displays.
• 4k: Maximum clarity for professional production (Requires Pro Plan).

📐 Aspect Ratio Mapping

• 9:16: Vertical (1080x1920) - Best for Shorts/Reels/TikTok.
• 16:9: Landscape (1920x1080) - Best for YouTube/Vimeo.
• 1:1: Square (1080x1080) - Best for Instagram Feed/Twitter.

---

Code Implementation Examples

Minimal Request

{
  "url": "https://www.youtube.com/watch?v=kXp8Rk6T5hI",
  "language": "auto",
  "videoType": "clip"
}

Full Production Integration

curl -X POST https://app.cutcap.ai/api/app/videos \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=...",
    "title": "Marketing Launch V2",
    "resolution": "1080p",
    "aspectRatio": "9:16",
    "videoFit": "cover",
    "language": "en",
    "presetId": "minimal",
    "videoType": "clip"
  }'

---

Response Success (201 Created)

{
  "videoId": "{videoId}",
  "status": "DOWNLOADING",
  "message": "AI Processing Pipeline Started",
  "creditsRemaining": 485
}

---

2. List Your Videos

GET /api/app/videos?page=1&limit=10

Returns a paginated list of your videos and their current status.

Example Request:

curl -X GET https://app.cutcap.ai/api/app/videos?page=1&limit=10 \
  -H "Authorization: Bearer sk_live_your_key"

---

3. Get Video Details

GET /api/app/videos/{videoId}

Fetch full metadata, transcription data, and render history for a specific video.

Example Request:

curl -X GET https://app.cutcap.ai/api/app/videos/{videoId} \
  -H "Authorization: Bearer sk_live_your_key"

---

4. Poll Render Status

GET /api/app/videos/{videoId}/render-status

The recommended way to track processing progress.

Example Request:

curl -X GET https://app.cutcap.ai/api/app/videos/{videoId}/render-status \
  -H "Authorization: Bearer sk_live_your_key"

---

🛠 Supported Values

1. Aspect Ratios (aspectRatio)

Use these keys to define the framing of your output video.

---

2. Subtitle Presets (presetId)

Apply professional, high-converting branding instantly by passing one of these IDs. We have also added the Animation Effect for each preset so you know exactly how the text will animate.

---

3. Transcription Languages (language)

We support over 50+ languages. Use the ISO codes below for the language parameter. For most cases, we recommend using "auto".

---

Best Practices

• Polling: We recommend polling the render status every 3-5 seconds.
• Security: Never share your sk_live_ key. If compromised, rotate it immediately in your settings.
• Rate Limiting: Our standard limit is 60 requests per minute.

Need help with integration? Contact our developer support team.

Back to Knowledge Base