Tornado API

https://docs.tornadoapi.io
Admin
Tornado API is a media download and processing service that enables extracting, transcoding,...
Tokens:76,171
Snippets:584
Trust Score:5.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Bulk Create Audio Extraction with curl

Source: https://docs.tornadoapi.io/api-reference/bulk/create

Bulk create example for audio extraction. Sets audio_only to true and audio_bitrate to 320k, with a folder of music. Uses the same endpoint and headers as the video example.

```bash
curl -X POST "https://api.tornadoapi.io/jobs/bulk" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {"url": "https://youtube.com/watch?v=song1"},
      {"url": "https://youtube.com/watch?v=song2"},
      {"url": "https://youtube.com/watch?v=song3"}
    ],
    "folder": "music",
    "audio_only": true,
    "audio_bitrate": "320k"
  }'
```

--------------------------------

### Configure Google Drive with cURL, Python, and Response

Source: https://docs.tornadoapi.io/api-reference/user/configure-gdrive

Shows how to configure Google Drive as a storage provider by sending a POST request to the /user/gdrive endpoint. The cURL example passes the service account JSON inline; the Python example loads it from a file, which is recommended. The response confirms the configuration with the provider, folder ID, and optional folder prefix.

```bash
curl -X POST "https://api.tornadoapi.io/user/gdrive" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
    "service_account_json": "{\"type\":\"service_account\",\"project_id\":\"my-gcp-project\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"tornado@my-gcp-project.iam.gserviceaccount.com\"}"
  }'
```

```python
import requests
import json

# Load service account JSON file (recommended)
with open("service-account.json") as f:
    sa_json = json.dumps(json.load(f))

response = requests.post(
    "https://api.tornadoapi.io/user/gdrive",
    headers={"x-api-key": "sk_your_api_key"},
    json={
        "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
        "service_account_json": sa_json
    }
)
print(response.json())
```

```json
{
  "message": "Google Drive configured successfully",
  "provider": "gdrive",
  "folder_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "folder_prefix": null
}
```

--------------------------------

### POST /batch/{id}/start

Source: https://docs.tornadoapi.io/api-reference/introduction

Starts a paused batch.

```APIDOC
## POST /batch/{id}/start

### Description
Starts a paused batch.

### Method
POST

### Endpoint
/batch/{id}/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The batch ID

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
{
  "message": "Batch started"
}
```

--------------------------------

### Bulk Create with curl, Node.js, and Python

Source: https://docs.tornadoapi.io/api-reference/bulk/create

Examples of creating a bulk job with video downloads using curl, Node.js fetch, and Python requests. All three send a POST to https://api.tornadoapi.io/jobs/bulk with an x-api-key header and a JSON body containing a jobs array and shared options. The Node.js and Python examples print the total_jobs and batch_id from the response.

```bash
curl -X POST "https://api.tornadoapi.io/jobs/bulk" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {"url": "https://youtube.com/watch?v=video1", "filename": "my-first-video"},
      {"url": "https://youtube.com/watch?v=video2", "filename": "my-second-video"},
      {"url": "https://youtube.com/watch?v=video3"}
    ],
    "folder": "my-downloads",
    "format": "mp4"
  }'
```

```javascript
const response = await fetch('https://api.tornadoapi.io/jobs/bulk', {
  method: 'POST',
  headers: {
    'x-api-key': 'sk_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jobs: [
      {url: 'https://youtube.com/watch?v=video1', filename: 'my-first-video'},
      {url: 'https://youtube.com/watch?v=video2', filename: 'my-second-video'},
      {url: 'https://youtube.com/watch?v=video3'}
    ],
    folder: 'my-downloads',
    format: 'mp4'
  })
});

const data = await response.json();
console.log(`Created ${data.total_jobs} jobs`);
console.log(`Batch ID: ${data.batch_id}`);
```

```python
import requests

response = requests.post(
    'https://api.tornadoapi.io/jobs/bulk',
    headers={'x-api-key': 'sk_your_api_key'},
    json={
        'jobs': [
            {'url': 'https://youtube.com/watch?v=video1', 'filename': 'my-first-video'},
            {'url': 'https://youtube.com/watch?v=video2', 'filename': 'my-second-video'},
            {'url': 'https://youtube.com/watch?v=video3'}
        ],
        'folder': 'my-downloads',
        'format': 'mp4'
    }
)

data = response.json()
print(f"Created {data['total_jobs']} jobs")
```

