跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

添加字幕

最后更新 查看 MarkdownAgent 设置

为您的视频库添加字幕。

添加或修改字幕

有两种方式为视频添加字幕：通过 AI 生成或上传字幕文件。

要在视频上创建或修改字幕，需要 Cloudflare API Token ↗。

<LANGUAGE_TAG> 必须遵循 BCP 47 格式 ↗. 为方便起见，文档底部提供了许多常用语言代码。 如果您添加的语言不在表格中，可以通过维护语言代码列表的 IANA 注册表 ↗ 查找要发送的值。搜索该语言即可。以下是在 IANA 中查找土耳其语字幕要发送的值时的示例：

%%

Subtag: tr
Description: Turkish
Added: 2005-10-16
Suppress-Script: Latn
%%

Subtag 代码表示值为 tr。这是您应在 HTTP 请求末尾作为 language 发送的值。

根据提供的语言生成标签。标签将在播放器中供用户选择时可见。例如，如果发送 tr，将创建标签 Türkçe；如果发送 de，将创建标签 Deutsch。

生成字幕

生成的字幕使用基于 AI 的语音转文本技术为您的视频生成隐藏式字幕。

视频必须先上传并处于 ready 状态才能生成字幕。 在以下示例 URL 中，视频的 UID 表示为 <VIDEO_UID>。 要在上传后视频变为 ready 时接收 webhook，请按照使用 webhook.

可为以下语言生成字幕：

  • cs - Czech
  • nl - Dutch
  • en - English
  • fr - French
  • de - German
  • it - Italian
  • ja - Japanese
  • ko - Korean
  • pl - Polish
  • pt - Portuguese
  • ru - Russian
  • es - Spanish

生成字幕时，请为音频中的口语语言生成。

视频可以包含多种语言的字幕，但每种语言必须唯一。 例如，视频可以关联英语、法语和德语字幕，但不能有两个英语字幕。如果您已为视频上传英文字幕，必须先删除它才能创建英文生成字幕。删除字幕的说明见下文。

<LANGUAGE_TAG> 必须遵循 BCP 47 格式。英语的标签为 en。 您可以在标签中指定地区，例如 en-GB，将渲染显示 British English 的字幕标签。

curl -X POST \
-H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>/generate
const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const caption = await client.stream.captions.language.create("<VIDEO_UID>", "en", {
	account_id: '<ACCOUNT_ID>',
});

请参阅完整的 Stream REST API 和 SDK 参考，了解如何从外部应用程序使用 REST API，以及适用于外部 TypeScript、Python 或 Go 应用的预生成 SDK。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const videoId = "<VIDEO_UID>";
		const caption = await env.STREAM.video(videoId).captions.generate("en");
		return new Response(JSON.stringify({ caption }));
	},
} 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 绑定 API 参考。

示例响应：

{
  "result": {
    "language": "en",
    "label": "English (auto-generated)",
    "generated": true,
    "status": "inprogress"
  },
  "success": true,
  "errors": [],
  "messages": []
}

结果将提供表示字幕生成进度的 status。
有三种状态：inprogress、ready 和 error。注意标签中会附加 (auto-generated)。

生成的字幕就绪后，将自动出现在视频播放器和视频 manifest 中。

如果字幕进入 error 状态，可以先删除它，然后使用上述端点尝试重新生成。 删除说明见下文。

上传文件

如果编辑生成的字幕，请注意两处变化：generated 字段将变为 false，标签中的 (auto-generated) 部分将被移除。

要创建或替换字幕文件：

curl -X PUT \
 -H 'Authorization: Bearer <API_TOKEN>' \
 -F file=@/Users/mickie/Desktop/example_caption.vtt \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>
const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const caption = await client.stream.captions.language.update("<VIDEO_UID>", "en", {
	account_id: '<ACCOUNT_ID>',
	file: '@/path/to/caption.vtt',
});

