INTEGRITY Документация

← Cloudflare Stream / stream / manage-video-library

Привязка к Workers API

A привязка подключает ваш Worker на внешние ресурсы на Developer Platform, например Stream, Бакеты R2, или Пространства имён KV.

Например, используя Stream в Workers, вы можете:

Настройка

Привязка Stream включается отдельно для каждого Worker.

Чтобы привязать Stream к вашему Worker, добавьте следующее в конец файла конфигурации Wrangler:

{
	"stream": {
		"binding": "STREAM"
	}
}
[stream]
binding = "STREAM"

Подробную информацию о настройке Worker см. в Документация по конфигурации Wrangler.

Методы

Методы уровня привязки

Следующие методы доступны в объекте env.STREAM binding напрямую.

upload(url, params?)

Загрузка видео по URL-адресу. Возвращает Promise<StreamVideo>.

Выбрасывает исключение: BadRequestError, QuotaReachedError, MaxFileSizeError, RateLimitedError, AlreadyUploadedError, InternalError.

createDirectUpload(params)

Создайте базовый URL прямой загрузки для клиентских загрузок без API-ключа. Возвращает Promise<StreamDirectUpload> с uploadURL и id.

Этот метод пока не поддерживает файлы размером более 200 МБ. Для больших прямых загрузок см. Запрос API для создания конечной точки TUS ↗._

videos.list(params?)

Список всех видео в аккаунте. Возвращает Promise<StreamVideo[]>.

Методы на уровне видео

Вызов env.STREAM.video(id) возвращает дескриптор, привязанный к одному видео, со следующими методами.

details()

Получение полной информации о видео. Возвращает Promise<StreamVideo>.

update(params)

Обновление метаданных видео. Возвращает Promise<StreamVideo>.

delete()

Удалите видео и его копии. Возвращает Promise<void>.

generateToken()

Создайте токен подписанного URL для видео. Возвращает Promise<string>.

downloads

Пространство имён для операций скачивания видео.

captions

Пространство имён для операций с субтитрами видео.

Методы работы с водяными знаками

Следующие методы доступны в объекте env.STREAM.watermarks пространство имён.

watermarks.generate(input, params)

Создайте профиль водяного знака. Принимает либо ReadableStream или строка URL. Возвращает Promise<StreamWatermark>.

watermarks.list()

Список всех профилей водяных знаков. Возвращает Promise<StreamWatermark[]>.

watermarks.get(watermarkId)

Получение одного профиля водяного знака. Возвращает Promise<StreamWatermark>.

watermarks.delete(watermarkId)

Удалите профиль водяного знака. Возвращает Promise<void>.

Примеры

Загрузка видео по URL-адресу

export default {
	async fetch(request, env) {
		const video = await env.STREAM.upload("https://example.com/video.mp4", {
			creator: "user-123",
			meta: { category: "tutorial" },
			allowedOrigins: ["example.com"],
		});
		return Response.json(video);
	},
};
export default {
	async fetch(request, env) {
		const video = await env.STREAM.upload("https://example.com/video.mp4", {
			creator: "user-123",
			meta: { category: "tutorial" },
			allowedOrigins: ["example.com"],
		});
		return Response.json(video);
	},
};

Создание прямой загрузки

export default {
	async fetch(request, env) {
		const directUpload = await env.STREAM.createDirectUpload({
			maxDurationSeconds: 300,
			creator: "user-123",
			meta: { source: "browser-upload" },
		});
		return Response.json(directUpload);
	},
};
export default {
	async fetch(request, env) {
		const directUpload = await env.STREAM.createDirectUpload({
			maxDurationSeconds: 300,
			creator: "user-123",
			meta: { source: "browser-upload" },
		});
		return Response.json(directUpload);
	},
};

Список видео

export default {
	async fetch(request, env) {
		const videos = await env.STREAM.videos.list({
			limit: 10,
			after: "2025-01-01T00:00:00Z",
		});
		return Response.json(videos);
	},
};
export default {
	async fetch(request, env) {
		const videos = await env.STREAM.videos.list({
			limit: 10,
			after: "2025-01-01T00:00:00Z",
		});
		return Response.json(videos);
	},
};

Получение информации о видео