--------------------------------

### Authenticate with x-api-key and get usage

Source: https://docs.tornadoapi.io/api-reference/introduction

Authenticates with the x-api-key header and retrieves usage statistics.

```bash
curl -H "x-api-key: sk_your_api_key" https://api.tornadoapi.io/usage
```

--------------------------------

### Response - With Billing

Source: https://docs.tornadoapi.io/api-reference/user/get-usage

Example response including billing period and current period usage for accounts with billing enabled.

```json
{
  "client_name": "My Application",
  "usage_count": 1523,
  "storage_usage_gb": 45.67,
  "storage_reserved_gb": 0.52,
  "storage_effective_usage_gb": 46.19,
  "billing_period_start": "2024-01-01T00:00:00Z",
  "billing_period_end": "2024-02-01T00:00:00Z",
  "current_period_usage_gb": 12.34
}
```

--------------------------------

### Response - Trial Key with Storage Limit

Source: https://docs.tornadoapi.io/api-reference/user/get-usage

Example response for a trial key that includes storage limit and remaining storage fields.

```json
{
  "client_name": "My Trial Account",
  "usage_count": 42,
  "storage_usage_gb": 3.0,
  "storage_reserved_gb": 0.0,
  "storage_effective_usage_gb": 3.0,
  "storage_limit_gb": 1024.0,
  "storage_limit_bytes": 1099511627776,
  "storage_remaining_gb": 1021.0
}
```

--------------------------------

### Response - Standard Usage

Source: https://docs.tornadoapi.io/api-reference/user/get-usage

Example response showing basic usage information including client name, usage count, and storage usage.

```json
{
  "client_name": "My Application",
  "usage_count": 1523,
  "storage_usage_gb": 45.67,
  "storage_reserved_gb": 0.52,
  "storage_effective_usage_gb": 46.19
}
```

--------------------------------

### Response - Key with Limits

Source: https://docs.tornadoapi.io/api-reference/user/get-usage

Example response for a key with limits, including maximum resolution, duration, and file size limits.

```json
{
  "client_name": "Limited Key",
  "usage_count": 100,
  "storage_usage_gb": 5.0,
  "storage_reserved_gb": 0.0,
  "storage_effective_usage_gb": 5.0,
  "max_resolution_limit": "1080",
  "max_duration_limit_seconds": 600,
  "max_filesize_limit_bytes": 524288000,
  "max_filesize_limit_mb": 500.0
}
```

--------------------------------

### Create job with inline storage (GCS and Alibaba OSS)

Source: https://docs.tornadoapi.io/api-reference/jobs/create

Create a job with inline storage credentials for Google Cloud Storage (GCS) or Alibaba OSS. Both examples POST to /jobs with the same URL and differ only in the storage provider and its required fields. Use these when you want to supply credentials directly in the request rather than referencing a saved destination.

```bash
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",
    "storage": {
      "provider": "gcs",
      "project_id": "my-gcp-project",
      "bucket": "tornado-downloads",
      "service_account_json": "{\"type\":\"service_account\",\"project_id\":\"my-gcp-project\",...}",
      "folder_prefix": "downloads/"
    }
  }'
```

```bash
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",
    "storage": {
      "provider": "oss",
      "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
      "bucket": "tornado-downloads",
      "access_key_id": "your-oss-access-key-id",
      "access_key_secret": "your-oss-access-key-secret",
      "folder_prefix": "downloads/"
    }
  }'
```

--------------------------------

### POST /batch/{id}/start

Source: https://docs.tornadoapi.io/api-reference/batch/start

Starts a paused batch, enqueuing all episode jobs for processing. The batch must be in `paused` status.

```APIDOC
## [POST] /batch/{id}/start

### Description
Starts a paused batch, enqueuing all episode jobs for processing. The batch must be in `paused` status.

### Method
POST

### Endpoint
/batch/{id}/start

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - Your API key for authentication

#### Path Parameters
- **id** (string) - Required - The batch UUID returned from `POST /jobs`

### Request Example
```bash
curl -X POST "https://api.tornadoapi.io/batch/550e8400-e29b-41d4-a716-446655440001/start" \
  -H "x-api-key: sk_your_api_key"
