AI MediaKit 视频加字幕工具支持将外部字幕文件（如 SRT、ASS）或直接提供的文本内容，以丰富的自定义样式，压制（或称“烧录”）到视频画面中，生成带内嵌字幕的新视频。本指南将带您了解如何通过 API 调用，为您的视频添加专业的内嵌字幕。 ## 效果预览通过视频加字幕工具，您可以实现以下效果： |输入视频 |输出视频（添加字幕后） | |---|---| |

| ## 快速体验：为 Vlog 视频添加内嵌字幕本节将通过一个具体的示例，演示如何直接在 API 请求中提供字幕文本和时间戳，为一段 Vlog 视频添加两句对话字幕。 ### 准备工作 1. **获取访问凭证**：在开始之前，访问 AI MediaKit 控制台 [API Key 管理页面](https://console.volcengine.com/imp/ai-mediakit/settings)，创建并获取 **AI MediaKit API Key**。 2. **准备视频文件**：准备一个需要添加字幕的视频文件，并将其上传至公网可访问的服务器或[视频点播服务](https://www.volcengine.com/docs/4/2834?lang=zh)中，以获取可供 API 调用的 URL。 ### 操作流程视频加字幕是一个异步任务，整体流程如下： 1. 成功调用 `POST /api/v1/tools/add-subtitle-to-video` 提交任务后，您将获得一个唯一的 `task_id`。 2. 您可以通过轮询 `GET /api/v1/tasks/{task_id}` 接口来查询任务状态，直到状态（`status`）变为 `completed`。或者，您也可以配置[事件回调](https://docs.volcengine.com/docs/6448/2288701)来自动接收任务完成的通知。 3. 任务完成后，解析响应中的 `result` 字段，即可在 `video_url` 字段中获取添加字幕后视频的下载地址。 #### 第 1 步：提交任务调用[提交视频加字幕任务 API](https://docs.volcengine.com/docs/6448/2372086)。您可以直接复制以下 cURL 命令，向 API 提交一个视频加字幕任务。该示例将添加两条字幕，并指定使用“站酷快乐体”。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/add-subtitle-to-video' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_vlog_video.mp4", "subtitles": [ { "subtitle_text": "大家好，欢迎来到我的 Vlog！", "start_time": 0.5, "end_time": 3.0 }, { "subtitle_text": "今天天气真不错～", "start_time": 3.5, "end_time": 5.0 } ], "subtitle_font_type": "zhanku_kuaile" }' ```

说明

需替换参数：

请将 {Your_API_Key} 替换为您的有效 API Key。

请将 video_url 的值替换为您自己准备的视频文件 URL。

您可以修改 subtitles 数组中的内容，包括文本 (subtitle_text) 和起止时间 (start_time, end_time)。

请求成功后，您会收到如下包含 `task_id` 的响应，请保存此 ID 用于后续查询。 ```JSON { "success": true, "task_id": "amk-tool-add-subtitle-to-video-123456789", "request_id": "20240520183000ABCDEFG12345" } ``` #### 第 2 步：获取结果由于视频处理需要时间，您需要通过轮询[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532) 来获取最终结果，直到任务状态变为 `completed`。 ```Bash curl -X GET 'https://mediakit.cn-beijing.volces.com/api/v1/tasks/{task_id}' \ -H 'Authorization: Bearer {Your_API_Key}' ```

说明

需替换参数：将 URL 末尾的 {task_id} 替换为第 1 步返回的任务 ID。

当任务成功完成后，您将收到如下响应。`result` 字段中的 `video_url` 即是添加字幕后视频的下载地址（默认输出为 MP4 格式，有效期为 24 小时）。 ```JSON { "success": true, "task_id": "amk-tool-add-subtitle-to-video-123456789", "task_type": "add-subtitle-to-video", "status": "completed", "result": { "video_url": "https://example.volcvideo.com/subtitled-video.mp4?auth_key=...", "resolution": "1080p", "duration": 125.4 }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851, "request_id": "1742012dcc1938455d84dbe56beb7acc" } ``` ## 进阶使用 ### 输入字幕文件添加字幕除了在请求体中直接提供字幕文本，您也可以提供一个公网可访问的字幕文件 URL（如 SRT、VTT、ASS 格式），系统会自动解析并将其添加到视频中。 ```JSON { "video_url": "https://example.com/your_movie_clip.mp4", "subtitle_url": "https://example.com/your_subtitles.srt", "subtitle_font_size": 48, "subtitle_font_color": "#FFFFFFCC" } ```

说明

当 subtitle_url 和 subtitles 参数同时存在时，系统将优先使用 subtitle_url。

### 自定义字幕样式 AI MediaKit 允许您通过丰富的 API 参数来定制字幕的视觉样式，使其与您的视频内容和品牌风格完美契合。您可以自定义字幕的位置、字体、大小、颜色，甚至应用复杂的花字效果。以下是主要的样式控制参数： * 字幕位置 (`subtitle_pos_preset`)：通过预设值快速将字幕放置在画面中的常用位置。 * `bottom_center`: 底部居中（默认） * `top_center`: 顶部居中 * `center`: 画面正中央 * `lower_third`: 偏下三分之一处 * 字体类型 (`subtitle_font_type`)：选择不同的字体以适应视频的氛围。 * `sy_black`: 思源黑体（端正百搭，正文首选） * `pm_zhengdao`: 庞门正道标题体（粗壮有力，大标题神器） * `zhanku_kuaile`: 站酷快乐体（圆润活泼，适合 Vlog 氛围） * 字体大小 (`subtitle_font_size`)：设置字幕的像素大小，默认为 `50`。 * 字体颜色 (`subtitle_font_color`)：使用 RGBA 十六进制格式（如 `#RRGGBBAA`）设置颜色和不透明度。默认值为 `#FFFFFFFF`（不透明白色）。 * 花字效果 (`subtitle_text_effect`)：指定一个花字效果资源 ID，为字幕应用描边、渐变、阴影等预设的视觉样式。设置后，`subtitle_font_color` 参数将不生效。具体效果请见[支持的花字](https://docs.volcengine.com/docs/6448/2372086#zeDVvGrvE5)。 #### 示例：应用自定义样式以下示例演示了如何将字幕设置为：使用思源黑体，48 像素大小，75% 透明度的白色（`#FFFFFFBF`），并显示在画面底部居中位置。 ```JSON { "video_url": "https://example.com/your_corporate_video.mp4", "subtitle_url": "https://example.com/your_subtitles.srt", "subtitle_pos_preset": "bottom_center", "subtitle_font_type": "sy_black", "subtitle_font_size": 48, "subtitle_font_color": "#FFFFFFBF" } ``` ## 相关 API 文档 * [提交视频加字幕任务 API](https://docs.volcengine.com/docs/6448/2372086) * [查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532) * [事件回调](https://docs.volcengine.com/docs/6448/2288701)