Quick Start

This guide walks you through the complete flow: authenticate, upload a video, wait for processing, and embed it – in under 5 minutes.

Prerequisites

You need a Streamdiver tenant with API credentials (tenantShortcode, clientId, clientSecret). Don't have one yet? Request trial access.

Step 1: Get an Access Token

Request an OAuth 2.0 token using your credentials:

curl

curl --request POST \
  --url https://sso.streamdiver.com/realms/{tenantShortcode}/protocol/openid-connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id={clientId} \
  --data client_secret={clientSecret}

Python

import requests

response = requests.post(
    "https://sso.streamdiver.com/realms/{tenantShortcode}/protocol/openid-connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "{clientId}",
        "client_secret": "{clientSecret}",
    },
)
token = response.json()["access_token"]

TypeScript

const response = await fetch(
  "https://sso.streamdiver.com/realms/{tenantShortcode}/protocol/openid-connect/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: "{clientId}",
      client_secret: "{clientSecret}",
    }),
  }
);
const { access_token: token } = await response.json();

You'll receive a JSON response with an access_token. Use it as a Bearer token in all subsequent requests.

For details on token lifetime and refresh, see Authentication.

Step 2: Upload a Video

Create an upload and send the file with a simple PUT request:

curl

# Create the upload
curl --request POST \
  --url https://api.streamdiver.com/v2/uploads \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{ "fileName": "my-video.mp4", "type": "put" }'

# Upload the file using the URL from the response
curl -X PUT -T my-video.mp4 "{url-from-response}"

Python

import requests

# Create the upload
upload = requests.post(
    "https://api.streamdiver.com/v2/uploads",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={"fileName": "my-video.mp4", "type": "put"},
).json()

# Upload the file
upload_url = upload["data"]["input"]["url"]
with open("my-video.mp4", "rb") as f:
    requests.put(upload_url, data=f)

TypeScript

// Create the upload
const upload = await fetch("https://api.streamdiver.com/v2/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ fileName: "my-video.mp4", type: "put" }),
}).then((r) => r.json());

// Upload the file
const uploadUrl = upload.data.input.url;
await fetch(uploadUrl, { method: "PUT", body: fileBuffer });

For large files (5GB+), use the S3 multipart procedure. See Upload for details.

Step 3: Complete the Upload

Mark the upload as complete to trigger transcoding and AI processing. Pass an optional channelId query parameter to assign the asset to a specific channel – if omitted, it goes to the default channel.

curl

curl --request PUT \
  --url "https://api.streamdiver.com/v2/uploads/{uploadId}/complete?channelId={channelId}" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json"

Python

result = requests.put(
    f"https://api.streamdiver.com/v2/uploads/{upload_id}/complete",
    params={"channelId": channel_id},
    headers={"Authorization": f"Bearer {token}"},
).json()

asset_id = result["data"]["assetId"]

TypeScript

const result = await fetch(
  `https://api.streamdiver.com/v2/uploads/${uploadId}/complete?channelId=${channelId}`,
  {
    method: "PUT",
    headers: { Authorization: `Bearer ${token}` },
  }
).then((r) => r.json());

const assetId = result.data.assetId;

The response includes the assetId – the ID of your new media asset. Streamdiver now automatically transcodes the video and runs the AI pipeline (transcription, speaker recognition, chapter generation, etc.).

Step 4: Retrieve the Media Asset

Use the assetId to fetch the media asset. The response includes processing status and the ready-to-use embed code in the player property:

curl

curl --request GET \
  --url https://api.streamdiver.com/v2/media/{assetId} \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json"

Python

asset = requests.get(
    f"https://api.streamdiver.com/v2/media/{asset_id}",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
).json()

# The embed snippet is in the player property
embed_code = asset["data"]["player"]

TypeScript

const asset = await fetch(
  `https://api.streamdiver.com/v2/media/${assetId}`,
  {
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  }
).then((r) => r.json());

// The embed snippet is in the player property
const embedCode = asset.data.player;

Processing time

Transcoding and AI processing run asynchronously. For short videos this typically takes a few minutes. Poll the asset periodically to check when it's ready.

Step 5: Publish the Channel

The widget requires the asset's channel to be public. If your channel isn't public yet, update its visibility (you only need to do this once per channel):

curl

curl --request PUT \
  --url https://api.streamdiver.com/v2/channels/{channelId}/visibility \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{ "visibility": "public" }'

Python

requests.put(
    f"https://api.streamdiver.com/v2/channels/{channel_id}/visibility",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={"visibility": "public"},
)

TypeScript

await fetch(
  `https://api.streamdiver.com/v2/channels/${channelId}/visibility`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ visibility: "public" }),
  }
);

Step 6: Embed the Player

Add the Publishing-Suite widget to any webpage – cookie-free, no consent banner required:

<link rel="stylesheet" href="https://assets.streamdiver.com/playerwidget/2/sdwebwidgets.css">
<script type="module" crossorigin src="https://assets.streamdiver.com/playerwidget/2/sdwebwidgets.js"></script>

<sd-media-widget
  tenant-name="{tenantShortcode}"
  asset-id="{assetId}">
</sd-media-widget>

Cookie-free

Unlike YouTube or Vimeo embeds, Streamdiver widgets set no cookies and require no cookie consent banner – fully GDPR-compliant out of the box.

What's Next?

• Embedding tutorial -- iframe embedding, channel embeds, and configuration parameters
• OpenAPI and Client Generation -- generate a typed client for your language
• Authentication -- token lifecycle and OAuth 2.0 details
• Upload -- S3 multipart uploads for large files
• File Import -- import from URLs, S3, or YouTube
• Chat, RAG & Flows -- ask questions about your media content
• Metadata -- explore AI-extracted entities, keywords, and speakers
• Interactive API Reference -- explore all endpoints

Related Use Cases

• Video-Hosting & Streaming -- self-hosted video platform with API-first integration