1# Stream API Reference
2 
3Upload, playback, live streaming, and management APIs.
4 
5## Upload APIs
6 
7### Direct Creator Upload (Recommended)
8 
9**Backend: Create upload URL (SDK)**
10```typescript
11import Cloudflare from 'cloudflare';
12 
13const client = new Cloudflare({ apiToken: env.CF_API_TOKEN });
14 
15const uploadData = await client.stream.directUpload.create({
16  account_id: env.CF_ACCOUNT_ID,
17  maxDurationSeconds: 3600,
18  requireSignedURLs: true,
19  meta: { creator: 'user-123' }
20});
21// Returns: { uploadURL: string, uid: string }
22```
23 
24**Frontend: Upload file**
25```typescript
26async function uploadVideo(file: File, uploadURL: string) {
27  const formData = new FormData();
28  formData.append('file', file);
29  return fetch(uploadURL, { method: 'POST', body: formData }).then(r => r.json());
30}
31```
32 
33### Upload from URL
34 
35```typescript
36const video = await client.stream.copy.create({
37  account_id: env.CF_ACCOUNT_ID,
38  url: 'https://example.com/video.mp4',
39  meta: { name: 'My Video' },
40  requireSignedURLs: false
41});
42```
43 
44## Playback APIs
45 
46### Embed Player (iframe)
47 
48```html
49<iframe
50  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/iframe?autoplay=true&muted=true"
51  style="border: none;" height="720" width="1280"
52  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
53  allowfullscreen="true"
54></iframe>
55```
56 
57### HLS/DASH Manifest URLs
58 
59```typescript
60// HLS
61const hlsUrl = `https://customer-<CODE>.cloudflarestream.com/${videoId}/manifest/video.m3u8`;
62 
63// DASH
64const dashUrl = `https://customer-<CODE>.cloudflarestream.com/${videoId}/manifest/video.mpd`;
65```
66 
67### Thumbnails
68 
69```typescript
70// At specific time (seconds)
71const thumb = `https://customer-<CODE>.cloudflarestream.com/${videoId}/thumbnails/thumbnail.jpg?time=10s`;
72 
73// By percentage
74const thumbPct = `https://customer-<CODE>.cloudflarestream.com/${videoId}/thumbnails/thumbnail.jpg?time=50%`;
75 
76// Animated GIF
77const gif = `https://customer-<CODE>.cloudflarestream.com/${videoId}/thumbnails/thumbnail.gif`;
78```
79 
80## Signed URLs
81 
82```typescript
83// Low volume (<1k/day): Use API
84async function getSignedToken(accountId: string, videoId: string, apiToken: string) {
85  const response = await fetch(
86    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/token`,
87    {
88      method: 'POST',
89      headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
90      body: JSON.stringify({
91        exp: Math.floor(Date.now() / 1000) + 3600,
92        accessRules: [{ type: 'ip.geoip.country', action: 'allow', country: ['US'] }]
93      })
94    }
95  );
96  return (await response.json()).result.token;
97}
98 
99// High volume: Self-sign with RS256 JWT (see "Self-Sign JWT" in patterns.md)
100```
101 
102## Captions & Clips
103 
104### Upload Captions
105 
106```typescript
107async function uploadCaption(
108  accountId: string, videoId: string, apiToken: string,
109  language: string, captionFile: File
110) {
111  const formData = new FormData();
112  formData.append('file', captionFile);
113  return fetch(
114    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/captions/${language}`,
115    {
116      method: 'PUT',
117      headers: { 'Authorization': `Bearer ${apiToken}` },
118      body: formData
119    }
120  ).then(r => r.json());
121}
122```
123 
124### Generate AI Captions
125 
126```typescript
127// TODO: Requires Workers AI integration - see workers-ai reference
128async function generateAICaptions(accountId: string, videoId: string, apiToken: string) {
129  return fetch(
130    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/captions/generate`,
131    {
132      method: 'POST',
133      headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
134      body: JSON.stringify({ language: 'en' })
135    }
136  ).then(r => r.json());
137}
138```
139 
140### Clip Video
141 
142```typescript
143async function clipVideo(
144  accountId: string, videoId: string, apiToken: string,
145  startTime: number, endTime: number
146) {
147  return fetch(
148    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/clip`,
149    {
150      method: 'POST',
151      headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
152      body: JSON.stringify({
153        clippedFromVideoUID: videoId,
154        startTimeSeconds: startTime,
155        endTimeSeconds: endTime
156      })
157    }
158  ).then(r => r.json());
159}
160```
161 
162## Video Management
163 
164```typescript
165// List videos
166const videos = await client.stream.videos.list({
167  account_id: env.CF_ACCOUNT_ID,
168  search: 'keyword' // optional
169});
170 
171// Get video details
172const video = await client.stream.videos.get(videoId, {
173  account_id: env.CF_ACCOUNT_ID
174});
175 
176// Update video
177await client.stream.videos.update(videoId, {
178  account_id: env.CF_ACCOUNT_ID,
179  meta: { title: 'New Title' },
180  requireSignedURLs: true
181});
182 
183// Delete video
184await client.stream.videos.delete(videoId, {
185  account_id: env.CF_ACCOUNT_ID
186});
187```
188 
189## In This Reference
190 
191- [README.md](./README.md) - Overview and quick start
192- [configuration.md](./configuration.md) - Setup and config
193- [api-live.md](./api-live.md) - Live streaming APIs (RTMPS/SRT/WebRTC)
194- [patterns.md](./patterns.md) - Full-stack flows, best practices
195- [gotchas.md](./gotchas.md) - Error codes, troubleshooting
196 
197## See Also
198 
199- [workers](../workers/) - Deploy Stream APIs in Workers
200