Upload with a link

If you have videos stored in a cloud storage bucket, you can pass a HTTP link for the file, and Stream will fetch the file on your behalf.

REST API
Workers Binding API

cURL
TypeScript

Make a POST request to the Stream API using the link to your video.

    curl \
    --data '{"url":"https://storage.googleapis.com/zaid-test/Watermarks%20Demo/cf-ad-original.mp4","meta":{"name":"My First Stream Video"}}' \
    --header "Authorization: Bearer <API_TOKEN>" \
    https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/copy

const client = new Cloudflare({
  apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted
  apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted
});

const video = await client.stream.copy.create({
  account_id: '<ACCOUNT_ID>',
  url: 'https://storage.googleapis.com/zaid-test/Watermarks%20Demo/cf-ad-original.mp4',
});

See the full Stream REST API and SDK reference for details on using REST API from external applications, with pre-generated SDK's for external TypeScript, Python, or Go applications.

index.ts
wrangler.jsonc

export default {
  async fetch(request, env, ctx): Promise<Response> {
    // upload a video with a link
    const videoDetails = await env.STREAM.upload(
      "https://storage.googleapis.com/zaid-test/Watermarks%20Demo/cf-ad-original.mp4",
      // (optional) attach metadata
      { meta: { name: "My First Stream Video" } }
    );

    // return a Workers response
    return new Response(
      JSON.stringify(videoDetails),
    );
  },

} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "<ENTER_WORKER_NAME>",
  "main": "src/index.ts",
  "compatibility_date": "2026-04-14",
  "observability": {
    "enabled": true
  },
  "stream": {
    "binding": "STREAM"
  }
}

See the full Workers Stream binding API reference.

If you have videos stored in a cloud storage bucket, you can pass a HTTP link for the file, and Stream will fetch the file on your behalf.

Check video status

Stream must download and encode the video, which can take a few seconds to a few minutes depending on the length of your video.

When the readyToStream value returns true, your video is ready for streaming.

You can optionally use webhooks which will notify you when the video is ready to stream or if an error occurs.

{
  "result": {
    "uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
    "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",
    "thumbnailTimestampPct": 0,
    "readyToStream": false,
    "status": {
      "state": "downloading"
    },
    "meta": {
      "downloaded-from": "https://storage.googleapis.com/zaid-test/Watermarks%20Demo/cf-ad-original.mp4",
      "name": "My First Stream Video"
    },
    "created": "2020-10-16T20:20:17.872170843Z",
    "modified": "2020-10-16T20:20:17.872170843Z",
    "size": 9032701,
    "preview": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/watch",
    "allowedOrigins": [],
    "requireSignedURLs": false,
    "uploaded": "2020-10-16T20:20:17.872170843Z",
    "uploadExpiry": null,
    "maxSizeBytes": 0,
    "maxDurationSeconds": 0,
    "duration": -1,
    "input": {
      "width": -1,
      "height": -1
    },
    "playback": {
      "hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
      "dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
    },
    "watermark": null
  },
  "success": true,
  "errors": [],
  "messages": []
}

After the video is uploaded, you can use the video uid shown in the example response above to play the video using the Stream video player.

If you are using your own player or rendering the video in a mobile app, refer to using your own player.