AI MediaKit 的文字滚屏工具，能够将大段文本内容与背景图片、音乐相结合，快速生成一个专业、流畅的竖版（9:16）文字滚动视频。该功能是制作小说推文、内容讲解、歌词视频等场景的绝佳选择。输出的视频为 MP4 格式。本指南将带您了解如何通过 API 调用，轻松将您的文本转换为引人入胜的滚屏视频。 ## 效果预览通过文字滚屏工具，您可以将一段纯文本、一张背景图和一段音频，转换为一个完整的视频作品。 |输入内容 |输出效果 | |---|---| |小说文本 + 一张浅色背景图片 + 一段舒缓的背景音乐 |

| ## 快速体验：生成一个基础的文字滚屏视频本节将通过一个具体的示例，演示如何调用 API，将一段小说文本生成为滚屏视频。 ### 准备工作 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。 ### 操作流程文字滚屏是一个异步任务，调用 API 的整体流程如下： 1. 成功调用 `POST /api/v1/tools/text-to-scrolling-video` 提交任务后，您将获得一个唯一的 `task_id`。 2. 您可以通过轮询 `GET /api/v1/tasks/{task_id}` 接口来查询任务状态，直到状态（`status`）变为 `completed`。或者，您也可以配置[事件回调](https://www.volcengine.com/docs/6448/2288701)自动接收任务状态变化。 3. 任务完成后，解析响应中的 `result` 字段，即可在 `video_url` 字段中获取最终生成视频的下载地址。 #### 第 1 步：提交任务您需要调用[提交文字滚屏任务 API](https://www.volcengine.com/docs/6448/2548809)。可直接复制以下 cURL 命令提交一个最基础的任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/text-to-scrolling-video' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "text": "沈兮和最爱我的那年，我无召入京，领兵谋反。我废了她的双手，挟天子以令诸侯。她悲愤绝望,隐忍卧薪。后来，她重新掌权，将我打入地牢，斩断我双手双脚，碾碎我浑身硬骨。她眉眼冷厉，一鞭甩在我肩胛：“戚乘风,这就是你背叛我的下场！”“我不会杀你，我要你此生都困在这不见天日的地牢，日日夜夜都忍受折磨。”“杀了你,未免太便宜了你！”", "image_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/background.jpg" }' ```

说明

需替换参数：

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

将 image_url 的值替换为您自己准备的背景图片 URL。

将 text 字段的内容替换为您自己的文本。

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

说明

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

当任务成功完成后，您将收到如下响应。`result` 字段中的 `video_url` 即是最终视频的下载地址。该地址的有效期为 24 小时，请务必及时下载保存。 ```JSON { "success": true, "task_id": "amk-tool-text-to-scrolling-video-123456789", "request_id": "20240521113000ABCDEFG12345", "result": { "video_url": "https://example.volcvideo.com/output.mp4?auth_key=1774504841-...", "resolution": "720p", "duration": 25.5 }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851 } ``` ## 进阶使用：自定义视频效果除了必需的文本和背景图，您还可以通过丰富的可选参数，对视频的视听效果进行精细化定制。 ### 自定义视觉元素（分辨率、字体、颜色） * `resolution`：设置视频分辨率，默认为 `720p`。示例：`"resolution": "1080p"` * `font_type`：选择预设字体，默认为 `sy_black`（思源黑体）。示例：`"font_type": "pm_zhengdao"` * `font_color`：设置文字颜色，为 8 位 RGBA 十六进制格式，默认为 `#1F1F1FFF`（不透明深灰）。示例（白色字体）：`"font_color": "#FFFFFFFF"` ### 调整滚动节奏（速度、起止停留） * `single_roll_duration`：单页文字完全滚过屏幕的时长（秒），值越小，滚动越快。默认为 `3`。示例（加快滚动）：`"single_roll_duration": 2.5` * `start_hold_duration`：视频开始时文字静止的时长（秒）。默认为 `2`。示例（立即开始滚动）：`"start_hold_duration": 0` * `end_hold_duration`：视频结束时文字静止的时长（秒）。默认为 `2`。示例（延长结尾停留）：`"end_hold_duration": 5` ### 添加背景音乐 * `audio_url`：提供背景音乐的 URL，音频将循环播放直至视频结束。示例：`"audio_url": "https://example.com/bgm.mp3"` ### **示例：创建一个定制化的滚屏视频** 以下请求将生成一个 1080p、使用“庞门正道”白色字体、滚动更快、并带有背景音乐的视频。 ```JSON { "text": "...", "image_url": "https://example.com/dark_background.png", "audio_url": "https://example.com/epic_music.mp3", "resolution": "1080p", "font_type": "pm_zhengdao", "font_color": "#FFFFFFFF", "single_roll_duration": 2.5 } ``` ## 附录：默认配置详细说明为保证开箱即用的效果，系统内置了一系列默认配置。本附录详细说明文字滚屏视频生成过程中的各项默认设置。 ### 布局与尺寸 * 输出尺寸：视频画面固定为 9:16 的竖版。您可以通过设置 `resolution` 参数来选择输出的分辨率档位。各档位对应的具体像素尺寸如下： * `360p`: 360 × 640 * `480p`: 480 × 854 * `720p`: 720 × 1280（默认） * `1080p`: 1080 × 1920 * 字体大小：字体大小会随您选择的 `resolution` 档位进行线性缩放，以确保视觉效果一致。例如，在 `720p` 分辨率下，字号约为 36px。该缩放行为由系统自动处理，不支持直接设置字号。 * 边距与间距：为保证阅读舒适性，系统内置了固定的文本边距和间距。不支持自定义。 * 左右边距：约为画布宽度的 16%。 * 行间距：20px。 * 字间距：3px。 ### 时序与滚动 * 起止停留：视频在开始滚动前和滚动结束后，会有一段静止展示的时间。您可以通过 `start_hold_duration`（默认 2 秒）和 `end_hold_duration`（默认 2 秒）参数分别进行设置。 * 滚动速度：指单页文字从进入画面到完全滚出画面所需的时间。您可以通过 `single_roll_duration` 参数进行控制，默认值为 3 秒/页。值越小，滚动越快。 * 滚动位置：文字的滚动路径为从屏幕中心附近进入，滚到中间附近结束。不支持自定义。 ### 字体与背景 * 字体颜色：您可以通过 `font_type` 参数选择预设的字体，通过 `font_color` 参数自定义设置字体颜色（默认为 `#1F1F1FFF`）。请注意，默认颜色仅适配浅色背景，若使用深色背景，请务必传入对比度足够的浅色字体（如 `#FFFFFFFF`）。 * 字体背景优化：为避免文字在滚动时边缘出现黑色毛刺或跳变，系统会自动为字体设置一个与字体颜色相同但完全透明的背景。此为系统内置的优化行为，无法关闭或修改。 * 背景图片处理（顶部/底部遮罩）：您必须传入`image_url` 提供背景图片。系统会自动裁切背景图片的顶部 10% 和底部 10% 区域，并将其作为半透明遮罩叠加在视频的顶部和底部，以增强滚屏文字的可读性。因此，请确保图片在这两个区域没有关键信息。 * 背景音乐处理：您可以通过 `audio_url` 参数提供背景音乐的 URL。音乐将循环播放，直到视频结束。如果音乐时长超过视频时长，超出部分将被自动截断。 ## 相关 API 文档 * [提交文字滚屏任务 API](https://www.volcengine.com/docs/6448/2548809) * [查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) * [事件回调](https://www.volcengine.com/docs/6448/2288701)

智能处理