> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Download media

> Download video or audio from a public URL at the quality you choose and get a direct link, or have it copied to your own S3 bucket.

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

```bash cURL theme={null}
curl -X POST https://api.importly.io/import \
  -H "Authorization: Bearer $IMPORTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "webhookUrl": "https://your-app.com/webhooks/importly"
  }'
```

```javascript Node.js theme={null}
// Submit an import; Importly POSTs the result to your webhook.
const res = await fetch('https://api.importly.io/import', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IMPORTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
    webhookUrl: 'https://your-app.com/webhooks/importly',
  }),
})
const { data } = await res.json()
console.log(data.jobId) // poll GET /import/status?id=... or wait for the webhook
```

```python Python theme={null}
import os
import requests

api_key = os.environ["IMPORTLY_API_KEY"]

# Submit an import; Importly POSTs the result to your webhook.
res = requests.post(
    "https://api.importly.io/import",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
        "webhookUrl": "https://your-app.com/webhooks/importly",
    },
)
print(res.json()["data"]["jobId"])  # poll GET /import/status?id=... or wait for the webhook
```

### Response

The request returns a job right away:

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "a824760e-ece1-4415-8838-ce2a7785ea6b",
    "status": "queued",
    "message": "Media import has been queued. You will receive a webhook when it's complete."
  }
}
```

When the job finishes, your webhook receives the file details:

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "a824760e-ece1-4415-8838-ce2a7785ea6b",
    "type": "import",
    "status": "completed",
    "mediaUrl": "https://fly.storage.tigris.dev/cdn-storage/imports/a824760e-ece1-4415-8838-ce2a7785ea6b/Me%20at%20the%20zoo.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&…&X-Amz-Expires=604800&X-Amz-Signature=…",
    "title": "Me at the zoo",
    "duration": 19,
    "thumbnailUrl": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…",
    "costInDollars": 0.03,
    "fileSizeBytes": 120621,
    "downloadedBytes": 252182,
    "filename": "Me at the zoo.mp3"
  }
}
```

`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](/docs/s3-storage.md).

## Options

| Parameter | Default | What it does |
| - | - | - |
| `url` | required | The public media page, e.g. a YouTube, TikTok, or podcast episode link |
| `includeVideo` | `true` | Set to `false` for audio only |
| `includeAudio` | `true` | Set to `false` for video only |
| `videoQuality` | `720p` | Highest video resolution to download (see [quality](#quality)) |
| `audioQuality` | `medium` | Highest audio bitrate to download |
| `webhookUrl` | none | HTTPS URL that receives the result when the job succeeds |
| `includeTranscript` | `false` | Also transcribe the media in the same job (see [transcripts](/docs/features/transcripts.md#transcripts-inside-an-import)) |
| `store` | `false` | Also upload the file to your own S3-compatible bucket |

Every parameter, including the transcript and storage options, is in the [`POST /import` reference](/docs/endpoints/import).

> [!NOTE]
>
> 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.

| `videoQuality` | Picks |
| - | - |
| `lowest` | The smallest available video |
| `144p` … `2160p` | Best video at or below that height (`144p`, `240p`, `360p`, `480p`, `720p`, `1080p`, `1440p`, `2160p`) |
| `best` | The highest available video |

| `audioQuality` | Picks |
| - | - |
| `lowest` | The smallest available audio |
| `low` | Best audio up to 64 kbps |
| `medium` | Best audio up to 128 kbps |
| `high` | Best audio up to 192 kbps |
| `best` | The highest available audio |

## Getting the result

> [tab] Webhook
>
> 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. Failed jobs don't send a webhook, and there are no retries, so keep polling as a fallback. Payloads for every job type are on [Webhooks](/docs/webhooks.md).

> [tab] Polling
>
> Call the status endpoint every few seconds until `status` is `completed` or `failed`. The result is nested under `result`:
>
> ```bash theme={null}
> curl "https://api.importly.io/import/status?id=a824760e-ece1-4415-8838-ce2a7785ea6b" \
>   -H "Authorization: Bearer $IMPORTLY_API_KEY"
> ```
>
> ```json theme={null}
> {
>   "success": true,
>   "data": {
>     "jobId": "a824760e-ece1-4415-8838-ce2a7785ea6b",
>     "status": "completed",
>     "result": {
>       "mediaUrl": "https://fly.storage.tigris.dev/cdn-storage/imports/a824760e-…/Me%20at%20the%20zoo.mp3?X-Amz-…",
>       "title": "Me at the zoo",
>       "duration": 19,
>       "filename": "Me at the zoo.mp3",
>       "fileSizeBytes": 120621,
>       "downloadedBytes": 252182,
>       "costInDollars": 0.03
>     },
>     "startedAt": "2026-11-16T14:36:05.491+00:00",
>     "completedAt": "2026-11-16T14:37:36.956+00:00"
>   }
> }
> ```
>
> A failed job has `status: "failed"` and a `message` explaining why.

## Pricing

Downloads cost $0.01 per MB downloaded, rounded up to the next MB, with a $0.03 minimum per import. You're charged only when the import succeeds.

| Example | Downloaded | Cost |
| - | - | - |
| 19-second clip, audio only | 0.24 MB | \$0.03 (the minimum) |
| 3-minute video at 720p | about 40 MB | about \$0.40 |

To spend less, lower `videoQuality`, or set `includeVideo: false` when you only need the audio. See [Pricing & credits](/docs/billing.md) for every price.

## Limits

> [accordion] Public media only
>
> Private, login-only, age-restricted, and password-protected media can't be downloaded. See [supported sites](/docs/features/supported-sites.md).

> [accordion] No playlists or live streams
>
> YouTube playlist pages are rejected; submit each video. Live streams fail until the stream has ended.

> [accordion] 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.

> [accordion] 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.

> [card] [Full reference: POST /import](/docs/endpoints/import.md)
>
> Every parameter, the status endpoint, and response fields.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.