Developer API

Clip videos from your own code.

Integrate AI-powered video clipping into any workflow. Analyze videos, retrieve clips, and track usage with a simple REST API, TypeScript SDK, or CLI.

View endpoints TypeScript SDK

Authentication

Bearer token auth

Every request requires an API key passed as a Bearer token. Generate keys from your dashboard under Settings > API Keys.

Include your API key in the Authorization header of every request:

Authorization: Bearer ddc_your_api_key_here

API keys start with ddc_. Keep them secret — do not expose keys in client-side code or public repositories.

Endpoints

REST API reference

Four endpoints cover the full clipping workflow — analyze, retrieve, and monitor.

POST/api/v1/analyze

Analyze a video

Submit a video URL for analysis. By default the API returns a job immediately and you poll for completion. Add ?sync=true if you want the full result in a single response. Optionally pass guidance to steer the detector toward specific topics or styles.

Request body

{
  "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
  "guidance": "Focus on technical demos and code walkthroughs"
}

Response

{
  "jobId": "b6f0d97c-...",
  "status": "processing"
}

Example

curl -X POST https://clipper.developersdigest.tech/api/v1/analyze \
  -H "Authorization: Bearer ddc_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

GET/api/v1/jobs

List recent jobs

Returns recent async analysis jobs for the authenticated user. Optionally filter by status to inspect only processing, completed, or failed work.

Response

{
  "jobs": [
    {
      "id": "b6f0d97c-...",
      "status": "processing",
      "progress": "transcribing",
      "progressLabel": "Transcribing audio",
      "progressPercent": 55,
      "createdAt": 1712255400000
    }
  ]
}

Example

curl https://clipper.developersdigest.tech/api/v1/jobs?status=processing   -H "Authorization: Bearer ddc_your_key"

GET/api/v1/jobs/:id

Get job status

Poll an async analysis job until it completes. While processing, the response includes the current pipeline step. When complete, it includes the full analysis result.

Response

{
  "id": "b6f0d97c-...",
  "status": "processing",
  "progress": "transcribing",
  "progressLabel": "Transcribing audio",
  "progressPercent": 55,
  "createdAt": 1712255400000
}

Example

curl https://clipper.developersdigest.tech/api/v1/jobs/b6f0d97c-... \
  -H "Authorization: Bearer ddc_your_key"

GET/api/v1/clips

List all clips

Returns saved clips for the current API key. Supports status/query filters plus server-side sorting and pagination so larger libraries stay manageable.

Response

{
  "clips": [
    {
      "id": "clip_xyz789",
      "videoTitle": "The agent loop explained",
      "clipType": "insight",
      "startTime": 124.5,
      "endTime": 183.2,
      "confidence": 92,
      "status": "ready",
      "createdAt": 1712255400000
    }
  ],
  "total": 42,
  "page": 2,
  "limit": 10,
  "totalPages": 5,
  "sort": "highest-confidence"
}

Example

curl 'https://clipper.developersdigest.tech/api/v1/clips?status=ready&q=hooks&sort=highest-confidence&page=2&limit=10' \
  -H "Authorization: Bearer ddc_your_key"

GET/api/v1/clips/:id/download

Download a clip file

Redirects to the stored MP4 for a saved clip when an exported file has been attached. Use this to fetch the actual rendered asset instead of only clip metadata.

Response

302 Redirect → https://cdn.clipper.../clip_xyz789.mp4

Example

curl -L https://clipper.developersdigest.tech/api/v1/clips/clip_xyz789/download   -H "Authorization: Bearer ddc_your_key"   -o clip_xyz789.mp4

GET/api/v1/clips/:id

Get a single clip

Returns full details for a single saved clip, including transcript text and a downloadable file URL when an exported asset has been attached.

Response

{
  "id": "clip_xyz789",
  "videoUrl": "https://youtube.com/watch?v=dQw4w9WgXcQ",
  "videoTitle": "Building AI Agents from Scratch",
  "clipType": "insight",
  "startTime": 124.5,
  "endTime": 183.2,
  "confidence": 92,
  "transcript": "So the core idea behind an agent...",
  "format": "9:16",
  "status": "ready",
  "createdAt": 1712255400000,
  "fileUrl": "https://cdn.clipper.../clip_xyz789.mp4"
}

Example

curl https://clipper.developersdigest.tech/api/v1/clips/clip_xyz789 \
  -H "Authorization: Bearer ddc_your_key"

GET/api/v1/usage

Check usage

Returns your current credit balance, lifetime totals, and a log of recent API calls.

Response

{
  "credits": 469,
  "lifetimePurchased": 1500,
  "lifetimeUsed": 1031,
  "recentCalls": [
    {
      "endpoint": "/api/v1/analyze",
      "creditsUsed": 31,
      "timestamp": "2026-04-03T12:00:00Z"
    }
  ]
}

Example

