Skip to main content
For AI or bot integrations, use MCP start_video_download, poll get_video_download, then pass the selected variant token to prepare_video_download. A successful preparation returns a temporary ready file URL. The integrating host must GET it to save or send the file; MCP does not transfer binary video in JSON. Preparation waits up to 45 seconds and can time out while remote work continues. See MCP download workflow. Pirehub’s video extraction flow accepts a public video link and returns normalized metadata plus secure download options when compatible formats are available. It does not return raw provider responses, upstream media URLs, provider headers, or provider identifiers.
Use this feature only for content you own, have permission to download, or are otherwise legally allowed to use. Public availability does not remove copyright or platform terms.

​
Supported platforms

​
Normalized platform families

These families have dedicated platform detection and normalization. The response uses facebook, instagram, tiktok, youtube, or twitter in its platform field.

​
Additional recognized sites

Pirehub can also recognize and inspect public media URLs from additional sites. Download availability depends on whether the source exposes a finite, non-DRM media format that the secure download flow can deliver. Common examples include: This table is illustrative, not exhaustive. Coverage can change as source sites update their formats and access requirements.
Some recognized sources expose metadata but only provide streaming playlists, protected media, separate tracks, or another delivery format the current secure download flow cannot deliver. For any such source, the response succeeds with the available metadata, an empty variants array, and "downloadUnavailableReason": "no_downloadable_format". This is a media-format limitation, not a temporary provider outage.
Results from sites outside the five normalized families currently use "platform": "unknown". This value means Pirehub recognized an additional source; it does not mean extraction failed.
Only public HTTP or HTTPS links can be processed. A site appearing in this table does not guarantee that every URL exposes a downloadable format. Private, login-only, geo-restricted, deleted, active live, or temporarily changed content can still fail extraction. When metadata is available but no compatible download format is available, Pirehub returns a metadata-only result instead of treating the provider as unavailable. Active broadcasts, including BIGO LIVE rooms and Twitch live channels, expose a continuously changing media playlist rather than a completed file. They cannot be downloaded by the current request-based flow; public replays and clips may work once the platform exposes a finite media file.

​
Authentication

POST /api/v1/video/extract and POST /api/v1/video/extract/jobs accept a Pirehub API key with the video:extract scope for server-to-server integrations. Send the key in x-pirehub-api-key or as a bearer token. See Authentication for OAuth support and credential handling. The website starts a short request and polls for its result. This avoids holding one HTTP connection open while providers extract metadata, which can exceed CDN or hosting first-byte timeouts. The synchronous endpoint below remains available. Start with a newly generated UUID in requestId:
The API responds with HTTP 202:
Poll using the returned jobId and token. Never put the token in a query string, logs, or a shared link. Authenticate polling with this issued job token.
While processing, HTTP 200 contains {"success":true,"data":{"status":"pending","pollAfterMs":2000}}. When completed, data contains {"status":"completed","result":{...}}; result has the same fields as the synchronous extraction response below. Terminal failures use non-2xx HTTP statuses and the standard error envelope, preserving public codes such as MEDIA_UNAVAILABLE and UPSTREAM_TIMEOUT.
  • Reuse the same requestId and URL when retrying an uncertain start request. During the five-minute retention period, the same caller will receive the same job without starting extraction twice. A different URL with that ID returns 409. After expiry, that ID may start a new job; use a new UUID for an intentional retry.
  • Processing has a two-minute deadline. Job records and access tokens expire after five minutes; expired or invalid access returns 404.
  • Poll approximately every two seconds. Polling has a separate per-IP rate limit; it does not consume API-key extraction quota. Start requests, including retries, remain subject to normal verification and quotas.
  • Interrupted jobs may time out. Submit a new job after a terminal timeout.
  • The website stops waiting when cancelled or after 150 seconds. Cancelling polling does not cancel provider work already in progress.

​
Synchronous extraction request

​
Extraction response

Metadata is best-effort. previewUrl, author details, duration, statistics, file size, quality, and recommendation flags may be absent when the source does not provide them.

​
Using the result

  1. Display previewUrl directly or fetch it as an image. The URL is internal, short-lived, and may return 404 after it expires.
  2. Present the entries in variants. A variant can represent video or audio.
  3. Pass the selected opaque downloadToken to Pirehub’s configured download flow. Do not decode, modify, persist long-term, or expose the token in logs.
  4. If requiresPreparation is true, the download flow may report preparation and rendering progress before the file is ready.
Preview and download tokens are intentionally short-lived. Use them immediately and repeat extraction when they expire. Audio-only items on the website download in the format supplied by the extraction provider. The UI displays that format and the source size when available, with no MP3/M4A conversion selector. The download prepare request sends the opaque token without audioFormat; provider-required preparation still runs when needed. Direct-to-source responses remain controlled by the source server’s headers. The website starts one native download per selection after any required checks or preparation. A browser may still ask for download permission or a save location, especially on mobile. These prompts are controlled by browser settings and cannot be disabled by the website. Downloads requiring rendering are not ready immediately.

​
Limits and failures

Administrator-issued API keys use the per-minute and monthly request limits configured for that key. Inspect the X-ApiKey-RateLimit-* and X-ApiKey-Monthly-* headers. First-party browser requests without an API key are limited to 10 requests per minute per IP and return X-RateLimit-* headers. Honor Retry-After after a 429 response. Common failures include invalid URLs, unsupported sites, streaming-only formats, private or unprocessable content, exhausted rate limits, provider timeouts, and temporary provider unavailability. See Errors and retries. Public website extraction does not wait for sign-in initialization; verification and request limits still apply. The website allows up to 90 seconds per extraction attempt so sequential fallback providers can finish. It automatically retries once for HTTP 502 or 503 using a fresh verification token. It does not automatically retry content errors, rate limits, verification failures, or timeouts. An extra attempt counts toward the normal request limits and does not guarantee the provider will recover. 422 MEDIA_UNAVAILABLE means an extractor explicitly reported that the media is unavailable. It may have been removed, made private, or restricted; check the link on the original site instead of repeatedly retrying. 422 UNPROCESSABLE_ENTITY is less specific and does not prove that the media was deleted. Recoverable extraction failures can still use fallback providers. If all attempts fail, a content error is preserved instead of being replaced by a later fallback timeout. Actual timeouts without a content result remain 504 UPSTREAM_TIMEOUT.

​
Next steps

Video extract endpoint

Review the complete request and response schema.

Authentication

Learn about scopes and credential handling.

Errors and retries

Handle failures safely and predictably.

​
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. Inspect X-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.