POST https://mediakit.cn-beijing.volces.com/api/v1/tools/text-to-scrolling-video

本 API 用于提交一个异步的文字生成滚屏视频任务，将指定的文本内容转换为一个竖版（9:16）的文字滚动视频。该功能常用于小说推文、内容讲解、歌词视频等场景。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
text	String	是	这是一个滚屏视频的示例...\n这是新的一行。	滚屏的文本内容。文本将横排、左对齐显示。支持使用 \n 进行强制换行。若不包含 \n，文本将根据画布宽度自动换行。部分特殊字符可能需要手动转义。例如，如果您希望在视频中显示单个斜杠字符（/），则在传入 text 字段时需要输入两个斜杠（//）才能正常显示。
image_url	String	是	https://example.com/background.jpg	背景图片 URL。图片来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：jpg, png 等主流静态图片格式。为达到最佳效果，建议：图片宽高比为 9:16，与输出视频保持一致。图片分辨率尽量匹配您选择的输出视频分辨率 resolution 保持一致。图片整体基调应与 font_color 形成足够对比度。注意：图片顶部和底部的 10% 区域将被用作遮罩，请避免在这些区域放置重要内容。
audio_url	String	否	https://example.com/bgm.mp3	背景音乐 URL。该音频将无缝循环播放，覆盖整个视频时长。音频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp3, m4a, wav 等主流音频格式。文件大小：建议单个输入文件大小不超过 10 GB。
resolution	String	否	720p	输出的竖版分辨率（固定为 9:16）。默认值为 720p。可选值包括：360p、480p、720p、1080p。
font_type	String	否	sy_black	滚屏文本的字体。默认值为 sy_black。可选值包括： sy_black: 思源黑体（经典、端正、百搭） pm_zhengdao: 庞门正道标题体（粗壮、有力） ali_puhui: 阿里巴巴普惠体（现代、饱满） zhanku_kuaile: 站酷快乐体（圆润、活泼）
font_color	String	否	#1F1F1FFF	文本颜色，必须为 8 位 RGBA 十六进制格式（RRGGBBAA）。默认值为 #1F1F1FFF（不透明深灰色）。若使用深色背景图，建议传入浅色字体（如 #FFFFFFFF），以保证可读性。
single_roll_duration	Number	否	3	单页文字完全滚过屏幕的时长，单位为秒。值越小，滚动速度越快。默认值为 3。取值范围: [0.5, 60]。
start_hold_duration	Number	否	2	视频开始时，文字在起始位置静止停留的时长，单位为秒。默认值为 2。取值范围: [0, 60]。
end_hold_duration	Number	否	2	视频结束时，文字在结束位置静止停留的时长，单位为秒。默认值为 2。取值范围: [0, 60]。
media_output_destination	String	否	vod://my-space	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 设置本参数后，任务结果中的 url 相关字段将返回形如 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_136	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_custom_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

以下示例演示了如何生成一个 1080p、带背景音乐、使用思源黑体和白色字体的文字滚屏视频。

响应说明

调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。

响应参数

参数	类型	描述
success	Boolean	任务是否成功提交。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识符。仅在 success 为 true 时返回有效值。您可以使用此 ID 来查询任务状态和结果。
request_id	String	本次 API 请求的唯一标识符，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。

Error 对象

参数	类型	描述
code	String	具体的错误码。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如 BadRequest。
message	String	对错误的详细描述，可用于开发调试。
param	String	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

文字生成滚屏视频是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果：

方法一（轮询查询）：使用提交任务时获取的 task_id，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

方法二（事件回调）：在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 callback_url 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅事件回调。

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。

参数	类型	示例值	描述
video_url	String	https://example.volcvideo.com/output.mp4?auth_key=...	生成的文字滚屏视频文件地址。文件格式为 MP4。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	25.5	输出视频的总时长（单位：秒）。
resolution	String	1080p	输出视频的分辨率。

最终的完整任务信息示例：

附录：默认配置详细说明

为保证开箱即用的效果，系统内置了一系列默认配置。本附录详细说明文字生成滚屏视频过程中的各项默认设置。

布局与尺寸

输出尺寸：视频画面固定为 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。音乐将循环播放，直到视频结束。如果音乐时长超过视频时长，超出部分将被自动截断。

AI MediaKit