Quick Start

Tornado API retrieves media, prepares your selected output and delivers the file to your workflow. Start with one supported source URL, inspect the result and its usage, then automate the same steps. For a walkthrough from the dashboard to your first API job, read Your first media workflow. Review the allowance, rate and payment terms shown for your account before submitting work.

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

Create your account and API key

Sign in to the dashboard, complete the onboarding required for your account, then create or retrieve an API key. Keep it on your server.

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; inspect delivery details for access to the file
`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"
}

Delivery-link availability and expiry depend on the destination and its access configuration. An expired URL does not mean the file was deleted. See storage, access and retention before relying on a link for lasting access.

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