Downloads

You can download the clips in any playlist. Clips are identified by their playlist ID and clip_number.

Need	Endpoint	Clips	Result
One clip now	GET /download_clip	1	MP4 file
A few clips now	GET /download_clips	Up to 20	ZIP file
Many clips, or one combined video	POST /playlist_download_jobs	Up to 400	Link to a ZIP or MP4, ready in a few minutes

If you only need to play a clip, use /clip instead. Its clip_url can also be downloaded.

Download One Clip

GET /download_clip

Responds with the clip as an MP4 file download. In a browser, linking to this URL starts the download.

Parameter	Required	Type	Description
playlist_id	Yes	UUID	Playlist ID
clip_number	Yes	integer	Clip number within the playlist
audio	No	true or false	Include broadcast audio. Default false

curl --location --remote-header-name --remote-name \
  'https://api.cleaningtheglass.com/video/download_clip?playlist_id=9fbe7116-240d-4715-8019-e1b0fccb644d&clip_number=1'

The response is usually a redirect to the file. Follow redirects, as --location does above.

Download a ZIP of Clips

GET /download_clips

Responds with a ZIP file of up to 20 clips. Every clip is prepared before the ZIP starts downloading, so larger requests can take a while to start.

Parameter	Required	Type	Description
playlist_id	Yes	UUID	Playlist ID
clip_numbers	Yes	string	Comma-separated clip numbers, such as 1,2,5
audio	No	true or false	Include broadcast audio. Default false
include_xml	No	true or false	Add a Hudl Sportscode XML file. Default false

curl --remote-header-name --remote-name \
  'https://api.cleaningtheglass.com/video/download_clips?playlist_id=9fbe7116-240d-4715-8019-e1b0fccb644d&clip_numbers=1,2,5&include_xml=true'

Files in the ZIP are numbered in the order you requested them, such as 001-clip-1-....mp4, so they sort in that order.

Scenario	Response	HTTP Status
More than 20 clip numbers	"Error: direct clip downloads are limited to 20 clips"	400
A clip number is not in the playlist	"Error: clips not found: 7,9"	404

Download Jobs

POST /playlist_download_jobs

Prepares up to 400 clips in the background. You can then check the job for a download link, have the link emailed, or both. Use a download job for large downloads or to combine clips into one video.

Request

Send JSON with these fields:

Field	Required	Type	Description
playlist_id	Yes	UUID	Playlist ID
clip_numbers	One of these two	list of integers	Clip numbers to download, such as [1, 2, 5]
include_all_clips	One of these two	boolean	Download every clip in the playlist
join_clips	No	boolean	true combines the clips into one MP4. false puts each clip in a ZIP. Default false
include_xml	No	boolean	Add a Hudl Sportscode XML file. Default false
email	No	string	Also email the download link to this address

If you send clip_numbers, include_all_clips is ignored. Only the first 400 clips are downloaded. Downloaded clips do not include audio.

curl --request POST \
  --url 'https://api.cleaningtheglass.com/video/playlist_download_jobs' \
  --header 'X-API-KEY: YOUR_VIDEO_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"playlist_id": "9fbe7116-240d-4715-8019-e1b0fccb644d", "include_all_clips": true, "join_clips": true}'

Response

A new job returns 202 with a job object:

{
  "result": "Success",
  "job": {
    "id": "5d1c2b7e-3f7a-4a39-9d0e-8a5f2c6b1e40",
    "playlist_id": "9fbe7116-240d-4715-8019-e1b0fccb644d",
    "clip_numbers": [1, 2, 3],
    "join_clips": true,
    "include_xml": false,
    "email": null,
    "status": "pending",
    "download_url": null,
    "error": null
  }
}

Scenario	HTTP Status
Missing playlist_id, or neither clip_numbers nor include_all_clips	400
Playlist or clip number not found	404
The job could not be started. The response includes the failed job	502

Check a Download Job

GET /playlist_download_jobs/<job_id>

Returns the job in the same format. Check it every few seconds until status is completed or failed. This endpoint does not need an API key.

status	Meaning
pending	The job has been created
running	Clips are being prepared
uploading	The file is being uploaded
completed	download_url holds the link to the file
failed	error describes the problem

The file is:

join_clips	include_xml	File
false	either	ZIP of individual MP4 clips, plus the XML file if requested
true	false	One MP4
true	true	ZIP of one MP4 and the XML file

A clip that cannot be generated is left out of the file. The job still completes.

Sportscode XML

With include_xml, the download includes an XML file that imports into Hudl Sportscode. It has one instance per clip, labeled Clip <clip_number>. Start and end times are in seconds and run on from one clip to the next, so they mark where each clip falls in a combined video.

Email Downloads

GET /email_playlist_download_url

Prefer download jobs

This endpoint still works. A download job with an email does the same thing and lets you check its progress.

Prepares up to 400 clips and emails a download link a few minutes later. Responds with 200 and {"result": "Success"} once the download starts.

Parameter	Required	Type	Description
playlist_id	Yes	UUID	Playlist ID
email	Yes	string	Address to send the link to
join_clips	Yes	true or false	Combine the clips into one MP4
clip_number	One of these two	integer, repeatable	Clips to download, such as ?clip_number=1&clip_number=2
include_all_clips	One of these two	true or false	Download every clip in the playlist
include_xml	No	true or false	Add a Hudl Sportscode XML file