请参阅完整的 Stream REST API 和 SDK 参考，了解如何从外部应用程序使用 REST API，以及适用于外部 TypeScript、Python 或 Go 应用的预生成 SDK。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const videoId = "<VIDEO_UID>";
		const language = "en";
		// Obtain a ReadableStream from a file upload, fetch, or other source
		const captionStream: ReadableStream = request.body!;
		const caption = await env.STREAM.video(videoId).captions.upload(language, captionStream);
		return new Response(JSON.stringify({ caption }));
	},
} 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 绑定 API 参考。

添加或修改字幕的示例响应

{
  "result": {
    "language": "en",
    "label": "English",
    "generated": false,
    "status": "ready"
  },
  "success": true,
  "errors": [],
  "messages": []
}

列出与视频关联的字幕

要查看与视频关联的字幕。 注意此结果列表还将包括处于 inprogress 和 error 状态的生成字幕：

curl -H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions
const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

const captions = await client.stream.captions.get("<VIDEO_UID>", {
	account_id: '<ACCOUNT_ID>',
});

请参阅完整的 Stream REST API 和 SDK 参考，了解如何从外部应用程序使用 REST API，以及适用于外部 TypeScript、Python 或 Go 应用的预生成 SDK。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const videoId = "<VIDEO_UID>";
		const captions = await env.STREAM.video(videoId).captions.list();
		return new Response(JSON.stringify({ captions }));
	},
} 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 绑定 API 参考。

获取与视频关联的字幕的示例响应

{
  "result": [
    {
      "language": "en",
      "label": "English (auto-generated)",
      "generated": true,
      "status": "inprogress"
    },
    {
      "language": "de",
      "label": "Deutsch",
      "generated": false,
      "status": "ready"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

获取字幕文件

要查看 WebVTT 字幕文件，可以发送 GET 请求：

curl \
-H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>/vtt

获取视频字幕文件的示例响应

WEBVTT

1
00:00:00.000 --> 00:00:01.560
This is an example of

2
00:00:01.560 --> 00:00:03.880
a WebVTT caption response.

删除字幕

要删除与视频关联的字幕：

curl -X DELETE \
 -H 'Authorization: Bearer <API_TOKEN>' \
 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>
const client = new Cloudflare({
	apiEmail: process.env['CLOUDFLARE_EMAIL'],
	apiKey: process.env['CLOUDFLARE_API_KEY'],
});

await client.stream.captions.language.delete("<VIDEO_UID>", "en", {
	account_id: '<ACCOUNT_ID>',
});

请参阅完整的 Stream REST API 和 SDK 参考，了解如何从外部应用程序使用 REST API，以及适用于外部 TypeScript、Python 或 Go 应用的预生成 SDK。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const videoId = "<VIDEO_UID>";
		await env.STREAM.video(videoId).captions.delete("en");
		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 绑定 API 参考。

如果 errors 响应字段中有条目，字幕尚未被删除。

删除字幕的示例响应

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

限制

  • 必须先上传视频，然后才能附加字幕。在以下示例 URL 中，视频 ID 表示为 media_id。
  • Stream 仅支持 WebVTT ↗ 格式的字幕文件。如果您有不同格式的字幕文件，请在上传前使用工具将其转换为 WebVTT ↗。
  • 视频可以包含多种语言字幕，但每种语言必须唯一。 例如，视频可以关联英语、法语和德语字幕，但不能有两个法语字幕。
  • 每个字幕文件大小限制为 10 MB。如需上传更大的文件，请联系支持。

最常用语言代码

语言代码 语言
zh Mandarin Chinese
hi Hindi
es Spanish
en English
ar Arabic
pt Portuguese
bn Bengali
ru Russian
ja Japanese
de German
pa Panjabi
jv Javanese
ko Korean
vi Vietnamese
fr French
ur Urdu
it Italian
tr Turkish
fa Persian
pl Polish
uk Ukrainian
my Burmese
th Thai

这篇文档对您有帮助吗？