Get Upload URL

Returns presigned URLs for uploading a video directly to S3 and retrieving it for analysis.

Both URLs expire after 24 hours. The upload must be completed before the URL expires.

When to Use This Endpoint

By default, analysis endpoints read videos directly from the URL you provide. This works well if your video hosting can handle parallel requests from multiple processing workers.

Use this upload endpoint when:

Your video hosting has rate limits or cannot handle parallel requests
You want faster, more reliable processing from SportAI's infrastructure
Your videos are behind authentication that SportAI cannot access

Alternatively, if your CDN handles high parallelism well, you can skip this endpoint and pass your video URL directly to analysis endpoints with read_video_from_origin: true (the default).

To have SportAI download your video to its servers before processing, set read_video_from_origin: false in your analysis request.

Request

{
  "fileName": "match-2024-01-15.mp4",
  "contentType": "video/mp4"
}

Parameter	Type	Required	Description
`fileName`	string	Yes	Original filename with extension. Max 255 characters. Must not contain special characters (`< > : " / \
`contentType`	string	Yes	MIME type of the video file.

Supported Video Types

Format	MIME Type	Extension
MP4	`video/mp4`	`.mp4`
QuickTime	`video/quicktime`	`.mov`
AVI	`video/x-msvideo`	`.avi`
WebM	`video/webm`	`.webm`
Matroska	`video/x-matroska`	`.mkv`

Response

{
  "data": {
    "uploadUrl": "https://sportai-uploads.s3.amazonaws.com/...",
    "downloadUrl": "https://sportai-uploads.s3.amazonaws.com/..."
  }
}

{
  "error": "Unsupported video type. Allowed types: video/mp4, video/quicktime, video/x-msvideo, video/webm, video/x-matroska"
}

{
  "error": "Internal server error"
}

Field	Description
`uploadUrl`	Presigned PUT URL for uploading the video directly to S3. Valid for 24 hours.
`downloadUrl`	Presigned GET URL to use as `video_url` in analysis endpoints. Valid for 24 hours.

Usage

1. Request presigned URLs:

curl -X POST "https://api.sportai.com/api/video/upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "tennis_match.mp4",
    "contentType": "video/mp4"
  }'

import requests

response = requests.post(
    "https://api.sportai.com/api/video/upload-url",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "fileName": "tennis_match.mp4",
        "contentType": "video/mp4",
    },
)
urls = response.json()["data"]

2. Upload video to S3 using the uploadUrl:

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @/path/to/tennis_match.mp4

with open("/path/to/tennis_match.mp4", "rb") as f:
    requests.put(
        urls["uploadUrl"],
        data=f,
        headers={"Content-Type": "video/mp4"},
    )

Do not add an Authorization header when uploading to S3. The presigned URL includes authentication.

3. Use downloadUrl as the video_url in analysis endpoints:

curl -X POST "https://api.sportai.com/api/statistics/tennis" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "DOWNLOAD_URL",
    "version": "stable"
  }'

Errors

Code	Error	Cause
`400`	Invalid content type	MIME type doesn't start with `video/`
`400`	Unsupported video type	Video format not in supported list
`400`	Filename too long	Filename exceeds 255 characters
`400`	Invalid characters	Filename contains prohibited characters
`500`	Internal server error	Server-side error