```

### Response
#### Success Response (200)
- **batch_id** (string) - The batch UUID
- **started_jobs** (integer) - Number of jobs successfully enqueued for processing
- **status** (string) - New batch status (`processing`)

#### Response Example
```json
{
  "batch_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_jobs": 142,
  "status": "processing"
}
```

### Error Responses
#### 400 Bad Request
```json
{
  "error": "Batch is not paused (current status: processing)"
}
```

#### 401 Unauthorized
```json
{
  "error": "Batch does not belong to this API key"
}
```

#### 404 Not Found
```json
{
  "error": "Batch not found"
}
```

```

--------------------------------

### Success response for video podcast

Source: https://docs.tornadoapi.io/api-reference/metadata/spotify-has-video

Example 200 response when the show has video episodes. Shows has_video true and total_episodes 100.

```json
{
  "show_id": "11VjrLJfoiNvgjjqov4RWh",
  "has_video": true,
  "episodes_scanned": 100,
  "total_episodes": 100,
  "determinate": true,
  "cached": false
}
```

--------------------------------

### 200 OK Success Response

Source: https://docs.tornadoapi.io/api-reference/user/get-s3

Example of a successful 200 OK response for a configured S3 bucket.

```json
{
  "configured": true,
  "provider": "s3",
  "container_or_bucket": "my-tornado-downloads",
  "folder_prefix": "videos/",
  "base_folder": "videos",
  "last_modified": 1751980800,
  "source": "keyvault"
}
```

--------------------------------

### Error Response

Source: https://docs.tornadoapi.io/

Example of an error response from the API.

```APIDOC
## Error Response

### Description
An error response returns a JSON object with an `error` field describing the issue.

### Response
#### Error Response
- **error** (string) - Description of the error.

#### Response Example
{
  "error": "Invalid API Key"
}
```

--------------------------------

### Success Response

Source: https://docs.tornadoapi.io/

Example of a successful JSON response from the API.

```APIDOC
## Success Response

### Description
A successful response returns a JSON object with a `job_id` field.

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier for the job.

#### Response Example
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### S3 Configuration Response Examples

Source: https://docs.tornadoapi.io/api-reference/user/get-s3

Possible JSON responses indicating configured status via Key Vault, legacy settings, or unconfigured state.

```json
{
  "configured": true,
  "provider": "s3",
  "container_or_bucket": "my-tornado-downloads",
  "folder_prefix": "videos/",
  "base_folder": "videos",
  "last_modified": 1751980800,
  "source": "keyvault"
}
```

```json
{
  "configured": true,
  "provider": "s3",
  "container_or_bucket": "my-tornado-downloads",
  "endpoint": "https://s3.us-east-1.amazonaws.com",
  "region": "us-east-1",
  "access_key_masked": "****MPLE",
  "source": "legacy"
}
```

```json
{
  "configured": false
}
```

--------------------------------

### Configure S3 storage with curl, Python, and response

Source: https://docs.tornadoapi.io/api-reference/user/configure-s3

Configure S3-compatible storage for the Tornado API user endpoint. The first curl example targets AWS S3 with a folder prefix; the second targets Cloudflare R2 with region 'auto'. The Python example uses the requests library to POST the same configuration. The JSON response shows the expected success output.

```bash
curl -X POST "https://api.tornadoapi.io/user/s3" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://s3.us-east-1.amazonaws.com",
    "bucket": "my-tornado-downloads",
    "region": "us-east-1",
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "folder_prefix": "videos/"
  }'
```

```bash
curl -X POST "https://api.tornadoapi.io/user/s3" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "bucket": "my-downloads",
    "region": "auto",
    "access_key": "R2_ACCESS_KEY_ID",
    "secret_key": "R2_SECRET_ACCESS_KEY"
  }'
```

```python
import requests

