Skip to main content
Downloading from YouTube or TikTok is easy from your laptop and unreliable from a server. Datacenter IPs get blocked, sites change how they serve video, and the streams you get back usually need ffmpeg to merge. Importly gives you a link to the finished file instead, and it works the same from a server, a CI job, or an agent sandbox.

Quick start

Request

Response

The request returns a job right away:
When the job finishes, your webhook receives the file details:
mediaUrl is a signed link to the file on Importly storage. It expires after 7 days, so copy the file somewhere permanent, or set store: true to have it copied to your bucket.

Options

Every parameter, including the transcript and storage options, is in the POST /import reference.
You’re billed for downloadedBytes, the bytes pulled from the source, not the size of the file you get. They differ for audio-only imports from platforms with no separate audio stream (common on TikTok): Importly downloads the smallest video and extracts the audio, so downloadedBytes is larger than fileSizeBytes.

Quality

Each setting is a ceiling. Importly picks the best stream at or below it. Video resolution is measured on the shorter side of the frame, so 720p is 1280×720 on a landscape video and 720×1280 on a portrait one (TikTok, Shorts, Reels). When a source has nothing at or below the ceiling, the import still runs: video takes the closest resolution above it and audio takes the best available. A source with a single file, such as a direct link or a podcast episode, downloads that file whatever the setting. Bitrates are nominal: a 128 kbps track that a source reports as 130 kbps still counts as medium.

Codecs

At a given resolution, Importly picks the smallest file in normal color (SDR) at the full frame rate. On YouTube that’s usually AV1 or VP9 video with Opus audio, in an .mp4. These play in Chrome, Firefox, Edge and ffmpeg, but not on older iPhones, in Safari on older Macs, in QuickTime, or in some video editors. Set compatibleCodecs: true to get H.264 video and AAC audio instead, which play everywhere. The file is usually larger, up to about 2.5× at 1080p, and you pay for the extra bytes. Where the source has no H.264 at that resolution (YouTube above 1080p, TikTok above 540p), you get the best codec it has. Every completed import reports what it holds in videoCodec (h264, hevc, vp9, av1) and audioCodec (aac, opus, mp3), so your app can check before it plays or edits the file.

Getting the result

Pass webhookUrl and Importly sends one POST to it when the job succeeds. The result fields sit directly on data, as in the example above. A job that fails for good sends a failure webhook instead. Deliveries aren’t retried, so keep polling as a fallback. Payloads for every job type are on Webhooks.

Pricing

A 10-minute video at 720p costs about $0.15 to download. Downloads are $2.05 per GB, billed as $0.002 per MB rounded up to the next MB, with a $0.01 minimum per import. You pay for what we download, and failed imports are free. To spend less, lower videoQuality, or set includeVideo: false when you only need the audio. See Pricing & credits for every price.

Limits

Private, login-only, age-restricted, and password-protected media can’t be downloaded. See supported sites.
YouTube playlist pages are rejected; submit each video. Live streams fail until the stream has ended.
An import never downloads more than your remaining credit can pay for. If the file is bigger, the job fails with FILE_TOO_LARGE; add credits or choose a lower quality. When we can tell up front, nothing is downloaded or charged. If the file turns out bigger partway through, the download stops when your credit runs out and you pay for what was downloaded.
Pass maxCostDollars to cap what one import can cost, transcript included. If the video would cost more, it isn’t downloaded: the job fails with MAX_COST_EXCEEDED and you’re charged $0.003 for the price check. See Capping the cost.

Full reference: POST /import

Every parameter, the status endpoint, and response fields.