curl https://clipper.developersdigest.tech/api/v1/usage \
  -H "Authorization: Bearer ddc_your_key"

TypeScript SDK

First-class SDK

Type-safe wrapper around the REST API. Install from npm and start clipping in three lines.

Install

npm install @dd-clipper/sdk

Usage

import { DDClipper } from '@dd-clipper/sdk';

const clipper = new DDClipper({ apiKey: 'ddc_...' });

// Analyze a video and wait for the result
const { video, clips, creditsUsed } = await clipper.analyze(
  'https://youtube.com/watch?v=dQw4w9WgXcQ'
);

console.log(`Found ${clips.length} clips, used ${creditsUsed} credits`);

// Submit a job without waiting
const { jobId } = await clipper.submitAnalyzeJob(
  'https://youtube.com/watch?v=dQw4w9WgXcQ'
);

const finished = await clipper.waitForJob(jobId, 3000);

// List all clips
const allClips = await clipper.listClips();

// Get a single clip
const clip = await clipper.getClip('clip_xyz789');

// Download the attached MP4
const downloaded = await clipper.downloadClip('clip_xyz789');

// Check usage
const usage = await clipper.usage();
console.log(`${usage.credits} credits remaining`);

CLI

Command-line interface

Run analysis and manage clips straight from your terminal. No code required.

Authenticate

npx dd-clipper login

Analyze a video

npx dd-clipper analyze https://youtube.com/watch?v=dQw4w9WgXcQ

Submit without waiting

npx dd-clipper analyze https://youtube.com/watch?v=dQw4w9WgXcQ --no-wait

Check a submitted job

npx dd-clipper job b6f0d97c-... --wait

List recent jobs

npx dd-clipper jobs --status processing

Inspect a saved clip

npx dd-clipper clip clip_xyz789

Download a saved clip

npx dd-clipper download clip_xyz789 --output ./clip.mp4

List your clips

npx dd-clipper clips

Check credit usage

npx dd-clipper usage

Credits

API usage is metered in credits. The system is simple and predictable.

1 credit

= 1 minute of video analyzed. A 30-minute video costs 30 credits.

No expiry

Purchased credits never expire. Use them whenever you need them.

Free tier

Every account starts with free monthly credits on the Starter plan. No card required.

Rate Limits

Fair usage limits

Rate limits protect the service and ensure consistent performance for everyone.

60 requests / minute

Each API key is limited to 60 requests per minute across all endpoints. If you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Need higher limits? Reach out — we offer custom rate limits for Studio plan customers and enterprise integrations.

curl -X POST https://clipper.developersdigest.tech/api/v1/analyze \ -H "Authorization: Bearer ddc_your_key" \ -H "Content-Type: application/json" \ -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

{ "jobs": [ { "id": "b6f0d97c-...", "status": "processing", "progress": "transcribing", "progressLabel": "Transcribing audio", "progressPercent": 55, "createdAt": 1712255400000 } ] }

{ "clips": [ { "id": "clip_xyz789", "videoTitle": "The agent loop explained", "clipType": "insight", "startTime": 124.5, "endTime": 183.2, "confidence": 92, "status": "ready", "createdAt": 1712255400000 } ], "total": 42, "page": 2, "limit": 10, "totalPages": 5, "sort": "highest-confidence" }

{ "id": "clip_xyz789", "videoUrl": "https://youtube.com/watch?v=dQw4w9WgXcQ", "videoTitle": "Building AI Agents from Scratch", "clipType": "insight", "startTime": 124.5, "endTime": 183.2, "confidence": 92, "transcript": "So the core idea behind an agent...", "format": "9:16", "status": "ready", "createdAt": 1712255400000, "fileUrl": "https://cdn.clipper.../clip_xyz789.mp4" }

{ "credits": 469, "lifetimePurchased": 1500, "lifetimeUsed": 1031, "recentCalls": [ { "endpoint": "/api/v1/analyze", "creditsUsed": 31, "timestamp": "2026-04-03T12:00:00Z" } ] }

import { DDClipper } from '@dd-clipper/sdk'; const clipper = new DDClipper({ apiKey: 'ddc_...' }); // Analyze a video and wait for the result const { video, clips, creditsUsed } = await clipper.analyze( 'https://youtube.com/watch?v=dQw4w9WgXcQ' ); console.log(`Found ${clips.length} clips, used ${creditsUsed} credits`); // Submit a job without waiting const { jobId } = await clipper.submitAnalyzeJob( 'https://youtube.com/watch?v=dQw4w9WgXcQ' ); const finished = await clipper.waitForJob(jobId, 3000); // List all clips const allClips = await clipper.listClips(); // Get a single clip const clip = await clipper.getClip('clip_xyz789'); // Download the attached MP4 const downloaded = await clipper.downloadClip('clip_xyz789'); // Check usage const usage = await clipper.usage(); console.log(`${usage.credits} credits remaining`);