Stream

Upload, manage, and deliver videos with Cloudflare Stream

Cloudflare Stream is a video streaming platform that handles encoding, storage, and delivery. The Stream API allows you to upload and manage videos programmatically.

Upload a video

Initiates a video upload using the TUS protocol.

await client.stream.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  body: {},
  'Tus-Resumable': '1.0.0',
  'Upload-Length': 1024000,
});

account_id · string · required

The account identifier

Tus-Resumable · string · required

TUS protocol version (set to “1.0.0”)

Upload-Length · number · required

The size of the upload in bytes

Upload-Metadata · string

Base64-encoded metadata about the upload

Upload-Creator · string

A user-defined identifier for the media creator

direct_user · string

The user ID for direct upload

List videos

Lists up to 1000 videos from a single request.

for await (const video of client.stream.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(video.uid, video.meta?.name);
}

account_id · string · required

The account identifier

creator · string

Filter by creator ID

search · string

Search videos by name

start · string

Start of the range (RFC 3339 timestamp)

end · string

End of the range (RFC 3339 timestamp)

include_counts · boolean

Include total count of videos

uid · string

The unique video identifier

allowedOrigins · array

List of origins allowed to display the video

created · string

The date and time the video was created

duration · number

The duration of the video in seconds (-1 if unknown)

meta · object

User modifiable key-value store for managing videos

readyToStream · boolean

Indicates whether the video is playable

status · object

Video processing status

thumbnail · string

URL of the video thumbnail

preview · string

The video’s preview page URI

Get a video

Fetches details for a single video.

const video = await client.stream.get(
  'ea95132c15732412d22c1476fa83f27a',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

identifier · string · required

The video identifier

account_id · string · required

The account identifier

Edit a video

Edit details for a single video.

const video = await client.stream.edit(
  'ea95132c15732412d22c1476fa83f27a',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    meta: {
      name: 'My Updated Video',
      description: 'A great video',
    },
    allowedOrigins: ['example.com'],
  },
);

identifier · string · required

The video identifier

account_id · string · required

The account identifier

meta · object

User modifiable key-value metadata

allowedOrigins · array

List of allowed origin domains. Use ["*"] for wildcard.

requireSignedURLs · boolean

Whether the video requires signed URLs for viewing

thumbnailTimestampPct · number

The timestamp percentage for the video thumbnail (0.0 to 1.0)

Delete a video

Deletes a video and its copies from Cloudflare Stream.

await client.stream.delete(
  'ea95132c15732412d22c1476fa83f27a',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

identifier · string · required

The video identifier

account_id · string · required

The account identifier

Direct uploads

Create a unique one-time upload URL for direct user uploads.

const upload = await client.stream.directUpload.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  maxDurationSeconds: 3600,
  requireSignedURLs: true,
  allowedOrigins: ['example.com'],
});

account_id · string · required

The account identifier

maxDurationSeconds · number

Maximum video duration in seconds

requireSignedURLs · boolean

Whether uploaded videos require signed URLs

allowedOrigins · array

Origins allowed to display the uploaded videos

meta · object

Metadata to associate with the uploaded video

expiry · string

Expiration time for the upload URL (RFC 3339)

Live inputs

Manage live streaming inputs.

// Create a live input
const liveInput = await client.stream.liveInputs.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  meta: { name: 'My Live Stream' },
  recording: {
    mode: 'automatic',
  },
});

// List live inputs
for await (const input of client.stream.liveInputs.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(input.uid, input.meta?.name);
}

// Get a live input
const input = await client.stream.liveInputs.get(
  'live_input_id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

Watermarks

Manage video watermarks.

// Upload a watermark
const watermark = await client.stream.watermarks.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: watermarkFile,
});

// List watermarks
for await (const watermark of client.stream.watermarks.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(watermark.uid);
}

// Delete a watermark
await client.stream.watermarks.delete(
  'watermark_id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

Captions and subtitles

Manage video captions.

// Get captions for a video
for await (const caption of client.stream.captions.get({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  identifier: 'video_id',
})) {
  console.log(caption.language);
}

Audio tracks

Manage multiple audio tracks for videos.

// Copy audio from another video
const audio = await client.stream.audioTracks.copy({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  identifier: 'destination_video_id',
  audio: {
    source_video_id: 'source_video_id',
  },
});

// Delete an audio track
await client.stream.audioTracks.delete(
  'video_id',
  'audio_track_id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

Webhooks

Manage webhooks for Stream events.

// Get webhook configuration
const webhook = await client.stream.webhooks.get({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

// Update webhook
await client.stream.webhooks.update({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  notificationUrl: 'https://example.com/webhook',
});

// Delete webhook
await client.stream.webhooks.delete({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

Signing keys

Manage signing keys for signed URLs.

// Create a signing key
const key = await client.stream.keys.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

// List signing keys
for await (const key of client.stream.keys.get({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(key.id);
}

// Delete a signing key
await client.stream.keys.delete(
  'key_id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

Downloads

Manage video downloads.

// Create a download
const download = await client.stream.downloads.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  identifier: 'video_id',
});

// Get download status
const status = await client.stream.downloads.get({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  identifier: 'video_id',
});

// Delete downloads
await client.stream.downloads.delete({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  identifier: 'video_id',
});

Get storage usage

Get information about video storage usage.

const usage = await client.stream.videos.storageUsage({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  creator: 'creator_id',
});