Quick Start

Python SDK

The fastest way to integrate Tornado in Python:

pip install tornado-api

from tornado_api import TornadoAPI

client = TornadoAPI(api_key="sk_your_api_key")

job = client.download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(f"Download ready: {job.s3_url}")

See the full SDK documentation on GitHub.

Get Your API Key

Request Access

Test Your Key

Verify your API key works by checking your usage:

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

Download Your First Video

Create a download job:

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"}'

Basic Example

# Create a job
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"
  }'

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

import requests

API_KEY = "sk_your_api_key"
BASE_URL = "https://api.tornadoapi.io"

# Create a job
response = requests.post(
    f"{BASE_URL}/jobs",
    headers={"x-api-key": API_KEY},
    json={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
)

job_id = response.json()["job_id"]
print(f"Job created: {job_id}")

const axios = require('axios');

const API_KEY = 'sk_your_api_key';
const BASE_URL = 'https://api.tornadoapi.io';

async function downloadVideo(url) {
  const response = await axios.post(
    `${BASE_URL}/jobs`,
    { url },
    { headers: { 'x-api-key': API_KEY } }
  );

  return response.data.job_id;
}

downloadVideo('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
  .then(jobId => console.log(`Job created: ${jobId}`));

With Custom Storage

You can provide your own storage credentials directly in the request. This is required for marketplace users and optional for direct API users. See Custom Storage for all supported providers.

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",
    "storage": {
      "provider": "s3",
      "endpoint": "https://s3.us-east-1.amazonaws.com",
      "bucket": "my-videos",
      "region": "us-east-1",
      "access_key": "AKIAIOSFODNN7EXAMPLE",
      "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
  }'

import requests

API_KEY = "sk_your_api_key"
BASE_URL = "https://api.tornadoapi.io"

response = requests.post(
    f"{BASE_URL}/jobs",
    headers={"x-api-key": API_KEY},
    json={
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "format": "mp4",
        "storage": {
            "provider": "s3",
            "endpoint": "https://s3.us-east-1.amazonaws.com",
            "bucket": "my-videos",
            "region": "us-east-1",
            "access_key": "AKIAIOSFODNN7EXAMPLE",
            "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
        }
    }
)

job_id = response.json()["job_id"]
print(f"Job created: {job_id}")

const axios = require('axios');

const API_KEY = 'sk_your_api_key';
const BASE_URL = 'https://api.tornadoapi.io';

async function downloadWithStorage(url) {
  const response = await axios.post(
    `${BASE_URL}/jobs`,
    {
      url,
      format: 'mp4',
      storage: {
        provider: 's3',
        endpoint: 'https://s3.us-east-1.amazonaws.com',
        bucket: 'my-videos',
        region: 'us-east-1',
        access_key: 'AKIAIOSFODNN7EXAMPLE',
        secret_key: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
      }
    },
    { headers: { 'x-api-key': API_KEY } }
  );

  return response.data.job_id;
}

downloadWithStorage('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
  .then(jobId => console.log(`Job created: ${jobId}`));

Supported providers: s3 (AWS S3, Cloudflare R2, MinIO, etc.), blob (Azure Blob Storage), gcs (Google Cloud Storage), oss (Alibaba OSS). See full provider reference.

Poll for Completion

Jobs are processed asynchronously. Poll the status endpoint until completion:

curl -X GET "https://api.tornadoapi.io/jobs/550e8400-e29b-41d4-a716-446655440000"

import time

def wait_for_job(job_id):
    while True:
        response = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers={"x-api-key": API_KEY}
        )
        data = response.json()

        if data["status"] == "Completed":
            return data["s3_url"]
        elif data["status"] == "Failed":
            raise Exception(data["error"])

        time.sleep(2)  # Poll every 2 seconds

download_url = wait_for_job(job_id)
print(f"Download ready: {download_url}")

Job Status Values

Status	Description
`Pending`	Job is queued, waiting to be processed
`Processing`	Job is being downloaded/processed
`Completed`	Job finished successfully, `s3_url` is available
`Failed`	Job failed, check `error` field for details
`Warning`	Job failed due to a content issue (private video, members-only, geo-blocked)
`Skipped`	Job was skipped (e.g. audio-only Spotify episodes with DRM)

Response Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "status": "Completed",
  "s3_url": "https://cdn.example.com/videos/video.mp4?signature=...",
  "subtitle_url": null,
  "error": null,
  "step": "Finished"
}

The s3_url is a presigned URL valid for 24 hours. Download the file before it expires.

Next Steps

Python SDK

Official Python client with async support, polling, and webhooks

Webhooks

Get notified when jobs complete

Batch Downloads

Download entire podcast shows

Custom Storage

Use your own cloud storage (S3, Azure, GCS)

Get Started

Features

Storage guides

Integrations

Python SDK

Get Your API Key

Basic Example

With Custom Storage

Poll for Completion

Job Status Values

Response Example

Next Steps

Python SDK

Webhooks

Batch Downloads

Custom Storage

​Python SDK

​Get Your API Key

​Basic Example

​With Custom Storage

​Poll for Completion

​Job Status Values

​Response Example

​Next Steps

Python SDK

Webhooks

Batch Downloads

Custom Storage

Python SDK

Get Your API Key

Basic Example

With Custom Storage

Poll for Completion

Job Status Values

Response Example

Next Steps