export default {
	async fetch(request, env) {
		const videoDetails = await env.STREAM.video("VIDEO_ID").details();
		return Response.json(videoDetails);
	},
};
export default {
	async fetch(request, env) {
		const videoDetails = await env.STREAM.video("VIDEO_ID").details();
		return Response.json(videoDetails);
	},
};

Обновление метаданных видео

export default {
	async fetch(request, env) {
		const videoDetails = await env.STREAM.video("VIDEO_ID").update({
			meta: { category: "updated-tutorial" },
			allowedOrigins: ["example.com", "*.example.com"],
		});
		return Response.json(videoDetails);
	},
};
export default {
	async fetch(request, env) {
		const videoDetails = await env.STREAM.video("VIDEO_ID").update({
			meta: { category: "updated-tutorial" },
			allowedOrigins: ["example.com", "*.example.com"],
		});
		return Response.json(videoDetails);
	},
};

Удаление видео

export default {
	async fetch(request, env) {
		await env.STREAM.video("VIDEO_ID").delete();
		return new Response("Video deleted", { status: 200 });
	},
};
export default {
	async fetch(request, env) {
		await env.STREAM.video("VIDEO_ID").delete();
		return new Response("Video deleted", { status: 200 });
	},
};

Создание токена подписанного URL-адреса

export default {
	async fetch(request, env) {
		const token = await env.STREAM.video("VIDEO_ID").generateToken();
		return Response.json({ token });
	},
};
export default {
	async fetch(request, env) {
		const token = await env.STREAM.video("VIDEO_ID").generateToken();
		return Response.json({ token });
	},
};

Загрузка субтитров

export default {
	async fetch(request, env) {
		const captionResponse = await fetch("https://example.com/captions-en.vtt");
		const caption = await env.STREAM.video("VIDEO_ID").captions.upload(
			"en",
			captionResponse.body,
		);
		return Response.json(caption);
	},
};
export default {
	async fetch(request, env) {
		const captionResponse = await fetch("https://example.com/captions-en.vtt");
		const caption = await env.STREAM.video("VIDEO_ID").captions.upload(
			"en",
			captionResponse.body,
		);
		return Response.json(caption);
	},
};

Создание субтитров с помощью ИИ

export default {
	async fetch(request, env) {
		const caption = await env.STREAM.video("VIDEO_ID").captions.generate("en");
		return Response.json(caption);
	},
};
export default {
	async fetch(request, env) {
		const caption = await env.STREAM.video("VIDEO_ID").captions.generate("en");
		return Response.json(caption);
	},
};

Просмотр и удаление субтитров

export default {
	async fetch(request, env) {
		const video = env.STREAM.video("VIDEO_ID");
		const captions = await video.captions.list();
		await video.captions.delete("en");
		return Response.json(captions);
	},
};
export default {
	async fetch(request, env) {
		const video = env.STREAM.video("VIDEO_ID");
		const captions = await video.captions.list();
		await video.captions.delete("en");
		return Response.json(captions);
	},
};

Создание и просмотр списка загрузок

export default {
	async fetch(request, env) {
		const video = env.STREAM.video("VIDEO_ID");
		const downloads = await video.downloads.generate();
		const audioDownloads = await video.downloads.generate("audio");
		const allDownloads = await video.downloads.get();
		return Response.json({ downloads, audioDownloads, allDownloads });
	},
};
export default {
	async fetch(request, env) {
		const video = env.STREAM.video("VIDEO_ID");
		const downloads = await video.downloads.generate();
		const audioDownloads = await video.downloads.generate("audio");
		const allDownloads = await video.downloads.get();
		return Response.json({ downloads, audioDownloads, allDownloads });
	},
};

Создание профиля водяного знака

export default {
	async fetch(request, env) {
		const watermark = await env.STREAM.watermarks.generate(
			"https://example.com/watermark.png",
			{
				name: "My Watermark",
				opacity: 0.5,
				position: "lowerRight",
				padding: 0.05,
				scale: 0.1,
			},
		);
		return Response.json(watermark);
	},
};
export default {
	async fetch(request, env) {
		const watermark = await env.STREAM.watermarks.generate(
			"https://example.com/watermark.png",
			{
				name: "My Watermark",
				opacity: 0.5,
				position: "lowerRight",
				padding: 0.05,
				scale: 0.1,
			},
		);
		return Response.json(watermark);
	},
};

