ウォーターマークを適用する

Stream API でアップロードした動画に、ウォーターマークを追加できます。

動画にウォーターマークを付けるには、まずウォーターマークプロファイルを作成します。ウォーターマークプロファイルは、ウォーターマークとして使う画像とその位置を定義します。プロファイルを用意したら、動画のアップロード時にオプションとして指定できます。

クイックスタート

ウォーターマークプロファイルには多くのカスタマイズ項目があります。ただし、ほとんどの場合はデフォルトのパラメーターで十分です。詳細は下の「プロファイル」を参照してください。

手順 1: プロファイルを作成する

curl -X POST -H 'Authorization: Bearer <API_TOKEN>' \
-F file=@/Users/rchen/cloudflare.png \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const watermark = await client.stream.watermarks.create({
	account_id: '<ACCOUNT_ID>',
	file: '@/path/to/image.png',
	name: 'marketing videos',
});

外部アプリケーションから REST API を使う方法と、TypeScript、Python、Go 向けの事前生成 SDK の詳細は、Stream の REST API と SDK リファレンスを参照してください。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const response = await fetch("https://example.com/cloudflare.png");
		const readableStream = response.body!;
		const watermark = await env.STREAM.watermarks.generate(readableStream, {
			name: "marketing videos",
		});
		return new Response(JSON.stringify({ watermark }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

手順 2: アップロード時にプロファイル UID を指定する

tus-upload --chunk-size 5242880 \
--header Authentication 'Bearer <API_TOKEN>' \
--metadata watermark <WATERMARK_UID> \
/Users/rchen/cat.mp4 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const video = await client.stream.copy.create({
	account_id: '<ACCOUNT_ID>',
	url: 'https://example.com/video.mp4',
	watermark: { uid: '<WATERMARK_UID>' },
});

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const video = await env.STREAM.upload(
			"https://example.com/video.mp4",
			{ watermarkId: "<WATERMARK_UID>" },
		);
		return new Response(JSON.stringify({ video }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

手順 3: 完了

プロファイル

プロファイルの作成、一覧、削除、情報取得には、 Cloudflare API トークン ↗ が必要です。

オプションパラメーター

name string default: empty string
- プロファイルの短い説明です。例: "marketing videos."
opacity float default: 1.0
- ウォーターマークの透明度です。0.0 は完全に透明、1.0 は完全に不透明です。ウォーターマーク画像自体が半透明の場合、1.0 にしても完全な不透明にはなりません。
padding float default: 0.05
- 位置で決まる動画の隣接辺と、ウォーターマークのあいだの余白です。0.0 は余白なし、1.0 は動画の幅または長さいっぱいに余白を取ります。
- Stream は、寸法の異なる動画でもウォーターマークがほぼ同じ位置になるようにします。
scale float default: 0.15
- 動画全体に対するウォーターマークのサイズです。このパラメーターは横向き動画と縦向き動画に自動で適応します。0.0 はスケールなし（ウォーターマークの元のサイズを使う）、1.0 は動画全体を埋めます。
- アルゴリズムは、寸法の異なる動画でもウォーターマークがほぼ同じ大きさに見えるようにします。
position string (enum) default: "upperRight"
- ウォーターマークの位置です。有効な値は upperRight、upperLeft、lowerLeft、lowerRight、center です。
  
  Note
  center を指定すると、padding パラメーターは無視されます。

ウォーターマークプロファイルを作成する

ユースケース 1: ローカルの画像ファイルを直接アップロードする

画像を直接アップロードするには、content-type に multipart/form-data を使い、file キーでファイルを指定して POST リクエストを送ります。ほかのフィールドはすべて任意です。

curl -X POST -H "Authorization: Bearer <API_TOKEN>" \
-F file=@{path-to-image-locally} \
-F name='marketing videos' \
-F opacity=1.0 \
-F padding=0.05 \
-F scale=0.15 \
-F position=upperRight \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const watermark = await client.stream.watermarks.create({
	account_id: '<ACCOUNT_ID>',
	file: '@/path/to/image.png',
	name: 'marketing videos',
	opacity: 1.0,
	padding: 0.05,
	scale: 0.15,
	position: 'upperRight',
});

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const response = await fetch("https://example.com/cloudflare.png");
		const readableStream = response.body!;
		const watermark = await env.STREAM.watermarks.generate(readableStream, {
			name: "marketing videos",
			opacity: 1.0,
			padding: 0.05,
			scale: 0.15,
			position: "upperRight",
		});
		return new Response(JSON.stringify({ watermark }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

ユースケース 2: 画像の URL を渡す

アップロード先を URL で指定するには、content-type に application/json を使い、url キーでファイルの場所を指定して POST リクエストを送ります。ほかのフィールドはすべて任意です。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const watermark = await env.STREAM.watermarks.generate(
			"https://example.com/logo.png",
			{
				name: "marketing videos",
				opacity: 1.0,
				padding: 0.05,
				scale: 0.15,
				position: "upperRight",
			},
		);
		return new Response(JSON.stringify({ watermark }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

curl -X POST -H "Authorization: Bearer <API_TOKEN>" \
-H 'Content-Type: application/json' \
-d '{
  "url": "{url-to-image}",
  "name": "marketing videos",
  "opacity": 1.0,
  "padding": 0.05,
  "scale": 0.15,
  "position": "upperRight"
}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

// The TypeScript SDK does not support URL-based watermark creation.
// Use the file-based approach instead:
const watermark = await client.stream.watermarks.create({
	account_id: '<ACCOUNT_ID>',
	file: '@/path/to/image.png',
	name: 'marketing videos',
	opacity: 1.0,
	padding: 0.05,
	scale: 0.15,
	position: 'upperRight',
});

ウォーターマークプロファイル作成時のレスポンス例

{
  "result": {
    "uid": "d6373709b7681caa6c48ef2d8c73690d",
    "size": 11248,
    "height": 240,
    "width": 720,
    "created": "2020-07-29T00:16:55.719265Z",
    "downloadedFrom": null,
    "name": "marketing videos",
    "opacity": 1.0,
    "padding": 0.05,
    "scale": 0.15,
    "position": "upperRight"
  },
  "success": true,
  "errors": [],
  "messages": []
}

プロファイルを URL からのダウンロードで作成した場合、downloadedFrom に値が入ります。

動画にウォーターマークプロファイルを使う

ウォーターマークプロファイルを作成したら、アップロード時に指定して動画へウォーターマークを付けられます。

Basic uploads

現時点では、Stream は Basic Uploads のアップロード時にウォーターマークプロファイルを指定できません。

リンクから動画をアップロードする

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const video = await env.STREAM.upload(
			"https://example.com/video.mp4",
			{ watermarkId: "<WATERMARK_UID>" },
		);
		return new Response(JSON.stringify({ video }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

curl -X POST -H "Authorization: Bearer <API_TOKEN>" \
-H 'Content-Type: application/json' \
-d '{
  "url": "{url-to-video}",
  "watermark": {
    "uid": "<WATERMARK_UID>"
  }
}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/copy

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const video = await client.stream.copy.create({
	account_id: '<ACCOUNT_ID>',
	url: 'https://example.com/video.mp4',
	watermark: { uid: '<WATERMARK_UID>' },
});

リンクから動画をアップロードしたときのレスポンス例

{
  "result": {
    "uid": "8d3a5b80e7437047a0fb2761e0f7a645",
    "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",

    "playback": {
      "hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
      "dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
    },
    "watermark": {
      "uid": "d6373709b7681caa6c48ef2d8c73690d",
      "size": 11248,
      "height": 240,
      "width": 720,
      "created": "2020-07-29T00:16:55.719265Z",
      "downloadedFrom": null,
      "name": "marketing videos",
      "opacity": 1.0,
      "padding": 0.05,
      "scale": 0.15,
      "position": "upperRight"
    }

}

tus で動画をアップロードする

tus-upload --chunk-size 5242880 \
--header Authentication 'Bearer <API_TOKEN>' \
--metadata watermark <WATERMARK_UID> \
<PATH_TO_VIDEO> https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream

Direct creator uploads

生成された一回限りの一意 URL でアップロードした動画には、指定したプロファイルのウォーターマークが付きます。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const directUpload = await env.STREAM.createDirectUpload({
			maxDurationSeconds: 3600,
			watermark: { id: "<WATERMARK_UID>" },
		});
		return new Response(JSON.stringify({ directUpload }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

curl -X POST -H "Authorization: Bearer <API_TOKEN>" \
-H 'Content-Type: application/json' \
-d '{
  "maxDurationSeconds": 3600,
  "watermark": {
    "uid": "<WATERMARK_UID>"
  }
}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/direct_upload

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const directUpload = await client.stream.directUpload.create({
	account_id: '<ACCOUNT_ID>',
	maxDurationSeconds: 3600,
	watermark: { uid: '<WATERMARK_UID>' },
});

ダイレクトユーザーアップロードのレスポンス例

{
  "result": {
    "uploadURL": "https://upload.videodelivery.net/c32d98dd671e4046a33183cd5b93682b",
    "uid": "c32d98dd671e4046a33183cd5b93682b",
    "watermark": {
      "uid": "d6373709b7681caa6c48ef2d8c73690d",
      "size": 11248,
      "height": 240,
      "width": 720,
      "created": "2020-07-29T00:16:55.719265Z",
      "downloadedFrom": null,
      "name": "marketing videos",
      "opacity": 1.0,
      "padding": 0.05,
      "scale": 0.15,
      "position": "upperRight"
    }
  },
  "success": true,
  "errors": [],
  "messages": []
}

ウォーターマークを指定しなかった場合、watermark は null になります。

ウォーターマークプロファイルを取得する

作成したウォーターマークプロファイルを確認する手順は次のとおりです。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const watermark = await env.STREAM.watermarks.get("<WATERMARK_UID>");
		return new Response(JSON.stringify({ watermark }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

curl -H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks/<WATERMARK_UID>

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const watermark = await client.stream.watermarks.get(
	'<WATERMARK_UID>',
	{ account_id: '<ACCOUNT_ID>' },
);

ウォーターマークプロファイル取得時のレスポンス例

{
  "result": {
    "uid": "d6373709b7681caa6c48ef2d8c73690d",
    "size": 11248,
    "height": 240,
    "width": 720,
    "created": "2020-07-29T00:16:55.719265Z",
    "downloadedFrom": null,
    "name": "marketing videos",
    "opacity": 1.0,
    "padding": 0.05,
    "scale": 0.15,
    "position": "center"
  },
  "success": true,
  "errors": [],
  "messages": []
}

ウォーターマークプロファイルを一覧する

作成したウォーターマークプロファイルを一覧する手順は次のとおりです。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const watermarks = await env.STREAM.watermarks.list();
		return new Response(JSON.stringify({ watermarks }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

curl -H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks/

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const watermarks = await client.stream.watermarks.list({
	account_id: '<ACCOUNT_ID>',
});

ウォーターマークプロファイル一覧時のレスポンス例

{
  "result": [
    {
      "uid": "9de16afa676d64faaa7c6c4d5047e637",
      "size": 207710,
      "height": 626,
      "width": 1108,
      "created": "2020-07-29T00:23:35.918472Z",
      "downloadedFrom": null,
      "name": "marketing videos",
      "opacity": 1.0,
      "padding": 0.05,
      "scale": 0.15,
      "position": "upperLeft"
    },
    {
      "uid": "9c50cff5ab16c4aec0bcb03c44e28119",
      "size": 207710,
      "height": 626,
      "width": 1108,
      "created": "2020-07-29T00:16:46.735377Z",
      "downloadedFrom": "https://company.com/logo.png",
      "name": "internal training videos",
      "opacity": 1.0,
      "padding": 0.05,
      "scale": 0.15,
      "position": "center"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

ウォーターマークプロファイルを削除する

作成したウォーターマークプロファイルを削除する手順は次のとおりです。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		await env.STREAM.watermarks.delete("<WATERMARK_UID>");
		return new Response(JSON.stringify({ success: true }));
	},
} satisfies ExportedHandler<{ STREAM: StreamBinding }>;

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

詳細は Workers Stream binding API リファレンスを参照してください。

curl -X DELETE -H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks/<WATERMARK_UID>

const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

await client.stream.watermarks.delete(
	'<WATERMARK_UID>',
	{ account_id: '<ACCOUNT_ID>' },
);

操作が成功すると、次のような成功レスポンスが返ります。

{
  "result": "",
  "success": true,
  "errors": [],
  "messages": []
}

制限

ウォーターマークプロファイルを作成したあと、パラメーターは変更できません。プロファイルを編集する必要がある場合は、削除して新しいプロファイルを作成してください。
動画にウォーターマークを適用したあと、別のプロファイルを適用するには動画を再アップロードする必要があります。
動画にウォーターマークを適用したあと、プロファイルを削除しても、動画からウォーターマークは取り除かれません。
最大ファイルサイズは 2MiB（2097152 バイト）で、対応しているのは PNG ファイルだけです。