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

# Single Downloads

> Download individual videos from YouTube and other platforms

## Overview

Single downloads are the core feature of Tornado. Submit a video URL and receive a processed file uploaded to your cloud storage.

## Supported Options

| Parameter        | Type    | Required | Description                                                                              |
| ---------------- | ------- | -------- | ---------------------------------------------------------------------------------------- |
| `url`            | string  | Yes      | The video URL to download                                                                |
| `format`         | string  | No       | Output format: `mp4`, `mkv`, `webm`, `mov`, `m4a`, `mp3`, `ogg`, `opus` (default: `mp4`) |
| `filename`       | string  | No       | Custom filename (without extension)                                                      |
| `folder`         | string  | No       | Folder prefix for organization                                                           |
| `webhook_url`    | string  | No       | URL to receive completion notification                                                   |
| `audio_only`     | boolean | No       | Extract audio only (default format: `m4a`)                                               |
| `max_resolution` | string  | No       | Max resolution: `best`, `2160`, `1440`, `1080`, `720`, `480`, `360`                      |

## Basic Request

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'
```

## With All Options

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "format": "mp4",
    "filename": "my-custom-video",
    "folder": "youtube-downloads/2024",
    "webhook_url": "https://myapp.com/webhook"
  }'
```

## Processing Pipeline

<Steps>
  <Step title="Queue">
    Job is added to the processing queue
  </Step>

  <Step title="Download">
    Video and audio streams are downloaded in parallel using optimal quality
  </Step>

  <Step title="Mux">
    FFmpeg combines video + audio into the final format
  </Step>

  <Step title="Upload">
    File is uploaded to your cloud storage with multipart/resumable upload for large files
  </Step>

  <Step title="Complete">
    Webhook is called (if configured) and status is updated
  </Step>
</Steps>

## Quality Selection

Tornado automatically selects the best available quality:

| Priority | Resolution  | Codec     |
| -------- | ----------- | --------- |
| 1        | 2160p (4K)  | VP9/AV1   |
| 2        | 1440p (2K)  | VP9/H.264 |
| 3        | 1080p (FHD) | H.264     |
| 4        | 720p (HD)   | H.264     |

<Note>
  Audio is always downloaded at the highest available bitrate (usually 128-256 kbps).
</Note>

## Custom Filenames

Use the `filename` parameter to set a custom name:

```json theme={null}
{
  "url": "https://youtube.com/watch?v=...",
  "filename": "Episode 1 - Introduction"
}
```

The filename is automatically sanitized:

* Special characters are removed
* Spaces are preserved
* Extension is added based on format

## Folder Organization

Organize downloads into folders using the `folder` parameter:

```json theme={null}
{
  "url": "https://youtube.com/watch?v=...",
  "folder": "client-a/project-1/videos"
}
```

This creates the object path: `client-a/project-1/videos/video-title.mp4`

<Warning>
  Folder names cannot contain `..` or start with `/` for security.
</Warning>

## Error Handling

Common errors and solutions:

| Error                | Cause                    | Solution                           |
| -------------------- | ------------------------ | ---------------------------------- |
| `Video unavailable`  | Private or deleted video | Verify the URL is accessible       |
| `Sign in to confirm` | Age-restricted content   | Contact us for cookie support      |
| `Rate limited`       | Too many requests        | Wait and retry, we handle rotation |
| `Unsupported URL`    | Platform not supported   | Check supported platforms list     |