🛠️ Developers

GrabCast API

Download videos and transcribe audio programmatically with a simple REST API. Free to start — no credit card.

🔑 Get your free API key from Account & SettingsOpen →

Base URL & authentication

All requests go to the API base URL. Authenticate by sending your API key in the X-API-Key header (get it on the Account page).

# Base URL https://grabcast-api-2026.fly.dev # Header on every authenticated request X-API-Key: gc_your_key_here

Quick start

Start a download and poll for the result:

# 1) Start a download curl -X POST https://grabcast-api-2026.fly.dev/api/download \ -H "X-API-Key: gc_your_key_here" \ -H "Content-Type: application/json" \ -d '{"url":"https://youtube.com/watch?v=...","format":"mp4","quality":"720","mode":"single"}' # -> { "job_id": "ab12…", "status": "queued", "clamped_quality": "720" } # 2) Poll the job until status = "done" curl https://grabcast-api-2026.fly.dev/api/jobs/ab12… \ -H "X-API-Key: gc_your_key_here"

Endpoints

POST/api/extract RECOMMENDED · LIGHTWEIGHT

Get direct download URLs without our server downloading the video. Body: url. Returns title, thumbnail, progressive[] (each with a direct url, height, ext, filesize) and best audio. Your app downloads the bytes straight from the source CDN — near-zero load on us, so this scales to very high volume. Best for TikTok/Instagram/Facebook and progressive MP4.

POST/api/download

Server-side download (merges 1080p/4K, cleaner file) — heavier. Body: url, format (mp4 | mp3), quality (360/480/720/1080/best or 128/192/320), mode (single | bulk | channel), limit. Returns a job_id. Counts against your monthly quota.

GET/api/jobs

List your recent jobs and their status, progress and result files.

GET/api/jobs/{job_id}

Get one job. When status is done, result.files[] holds download_url, height, ext and size_bytes.

POST/api/transcribe

Transcribe a downloaded file to text. Body: path (the key from a finished download). Returns a job with .txt and .srt.

GET/api/health

Public health check — no key needed.

Rate limits & fair use

To keep the service fast and free for everyone, expensive endpoints are rate-limited per IP and every account has a monthly quota. Build a small delay/back-off into your client and prefer /api/extract (lightweight) over /api/download whenever you can.

Per-IP rate limits: /api/download 20/min · /api/transcribe 10/min · /api/extract 40/min. Over the limit → 429 with a Retry-After header.
Monthly quota per account on download and transcribe (see your plan on the Account page). /api/extract is lightweight and does not consume download quota.
401 invalid/missing key · 402 quota reached · 429 too many requests · 503 server busy (very high load — wait a few seconds and retry).
The API and web app share the same account, so keys, quota and history stay in sync.

Notes

Only download or transcribe content you own or have permission to use, in line with each platform's terms and local copyright law.
Keep your API key secret. If it's exposed, regenerate it on the Account page — the old key stops working immediately.

Get your API key →