Skip to main content

​
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

1

Request Access

Contact us to get your API key. You’ll receive a key in the format sk_xxxxxxxxxxxxxxxx.
2

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"
3

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

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

​
Job Status Values

StatusDescription
PendingJob is queued, waiting to be processed
ProcessingJob is being downloaded/processed
CompletedJob finished successfully, s3_url is available
FailedJob failed, check error field for details
WarningJob failed due to a content issue (private video, members-only, geo-blocked)
SkippedJob 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)