response = requests.post(
    "https://api.tornadoapi.io/user/s3",
    headers={"x-api-key": "sk_your_api_key"},
    json={
        "endpoint": "https://s3.us-east-1.amazonaws.com",
        "bucket": "my-tornado-downloads",
        "region": "us-east-1",
        "access_key": "AKIAIOSFODNN7EXAMPLE",
        "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
)
print(response.json())
```

```json
{
  "message": "S3 storage configured successfully",
  "provider": "s3",
  "container_or_bucket": "my-tornado-downloads",
  "folder_prefix": "videos/"
}
```

--------------------------------

### Rate Limit Exceeded Response

Source: https://docs.tornadoapi.io/

Example of the JSON error returned when the rate limit is exceeded.

```APIDOC
## Rate Limit Exceeded Response

### Description
When the rate limit is reached, the API responds with a 429 status and a JSON error containing retry advice.

### Response
#### Error Response (429)
- **error** (string) - Error code, e.g., `rate_limit_exceeded`.
- **message** (string) - Human-readable message with retry advice.
- **retry_after** (integer) - Seconds to wait before retrying.
- **limit_requests_per_second** (integer) - The rate limit value.
- **bulk_endpoint** (string) - The bulk endpoint path.
- **max_jobs_per_bulk** (integer) - Maximum jobs per bulk request.

#### Response Example
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests for this authenticated client. Retry after 1 second. For multiple downloads with a direct API key, use POST /jobs/bulk with up to 100 jobs per request.",
  "retry_after": 1,
  "limit_requests_per_second": 1000,
  "bulk_endpoint": "/jobs/bulk",
  "max_jobs_per_bulk": 100
}
```

--------------------------------

### Success response for reset bucket config

Source: https://docs.tornadoapi.io/api-reference/user/reset-bucket

Example JSON response returned on successful reset. The message confirms the bucket configuration has been reset to default.

```json
{
  "message": "Bucket configuration reset to default"
}
```

--------------------------------

### Error Response (404 Not Found)

Source: https://docs.tornadoapi.io/api-reference/batch/get-status

Example error response with HTTP 404 Not Found. Returns null when the batch or resource is not found.

```json
null
```

--------------------------------

### Success Response (200 OK)

Source: https://docs.tornadoapi.io/api-reference/batch/get-status

Example success response with HTTP 200 OK. Shows a completed batch with all episodes processed and no failures.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "show_url": "https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
  "status": "completed",
  "folder": "huberman-lab-2024",
  "total_episodes": 142,
  "completed_episodes": 142,
  "failed_episodes": 0,
  "skipped_episodes": 0,
  "episode_jobs": ["uuid-1", "uuid-2", "uuid-3"]
}
```

--------------------------------

### Success response served from cache

Source: https://docs.tornadoapi.io/api-reference/metadata/spotify-has-video

Example 200 response when the result is served from cache. Shows cached true and has_video true.

```json
{
  "show_id": "11VjrLJfoiNvgjjqov4RWh",
  "has_video": true,
  "episodes_scanned": 100,
  "total_episodes": 100,
  "determinate": true,
  "cached": true
}
```

--------------------------------

### Video Clipping

Source: https://docs.tornadoapi.io/api-reference/jobs/create

Creates a job that clips the video from the start time to the end time. The clip_start and clip_end parameters are set to '00:01:30' and '00:03:00' respectively.

```bash
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",
    "clip_start": "00:01:30",
    "clip_end": "00:03:00"
  }'
```

--------------------------------

### GET /usage

Source: https://docs.tornadoapi.io/api-reference/introduction

Gets usage statistics.

```APIDOC
## GET /usage

### Description
Gets usage statistics.

### Method
GET

### Endpoint
/usage

### Response
#### Success Response (200)
- **usage** (object) - Usage statistics

#### Response Example
{
  "usage": {
    "requests": 100,
    "downloads": 50
  }
}
```

--------------------------------

### GET /user/s3

Source: https://docs.tornadoapi.io/api-reference/introduction

Gets the current S3 storage configuration.

```APIDOC
## GET /user/s3

### Description
Gets the current S3 storage configuration.

### Method
GET

### Endpoint
/user/s3

### Response
#### Success Response (200)
- **bucket** (string) - The bucket name
- **access_key** (string) - The access key

#### Response Example
{
  "bucket": "my-bucket",
  "access_key": "AKIA..."
}
```

--------------------------------

### GET /batch/{id}

Source: https://docs.tornadoapi.io/api-reference/introduction

Gets the status of a batch operation.

```APIDOC
## GET /batch/{id}

### Description
Gets the status of a batch operation.

### Method
GET

### Endpoint
/batch/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The batch ID

### Response
#### Success Response (200)
- **id** (string) - The batch ID
- **status** (string) - The batch status

#### Response Example
{
  "id": "batch_123",
  "status": "paused"
}
```

--------------------------------

### Create a multi-clip job with a clips array

Source: https://docs.tornadoapi.io/features/advanced-options

