Downloads

The Downloads API lets you create downloadable packages from your media library. A download can include selected media assets, specific renditions (video qualities, audio formats), and transcripts -- bundled as a single compressed archive with an optional expiry date.

Create a Download

Create a download package by specifying which assets, renditions, and transcripts to include:

curl

curl --request POST \
  --url https://api.streamdiver.com/v2/downloads \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Q4 Board Meeting Materials",
    "description": "Video recordings and transcripts from the Q4 board meeting",
    "selectedMediaIds": ["{mediaId1}", "{mediaId2}"],
    "selectedRenditionIds": ["{renditionId1}"],
    "selectedTranscripts": [
      { "id": "{transcriptId1}", "format": "srt" },
      { "id": "{transcriptId2}", "format": "txt" }
    ],
    "expires": "2025-12-31T23:59:59Z"
  }'

Python

download = requests.post(
    "https://api.streamdiver.com/v2/downloads",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "title": "Q4 Board Meeting Materials",
        "description": "Video recordings and transcripts from the Q4 board meeting",
        "selectedMediaIds": [media_id_1, media_id_2],
        "selectedRenditionIds": [rendition_id],
        "selectedTranscripts": [
            {"id": transcript_id_1, "format": "srt"},
            {"id": transcript_id_2, "format": "txt"},
        ],
        "expires": "2025-12-31T23:59:59Z",
    },
).json()

print("Download ID:", download["data"]["id"])
print("Status:", download["data"]["status"])

TypeScript

const download = await fetch("https://api.streamdiver.com/v2/downloads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Q4 Board Meeting Materials",
    description: "Video recordings and transcripts from the Q4 board meeting",
    selectedMediaIds: [mediaId1, mediaId2],
    selectedRenditionIds: [renditionId],
    selectedTranscripts: [
      { id: transcriptId1, format: "srt" },
      { id: transcriptId2, format: "txt" },
    ],
    expires: "2025-12-31T23:59:59Z",
  }),
}).then((r) => r.json());

console.log("Download ID:", download.data.id);
console.log("Status:", download.data.status);

Request Properties

Property	Type	Description
title	string	Title for the download package
description	string	Description of the contents
selectedMediaIds	string[]	Media asset IDs to include (authenticated users only)
selectedRenditionIds	string[]	Specific rendition IDs to include
selectedTranscripts	object[]	Transcripts to include, each with id and format (txt, srt, json)
expires	date-time	Expiration date in UTC (optional; tenant default is used if omitted)

info

Anonymous users are limited to a single rendition per download. Authenticated users can select multiple assets, renditions, and transcripts.

Check Download Status

After creating a download, it may need time to prepare. Poll the status until it's ready:

curl

curl --request GET \
  --url https://api.streamdiver.com/v2/downloads/{downloadId} \
  --header "Authorization: Bearer {token}"

Python

import time

while True:
    download = requests.get(
        f"https://api.streamdiver.com/v2/downloads/{download_id}",
        headers={"Authorization": f"Bearer {token}"},
    ).json()

    status = download["data"]["status"]
    if status == "ready":
        for f in download["data"]["files"]:
            print(f"Download URL: {f['url']} ({f['size']} bytes)")
        break

    print("Preparing... waiting 5s")
    time.sleep(5)

TypeScript

let status = "preparing";
while (status !== "ready") {
  const dl = await fetch(
    `https://api.streamdiver.com/v2/downloads/${downloadId}`,
    { headers: { Authorization: `Bearer ${token}` } }
  ).then((r) => r.json());

  status = dl.data.status;
  if (status === "ready") {
    dl.data.files.forEach((f) =>
      console.log(`Download URL: ${f.url} (${f.size} bytes)`)
    );
  } else {
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Status Values

Status	Description
preparing	The download is being assembled
ready	Files are available for download

When ready, the response includes files with download URLs, file sizes, and MIME types:

{
  "data": {
    "id": "{downloadId}",
    "status": "ready",
    "compressed": true,
    "files": [
      {
        "url": "https://api.streamdiver.com/v2/downloads/file/{fileId}",
        "size": 123456789,
        "mimeType": "application/zip"
      }
    ]
  }
}

List Downloads

Retrieve all downloads created by the current user:

curl --request GET \
  --url "https://api.streamdiver.com/v2/downloads?perPage=10&page=0" \
  --header "Authorization: Bearer {token}"

Delete a Download

Remove a download and its associated files:

curl --request DELETE \
  --url https://api.streamdiver.com/v2/downloads/{downloadId} \
  --header "Authorization: Bearer {token}"

Further Resources

• Interactive API Reference -- Downloads -- all download endpoints
• Transcripts & Subtitles -- find transcript IDs for download inclusion
• Metadata -- explore renditions and asset details

Related Use Cases

• E-Learning & Training -- download packages with training videos and transcripts
• Unternehmenskommunikation -- download packages for content distribution and archival