curl --request POST \
--url https://www.ntanduy.com/api/v1/video/extract \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://www.youtube.com/watch?v=VIDEO_ID"
}
'{
"success": true,
"data": {
"platform": "youtube",
"sourceId": "VIDEO_ID",
"title": "Example video",
"previewUrl": "/api/v1/video/preview/opaque-preview-token",
"author": {
"displayName": "Example creator",
"handle": "example"
},
"durationSeconds": 95,
"stats": {
"views": 12500,
"likes": 640,
"comments": 28
},
"variants": [
{
"id": "video_1080p",
"downloadToken": "opaque-short-lived-token",
"requiresPreparation": false,
"label": "Video 1080p",
"kind": "video",
"extension": "mp4",
"mimeType": "video/mp4",
"sizeBytes": 52428800,
"qualityLabel": "1920x1080",
"recommended": true
}
]
}
}Extract video information
Extract normalized metadata and secure download options from a public video link.
curl --request POST \
--url https://www.ntanduy.com/api/v1/video/extract \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://www.youtube.com/watch?v=VIDEO_ID"
}
'{
"success": true,
"data": {
"platform": "youtube",
"sourceId": "VIDEO_ID",
"title": "Example video",
"previewUrl": "/api/v1/video/preview/opaque-preview-token",
"author": {
"displayName": "Example creator",
"handle": "example"
},
"durationSeconds": 95,
"stats": {
"views": 12500,
"likes": 640,
"comments": 28
},
"variants": [
{
"id": "video_1080p",
"downloadToken": "opaque-short-lived-token",
"requiresPreparation": false,
"label": "Video 1080p",
"kind": "video",
"extension": "mp4",
"mimeType": "video/mp4",
"sizeBytes": 52428800,
"qualityLabel": "1920x1080",
"recommended": true
}
]
}
}extract_video_metadata calls this synchronous endpoint. For file downloads, prefer start_video_download, get_video_download, then prepare_video_download; the host saves/sends the returned ready URL. See MCP download workflow.
For server-to-server use, send a Pirehub API key with the video:extract scope.
See Authentication for OAuth support and credential handling.The response contains only normalized public metadata, an internal preview URL,
and opaque short-lived download tokens.
See the video extraction guide for normalized platform
families, additional supported sites, token handling, limits, and responsible-use
requirements.
Subscription-backed API keys
Paid self-service keys use shared owner credits and the plan’s per-second and concurrent-job limits. Successful results, including cache hits, consume the configured action cost; errors release the reservation. Video jobs settle at completion. InspectX-ApiKey-Credit-* and X-ApiKey-RateLimit-*.
An optional Idempotency-Key prevents repeated synchronous execution/debits;
repeated operations return 409 rather than replaying a response. Job starts use
requestId instead. See API plans and idempotency
for costs, billing periods, headers, error codes and retry rules.Authorizations
OAuth 2.0 Authorization Code with PKCE, issued by Pirehub's Clerk authorization server. Request only the scopes required by the operation.
Headers
Self-service keys only. Owner-scoped operation identifier; reuse after admission returns 409 without another debit or execution. USAGE_CONCURRENCY_EXCEEDED retains no new reservation: wait and retry with the same identifier and payload. No response replay. Video jobs use requestId instead.
1 - 80^[a-zA-Z0-9_-]+$Body
A public HTTP or HTTPS media URL from a supported site. A missing scheme is normalized to HTTPS.
1"https://www.youtube.com/watch?v=VIDEO_ID"
"https://www.tiktok.com/@creator/video/VIDEO_ID"
"https://vimeo.com/VIDEO_ID"
"https://www.reddit.com/r/videos/comments/POST_ID/example/"