Create one job that produces multiple clips from a single video by submitting a `clips` array. The worker downloads the source once and outputs one file per range in order, with filenames ending in `-clip-001.mp4`, `-clip-002.mp4`, etc. All clips share the format, encoding, and storage options; `audio_only` is supported. Do not combine `clips` with top-level `clip_start`/`clip_end`.

```bash
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",
    "clips": [
      {"clip_start": "0", "clip_end": "15"},
      {"clip_start": "00:01:00", "clip_end": "00:01:30"}
    ],
    "filename": "highlights",
    "format": "mp4"
  }'
```

--------------------------------

### GET /jobs/{id}

Source: https://docs.tornadoapi.io/api-reference/introduction

Gets the status of a specific download job by its ID.

```APIDOC
## GET /jobs/{id}

### Description
Gets the status of a specific download job.

### Method
GET

### Endpoint
/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID

### Response
#### Success Response (200)
- **id** (string) - The job ID
- **status** (string) - The job status

#### Response Example
{
  "id": "job_123",
  "status": "completed"
}
```

--------------------------------

### curl Request to Get Usage

Source: https://docs.tornadoapi.io/api-reference/user/get-usage

Sends a GET request to the usage endpoint with an API key to retrieve usage statistics.

```bash
curl -X GET "https://api.tornadoapi.io/usage" \
  -H "x-api-key: sk_your_api_key"
```

--------------------------------

### Get Job Status with curl

Source: https://docs.tornadoapi.io/api-reference/jobs/get-status

Sends a GET request to the /jobs/{id} endpoint with an API key to retrieve job details.

```bash
curl -X GET "https://api.tornadoapi.io/jobs/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: sk_your_api_key"
```

--------------------------------

### Response: 404 Not Found

Source: https://docs.tornadoapi.io/api-reference/user/delete-oss

Error response when no OSS configuration exists.

```json
{
  "error": "No OSS configuration found"
}
```

--------------------------------

### Get Batch Status with curl

Source: https://docs.tornadoapi.io/api-reference/batch/get-status

Sends a GET request to the Tornado API batch endpoint with an API key to retrieve the current status of a batch job.

```bash
curl -X GET "https://api.tornadoapi.io/batch/550e8400-e29b-41d4-a716-446655440001" \
  -H "x-api-key: sk_your_api_key"
```

--------------------------------

### GET /jobs

Source: https://docs.tornadoapi.io/api-reference/introduction

Lists all jobs.

```APIDOC
## GET /jobs

### Description
Lists all jobs.

### Method
GET

### Endpoint
/jobs

### Response
#### Success Response (200)
- **jobs** (array) - List of jobs

#### Response Example
{
  "jobs": [
    {
      "id": "job_123",
      "status": "completed"
    }
  ]
}
```

--------------------------------

### GET /jobs

Source: https://docs.tornadoapi.io/

Lists all jobs for the authenticated user.

```APIDOC
## GET /jobs

### Description
List all jobs.

### Method
GET

### Endpoint
/jobs

### Authentication
Requires `x-api-key` header.

### Request Example
```
curl -H "x-api-key: sk_your_api_key" https://api.tornadoapi.io/jobs
```

### Response
#### Success Response (200)
List of jobs.

```

--------------------------------

### Download with Subtitles & Thumbnail

Source: https://docs.tornadoapi.io/api-reference/jobs/create

Creates a job that downloads subtitles and a thumbnail along with the video. Both flags are set to true.

```bash
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",
    "download_subtitles": true,
    "download_thumbnail": true
  }'
```

--------------------------------

### Start a paused batch with curl

Source: https://docs.tornadoapi.io/api-reference/batch/start

Starts a paused batch by sending a POST request to the /batch/{id}/start endpoint. The batch must be in paused status. The response includes the batch ID, the number of jobs enqueued, and the new status (processing).

```bash
curl -X POST "https://api.tornadoapi.io/batch/550e8400-e29b-41d4-a716-446655440001/start" \
  -H "x-api-key: sk_your_api_key"
```

```json
{
  "batch_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_jobs": 142,
  "status": "processing"
}
```

--------------------------------

### Configure Alibaba OSS with Python (requests library)

Source: https://docs.tornadoapi.io/api-reference/user/configure-oss

Use the Python requests library to call the /user/oss endpoint with the same required body fields. The response is printed as JSON. This example is an alternative to the cURL command.