Просмотр и удаление профилей водяных знаков

export default {
	async fetch(request, env) {
		const watermarks = await env.STREAM.watermarks.list();
		const watermark = await env.STREAM.watermarks.get("WATERMARK_ID");
		await env.STREAM.watermarks.delete("WATERMARK_ID");
		return Response.json({ watermarks, watermark });
	},
};
export default {
	async fetch(request, env) {
		const watermarks = await env.STREAM.watermarks.list();
		const watermark = await env.STREAM.watermarks.get("WATERMARK_ID");
		await env.STREAM.watermarks.delete("WATERMARK_ID");
		return Response.json({ watermarks, watermark });
	},
};

Определения типов

StreamVideo

StreamVideo возвращается операциями получения или создания видео. Он содержит полные метаданные видео.

StreamVideoStatus

Информация о статусе обработки видео.

StreamVideoInput

Метаданные исходной загрузки.

StreamPublicDetails

Публичные данные, связанные с видео.

StreamDirectUpload

Возвращается createDirectUpload(). Содержит URL-адрес загрузки и идентификатор видео для прямой загрузки.

StreamCaption

Представляет собой дорожку субтитров или подписей для видео.

StreamDownloadGetResponse

Объект, ключами которого являются типы загрузок. Каждый ключ необязателен и присутствует только в том случае, если загрузка этого типа была создана.

StreamDownload

Представляет собой сформированную загрузку видео.

StreamWatermark

Представляет собой профиль водяного знака.

StreamWatermarkPosition

Положение водяного знака на видео.

'upperRight' | 'upperLeft' | 'lowerLeft' | 'lowerRight' | 'center'

StreamDownloadStatus

Статус сформированного файла для скачивания.

'ready' | 'inprogress' | 'error'

StreamDownloadType

Тип создаваемой загрузки.

'default' | 'audio'

StreamUrlUploadParams

Параметры для загрузки видео по URL.

StreamDirectUploadCreateParams

Параметры для создания прямой загрузки.

StreamDirectUploadWatermark

Настройка водяного знака для прямой загрузки.

StreamUpdateVideoParams

Параметры для обновления видео.

StreamVideosListParams

Параметры для получения списка видео.

StreamPaginationComparison

Операторы сравнения для запросов пагинации.

'eq' | 'gt' | 'gte' | 'lt' | 'lte'

StreamWatermarkCreateParams

Параметры для создания профиля водяного знака.

Обработка ошибок

При ошибке выбрасывается StreamError, который расширяет стандартный Error интерфейс с дополнительной информацией:

Могут возникать следующие подтипы ошибок:

Тип ошибки Описание
InternalError Произошла внутренняя ошибка сервера.
BadRequestError Запрос был некорректно составлен или содержал недопустимые параметры.
NotFoundError Запрошенный ресурс не найден.
ForbiddenError Запрос не был авторизован.
RateLimitedError Запрос был отклонён из-за превышения лимита частоты запросов.
QuotaReachedError Аккаунт достиг лимита по количеству видео.
MaxFileSizeError Загруженный файл превышает максимально допустимый размер.
InvalidURLError Указанный URL недействителен или недоступен.
AlreadyUploadedError Видео уже загружено.
TooManyWatermarksError Аккаунт достиг лимита профилей водяных знаков.

Используйте try...catch блок для обработки ошибок:

export default {
	async fetch(request, env) {
		try {
			const videoDetails = await env.STREAM.upload(
				"https://example.com/video.mp4",
			);
			return Response.json(videoDetails);
		} catch (e) {
			if (e instanceof Error) {
				return new Response(`Stream error: ${e.message}`, { status: 500 });
			}
			throw e;
		}
	},
};
export default {
	async fetch(request, env) {
		try {
			const videoDetails = await env.STREAM.upload("https://example.com/video.mp4");
			return Response.json(videoDetails);
		} catch (e) {
			if (e instanceof Error) {
				return new Response(`Stream error: ${e.message}`, { status: 500 });
			}
			throw e;
		}
	},
};