Transcription API & MCP

REST API

The API uses your account’s transcript credits and the same processing flow as the website.

Base URL: https://proclipper.app. All requests below use a Bearer API key. OAuth tokens issued for MCP cannot be used as REST API keys.

All REST API requests

1. Create an API key

Open Dashboard → API keys, enter a friendly name, and select Create API key. Copy the token before closing; the full key is shown only once.

Send Authorization: Bearer YOUR_API_KEY with every request. Keep keys on your server, out of public browser code and source control. You can revoke individual keys from the dashboard.

2. Check your account

curl https://proclipper.app/api/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns id, username, email, plan, credits (clipping credits), transcriptCredits, and createdAt. This request is free.

3. List videos or inspect video metadata

Listing returns metadata without creating transcripts. Submit one channel or playlist URL, or a single video URL with mode: "full".

curl https://proclipper.app/api/youtube/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/@CHANNEL","maxVideos":10,"mode":"flat"}'

Channel listings use the Videos tab, excluding Shorts and live tabs. Results follow YouTube’s listing order, up to your limit; pagination is not supported. For a specific video’s upload date, send its URL with mode: "full" and maxVideos: 1.

A completed request returns HTTP 200. If it is still running after roughly 10 seconds, HTTP 202 returns a UUID jobId and status. Poll that job every few seconds instead of submitting again:

curl 'https://proclipper.app/api/youtube/videos?jobId=YOUR_LISTING_JOB_ID' \
  -H "Authorization: Bearer YOUR_API_KEY"

Polling returns pending, processing, or the completed result. Listing failures return an HTTP error. Only your account can access its jobs.

The completed result includes jobId, status, url, mode, maxVideos, count, videos, creditsCharged, and transcriptCredits. Each video contains youtubeId, url, title, channel, duration (seconds), thumbnail, and uploadDate (YYYY-MM-DD). Unavailable metadata may be null.

Each successful listing costs 1 transcript credit, even if empty. Polling is free; failed listings do not consume credits. Every new POST creates a separate billable request.

4. Submit transcripts

POST /api/transcribe accepts JSON. Replace VIDEO_ID with a YouTube video ID.

curl https://proclipper.app/api/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"links":["https://www.youtube.com/watch?v=VIDEO_ID"],"maxVideos":3}'

A successful submission returns HTTP 202 with a job ID. Processing runs in the background.

{"jobId":"123"}

Each video checked costs 1 transcript credit, including videos without available captions. Processing errors are refunded. An account without credits receives HTTP 402.

5. Check transcription progress

Use the returned job ID to check status. Poll every few seconds until the job reaches completed, partial, or failed.

curl 'https://proclipper.app/api/transcribe?jobId=123' \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes status, videos, skippedVideos, transcriptCredits, creditLimitReached, and combinedReady. Jobs start as pending and move to processing. A partial job has some successful results and some processing failures.

Ready videos appear in videos as they finish. Use each entry’s id to download that transcript. Only the account that owns a job can access it.

6. Download transcripts

Once combinedReady is true, download all transcripts in one file:

curl -L 'https://proclipper.app/api/transcribe?jobId=123&download=all&format=json&timestamps=true' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o transcripts.json

Or download a ZIP containing a separate file for each video:

curl -L 'https://proclipper.app/api/transcribe?jobId=123&download=zip&format=markdown' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o transcripts.zip

For a single ready transcript, replace download=all with download=TRANSCRIPT_ID, using the id from videos. Individual downloads are available before the entire job finishes.

JSON output contains a transcripts array with video metadata and cues. With timestamps enabled, cues include startTime and endTime in seconds.

Error responses