```python
import requests

response = requests.post(
    "https://api.tornadoapi.io/user/oss",
    headers={"x-api-key": "sk_your_api_key"},
    json={
        "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
        "bucket": "tornado-downloads",
        "access_key_id": "LTAI5tXXXXXXXXXXXXXX",
        "access_key_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
)
print(response.json())
```

--------------------------------

### Configure Alibaba OSS with cURL (POST /user/oss)

Source: https://docs.tornadoapi.io/api-reference/user/configure-oss

Use this cURL command to configure Alibaba Cloud OSS. The command sends a POST request to the /user/oss endpoint with an API key and OSS credentials (endpoint, bucket, access key ID, and secret). The access key secret is an 'XXXX' masked example value. Inline displays show the API endpoint and body.

```bash
curl -X POST "https://api.tornadoapi.io/user/oss" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
    "bucket": "tornado-downloads",
    "access_key_id": "LTAI5tXXXXXXXXXXXXXX",
    "access_key_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXX"
  }'
```

--------------------------------

### Configure Alibaba OSS - Successful Response (JSON)

Source: https://docs.tornadoapi.io/api-reference/user/configure-oss

Shows a successful response after configuring Alibaba OSS. It returns a confirmation message, provider type 'oss', and the bucket name.

```json
{
  "message": "Alibaba OSS storage configured successfully",
  "provider": "oss",
  "container_or_bucket": "tornado-downloads"
}
```

--------------------------------

### Response: Success message

Source: https://docs.tornadoapi.io/api-reference/user/delete-oss

Example of a successful response with a confirmation message.

```json
{
  "message": "OSS storage configuration removed"
}
```

--------------------------------

### GET /batches/{id}

Source: https://docs.tornadoapi.io/api-reference/batch/get-status

Retrieves the current status and progress of a batch download operation.

```APIDOC
## GET /batches/{id}

### Description
Retrieves the current status and progress of a batch download operation.

### Method
GET

### Endpoint
/batches/{id}

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - Your API key for authentication

#### Path Parameters
- **id** (string) - Required - The batch UUID returned from `POST /jobs` when submitting a Spotify show URL

### Response
#### Success Response (200)
- **id** (string) - Batch UUID
- **show_url** (string) - Original Spotify show URL
- **status** (string) - Batch status: `paused`, `processing`, `completed`, or `finished`
- **folder** (string) - S3 folder prefix for episodes
- **total_episodes** (integer) - Total number of episodes in the show
- **completed_episodes** (integer) - Number of successfully completed episodes
- **failed_episodes** (integer) - Number of failed episodes
- **skipped_episodes** (integer) - Number of skipped episodes (e.g. audio-only Spotify episodes protected by Widevine DRM)
- **episode_jobs** (array) - List of individual job UUIDs for each episode

#### Response Example
{
  "id": "string",
  "show_url": "string",
  "status": "string",
  "folder": "string",
  "total_episodes": 0,
  "completed_episodes": 0,
  "failed_episodes": 0,
  "skipped_episodes": 0,
  "episode_jobs": []
}
```

--------------------------------

### Record from Start (VOD Mode) with curl

Source: https://docs.tornadoapi.io/features/advanced-options

Records a live stream from its beginning (VOD mode) by setting live_from_start to true. The max_duration is set to 7200 seconds.

```bash
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/live/abc123",
    "live_recording": true,
    "live_from_start": true,
    "max_duration": 7200
  }'
```

--------------------------------

### Python request to configure GCS from service account file

Source: https://docs.tornadoapi.io/api-reference/user/configure-gcs

Loads a service account JSON from a file (recommended) and posts it to /user/gcs. Prints the response JSON.

```Python
import requests
import json

# Load service account JSON file (recommended)
with open("service-account.json") as f:
    sa_json = json.dumps(json.load(f))

response = requests.post(
    "https://api.tornadoapi.io/user/gcs",
    headers={"x-api-key": "sk_your_api_key"},
    json={
        "project_id": "my-gcp-project",
        "bucket": "tornado-downloads",
        "service_account_json": sa_json
    }
)
print(response.json())
```

--------------------------------

### Batch Status Response - Finished with Failures

Source: https://docs.tornadoapi.io/api-reference/batch/get-status

