Quick start
Request
Response
The request returns a job right away: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, so720p 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
- Webhook
- Polling
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
Public media only
Public media only
Private, login-only, age-restricted, and password-protected media can’t be downloaded. See supported sites.
No playlists or live streams
No playlists or live streams
YouTube playlist pages are rejected; submit each video. Live streams fail until the stream has ended.
Downloads are capped by your balance
Downloads are capped by your balance
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.Set your own cap per import
Set your own cap per import
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.Links expire after 7 days
Links expire after 7 days
mediaUrl is signed for 7 days. Copy the file somewhere permanent, or use store: true to deliver it to your own bucket.Full reference: POST /import
Every parameter, the status endpoint, and response fields.