Example JSON response when all episodes are done but some have failed.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "show_url": "https://open.spotify.com/show/7iQXmUT7XGuZSzAMjoNWlX",
  "status": "finished",
  "folder": "huberman-lab-2024",
  "total_episodes": 142,
  "completed_episodes": 140,
  "failed_episodes": 2,
  "episode_jobs": ["uuid-1", "uuid-2", "..."]
}
```

--------------------------------

### POST https://api.tornadoapi.io/user/s3

Source: https://docs.tornadoapi.io/api-reference/user/configure-s3

Configures an S3-compatible storage provider for downloads. Provide the endpoint, bucket, region, and credentials to set up the storage. Returns a success message with the configured provider details.

```APIDOC
## POST https://api.tornadoapi.io/user/s3

### Description
Configures an S3-compatible storage provider for downloads. Provide the endpoint, bucket, region, and credentials to set up the storage. Returns a success message with the configured provider details.

### Method
POST

### Endpoint
https://api.tornadoapi.io/user/s3

### Parameters
#### Request Body
- **endpoint** (string) - Required - The URL of the S3-compatible storage provider.
- **bucket** (string) - Required - The name of the bucket to use.
- **region** (string) - Required - The region of the bucket.
- **access_key** (string) - Required - The access key ID for authentication.
- **secret_key** (string) - Required - The secret access key for authentication.
- **folder_prefix** (string) - Optional - A folder prefix within the bucket to use.

### Request Example
{
  "endpoint": "https://s3.us-east-1.amazonaws.com",
  "bucket": "my-tornado-downloads",
  "region": "us-east-1",
  "access_key": "AKIAIOSFODNN7EXAMPLE",
  "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "folder_prefix": "videos/"
}

### Response
#### Success Response (200)
- **message** (string) - Success confirmation message.
- **provider** (string) - Storage provider type: `s3`.
- **container_or_bucket** (string) - The configured bucket name.
- **folder_prefix** (string) - The configured folder prefix (if provided).

#### Response Example
{
  "message": "S3 storage configured successfully",
  "provider": "s3",
  "container_or_bucket": "my-tornado-downloads",
  "folder_prefix": "videos/"
}
```

--------------------------------

### Configure Azure Blob Storage with Account Key (Python)

Source: https://docs.tornadoapi.io/api-reference/user/configure-blob

Uses the requests library to POST the configuration to the /user/blob endpoint with an account key. The response is printed as JSON.

```python
import requests

response = requests.post(
    "https://api.tornadoapi.io/user/blob",
    headers={"x-api-key": "sk_your_api_key"},
    json={
        "account_name": "mystorageaccount",
        "container": "tornado-downloads",
        "account_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxx=="
    }
)
print(response.json())
```

--------------------------------

### Configure S3 Storage

Source: https://docs.tornadoapi.io/api-reference/user/configure-s3

Sets up S3-compatible storage for uploaded videos. Credentials are verified before saving.

```APIDOC
## Configure S3 Storage

### Description
Sets up S3-compatible storage for uploaded videos. Credentials are verified before saving.

### Method
POST

### Endpoint
/configure-s3

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - Your API key for authentication

#### Request Body
- **endpoint** (string) - Required - S3 endpoint URL (e.g., `https://s3.us-east-1.amazonaws.com` or `https://ACCOUNT_ID.r2.cloudflarestorage.com`)
- **bucket** (string) - Required - Bucket name
- **region** (string) - Required - AWS region (e.g., `us-east-1`, `auto` for R2)
- **access_key** (string) - Required - AWS Access Key ID or equivalent
- **secret_key** (string) - Required - AWS Secret Access Key or equivalent
- **folder_prefix** (string) - Optional - Optional folder prefix for organizing uploads (e.g., `downloads/2024/`)
- **base_folder** (string) - Optional - Base folder name for uploaded files. Defaults to `videos` if not specified. Set to a custom value to change the top-level folder where files are stored (e.g., `downloads`, `media`).

### Request Example
{
  "endpoint": "https://s3.us-east-1.amazonaws.com",
  "bucket": "my-bucket",
  "region": "us-east-1",
  "access_key": "AKIA...",
  "secret_key": "...",
  "folder_prefix": "downloads/2024/",
  "base_folder": "videos"
}

### Response
#### Success Response (200)
- **message** (string) - Success message indicating storage configured successfully.

#### Response Example
{
  "message": "S3 storage configured successfully"
}
```
Tokens:
Raw