如需开通使用本API，请联系火山

概述

本文档为 Kickart OpenAPI【故事板渲染视频 API】的官方接入指引。旨在帮助开发者通过 API 接口，将"故事板渲染视频"能力（输入结构化故事板 + 渲染参数，输出成片视频）快速、高效地集成到自有业务系统中。

故事板渲染视频 API 通常与"故事板生成 API"（爆款复刻 / 一键成片）配合使用，典型调用流程如下：

快速开始

仅需两步即可完成您的首次 API 调用：

申请 API Key：在火山-创作Agent控制台获取用于OpenAPI请求的 API Key。

调用接口：根据本文档的指引，构造 HTTP 请求，并通过 API Key 进行鉴权，发起接口调用。

*调用 API 须确认有权使用所提交的信息及内容，承诺上传的人像素材均为已授权虚拟人像，并已阅读且同意《虚拟人像合规承诺函》与《合规承诺函》

对外域名

对外域名: https://kickart.volces.com

APIKey 申请

请通过主账号登录创作Agent首页。

导航至 kickart-apikey申请页面。

在左侧菜单中选择「API Key」模块，然后点击「+New」按钮。

输入 API Key 名称后，点击「Create」按钮完成创建。

创建成功后，您将获得一个 API Key。请妥善保管此密钥，它将作为您调用所有接口的唯一凭证。

权限说明：在调用接口前，请确保您的账户已开通相关服务的访问权限。若在调用过程中遇到权限问题，请联系您的企业管理员或火山引擎商务代表。

鉴权方式

所有 API 接口均采用基于 HTTP Header 的 Bearer Token 鉴权方案。您需要在每次请求的 Header 中附带 Authorization 和 Content-Type 字段。

Header	说明
Authorization	认证凭证。格式必须为 Bearer {API_KEY}，其中 {API_KEY} 需要替换为您在Kickart平台申请到的真实 API Key。示例: Bearer 1jkdislxdsldjgeouqllsj8ko8gssccx
Content-Type	请求体的内容类型。固定值为 application/json。

模板说明

故事板渲染视频 API 提供两种渲染模式，所有参数都相同, 只是模型和创点消耗不同, 通过 template_id 区分。请根据画质与速度需求选择对应模板。

模板 ID	模板说明	创点消耗
如需使用，请联系火山	专业模式（seedance 2.5 pro、720p）对应底层模型seedance_2.5，拥有更稳定的指令遵循能力，单次视频创作时长进一步放宽，可以支持更多参考素材的引用。	按照实际token消耗计费
如需使用，请联系火山	专业模式（seedance 2.0 pro、720p）对应底层模型 seedance_2.0，画质与稳定性更佳，适用于对成片质量要求高的场景。	按照实际token消耗计费
如需使用，请联系火山	进阶模式（seedance 2.0 fast、720p）对应底层模型 seedance_2.0_fast，渲染速度更快，适用于对时效要求高、批量化生产的场景。	按照实际token消耗计费
如需使用，请联系火山	Mini模式（seedance 2.0 mini、720p）对应底层模型 seedance_2.0_mini，渲染速度更快，适用于对时效要求高、批量化生产的场景。	按照实际token消耗计费

具体可用的 template_id 以实际分配为准，如有疑问请联系您的火山引擎商务代表获取。

接口说明

提交异步任务

该接口用于提交一个故事板渲染视频的异步处理任务。调用成功后，会立即返回一个任务 ID (task_id)，您可以使用此 ID 来查询任务的执行状态和最终结果（渲染完成的视频下载链接）。

请求方法：POST

请求路径：/openapi/ai_effect/submit

请求参数

字段名	类型	必填	描述
template_id	string	是	固定值，用于指定渲染模式（专业模式 / 进阶模式）。参考「模板说明」
payload	payload	是	JSON Object，用于传递渲染所需的故事板与渲染参数。其内部结构见下文 payload 结构。 payload输入素材规则请参考：素材校验规则说明
callback_url	string	否	回调任务结果的公网地址，例如 https://your-server.com/webhook。当任务完成（无论成功或失败）时，系统会向此 URL 发送一个 POST 请求，通知您结果。回调结果即为查询接口的响应参数。
watermark	boolean	否	true 默认 false 视频右下角是否添加“AI生成”水印，若需添加则传入true
content_producer	string	否	暗水印生产者的社会信用代码。未传入时以 SaaS 配置为准；传入时以传入内容为准 GB45438 标识中的内容生戸者的社会信用代码
content_propagator	string	否	暗水印内容传播者的社会信用代码。未传入时以 SaaS 配置为准；传入时以传入内容为准 GB45438 标识中的内容传播者的社会信用代码
无需传入, 会读取 saas 页面中的配置	无需传入	否	和你的 saas 中配置保持一致
private_ips	string[]	否	私有版权ID数组示例: [767891111111111, 767892222222222, 767893333333333] 不能超过5个如果传入ips, 会根据该租户的我的版权配置, 匹配相应模型的私有版权进行校验 https://console.volcengine.com/kickart/copyright-space

payload 结构

字段名	类型	必填	说明
storyboard	storyboard	是	完整的故事板结构（可以是故事板生成 API 输出的原始版本，也可以是客户修改后的版本）。结构与故事板生成 API 的输出格式一致，详见下文 storyboard 结构。校验规则：整体分镜数量：最少 1 个分镜，最多 8 个分镜各分镜 prompt ≤ 2000 字符各分镜时长：单个分镜支持 4s–15s，超出范围报错
subtitle_font_id	string	否	字幕字体 ID media_id，字幕字体ID选取请参考：创作Agent （Kickart）-获取字体列表 API 不传则使用默认样式。
subtitle_font_style_id	string	否	花字样式 ID media_id，字幕花字ID选取请参考：创作Agent （Kickart）-获取花字列表 API 不传则使用默认样式。
subtitle_font_size	int	否	字幕大小。默认值 12，取值范围 5～50。
subtitle_line_width_ratio	float	否	字幕单行最大宽度占视频画布宽度的比例，超过该比例后自动换行。默认值 0.9，取值范围 0.5～1。
bgm_mode	string	否	BGM 使用模式，不传默认 auto： none：合成处理阶段不使用 BGM auto：智能识别BGM意图 custom：使用自定义 BGM（需配合 bgm_url） origin_bgm：从原始音频分离BGM纯音乐（需配合 bgm.audio_url）注意事项：bgm_mode该设置不会影响视频生成模型本身的音频生成。即使设置为 none，若故事板分镜或者prompt包含口播、音乐、旋律、伴奏等音频生成内容，视频仍可能包含音频。无需背景音的情况下，注意提示词是否包含音频相关的内容。
bgm_url	string	仅当 bgm_mode=custom 时必填	自定义 BGM 文件 URL。时长适配策略：BGM 短于视频时循环播放；长于视频时截取（以视频时长为准）校验规则：格式 mp3 / wav；大小 ≤ 50MB
nle_subtitle_enabled	bool	否	是否在生成视频中添加硬字幕（nle字幕），默认 true true 开启，false 关闭
use_subtitle_erasure	bool	否	是否在分镜渲染阶段尝试擦除视频底部字幕,默认 false true 开启，false 关闭
resolution	string	否	成片分辨率默认值：720p(p注意要小写) 可选值： Seedance 2.5: 480p, 720p, 1080p Seedance 2.0: 480p, 720p, 1080p, 4k Seedance 2.0 mini: 480p, 720p Seedance 2.0 fast: 480p, 720p

storyboard结构

字段名	类型	必填	说明
video_duration	double	是	视频总时长（秒），等于各分镜时长(shot.duration)之和。总时长加和不超过 90s 如果检查到 shot.duration 加和超过 90, 会如下报错如果各分镜时长(shot.duration)之和和 video_duration不相等,会报错 1424 { "code": 1450, "message": "自定义规则校验失败(rule=array_field_sum_less_than, target=/storyboard/shots): 字段 \"duration\" 之和 156 超过上限 90" }
aspect_ratio	string	是	画面比例，支持 9:16、16:9、3:4、4:3、1:1。
language	string	是	视频语言，影响口播文本、字幕等，例如 zh。支持范围如下语言说明： zh：中文 en: 英文 en-us：英语（美国） pt-br: 葡萄牙语 ja：日语 es-mx：西班牙语（墨西哥） id：印度尼西亚语 ms：马来语 tl：他加禄语（菲律宾语）
title	string	否	故事板标题。
storyline	string	否	整体故事线 / 叙事脚本描述。
visual_style	string	否	整体视觉风格描述。
bgm_description	string	否	BGM 风格描述（在 bgm_mode=auto 时用于智能推荐）。
shots	list<shot>	是	分镜列表，最少 1 个、最多 8 个，结构见下文 shot 结构。
bgm	bgm	bgm_mode=origin_bgm时必填	从故事板输入提取的BGM相关数据

shot 分镜结构

字段名	类型	必填	说明
duration	double	是	分镜时长（秒），取值范围 4s–15s。
prompt	string	是	分镜提示词，描述画面、运镜、口播、风格等。不超过≤ 2000 字符。
subtitle	string	否	该分镜对应的字幕文本。
image_urls	list<string>	否	该分镜引用的图片素材 URL 列表。
audio_urls	list<string>	否	该分镜引用的音频（音色）素材 URL 列表。

bgm结构

字段名	类型	必填	说明
audio_url	string	bgm_mode=origin_bgm时必填	bgm_mode=auto：智能推荐BGM的参考音频 bgm_mode=origin_bgm: 参考视频的音轨，用于从原始音频分离BGM纯音乐
bgm_desc	string	否	BGM 风格描述（在 bgm_mode=auto 时用于智能推荐），优先级高于 bgm_description

素材校验规则说明

输入类型	每个shot	校验条件
文本	shot.prompt	提示词语言支持：所有模型均支持中英文提示词； seedance2.5 额外支持西班牙语、印度尼西亚语、马来语、泰语、阿拉伯语、葡萄牙语、越南语、日语、韩语等 11 种语言； seedance 2.0 及 seedance 2.0 fast 额外支持日语、印尼语、西班牙语、葡萄牙语。提示词字数建议：≤ 2000 字符。字数过多易导致信息分散，模型可能忽略细节、仅关注重点，进而造成视频缺失部分元素。
图片	shot.image_urls	图片数量： ≤ 30 张（2.5）； ≤ 9 张（2.0、2.0 fast）图片大小 & 格式：与一键成片一致（JPEG / PNG，单张 ≤ 8MB）
音频	shot.audio_urls	不可单独输入音频，应至少包含 1 个参考视频或图片。格式：wav、mp3 时长： 2.5：单个视频时长 [2, 30] s，最多传入 10 段参考音频，所有视频总时长不超过 30s。 2.0 & 2.0fast ：单个音频时长 [2, 15] s，最多传入 3 段参考音频，所有音频总时长不超过 15s。大小：单个音频不超过 15MB，请求体大小不超过 64MB。大文件请勿使用 Base64 编码。

响应参数

字段名	类型	描述
code	int32	状态码。0 表示任务已成功提交。非 0 值表示提交失败，原因见 message 字段。
message	string	状态描述信息。
request_id	string	本次请求的唯一标识符，可用于问题排查。
data	object	包含任务 ID 的数据对象。其结构为 {"task_id": "..."}。

cURL 请求示例

响应示例（成功）

响应示例（失败）

查询任务结果

在提交异步任务后，您可以通过此接口，使用 task_id 来轮询任务的执行状态和最终结果（例如生成的图片或视频 URL）。

请求方法：POST

请求路径：/openapi/ai_effect/query

Timeout : 3600 秒

请求参数

字段名	类型	必填	示例	描述
task_id	string	是	"7573967600885514303"	要查询的任务 ID，来源于“提交异步任务”接口的成功响应。

响应参数

响应体中的 code 字段指示了任务的当前状态。您需要依据此字段来判断任务是仍在进行、已成功还是已失败。

字段名	类型	描述
code	i32	任务状态码。关键值包括： 0: 任务执行成功。 1000: 任务仍在运行中。其他非零值表示任务失败，具体含义请参考“错误码说明”章节。
message	string	任务状态的文本描述。例如 "Success" 或 "AsyncTaskRunning"。
request_id	string	本次请求的唯一标识符。
data	queryData	包含任务详细信息的对象，见下文 QueryData 结构。

queryData

字段名	类型	描述
task_id	string	任务的唯一 ID
progress	int	进度 0-100
usage	double	本次任务消耗的创点数量，仅在任务成功时有效
payload	payload	任务详情
eta	AiTemplateTaskETA	任务预估剩余时长，任务进行中会返回，预估时长与实际时长存在差异。

payload

任务结果详情，不同类型任务的结果字段可能存在差异，以下字段为结果公共字段。

字段名	类型	描述
result_url	string	任务结果地址
shot_list	array	分镜视频列表，元素顺序与输入 storyboard.shots 一致

关于 result_url 的有效期

请注意，响应中返回的 result_url 具有有效期，我们保证其在任务完成后 24 小时内可用。为避免资源失效，请您在获取到 URL 后尽快下载所需的文件。

shot_list

字段名	类型	说明
duration	double	分镜时长, 如 15
width	double	分镜视频的宽, 如 1280
height	double	分镜视频的高, 如 720
url	string	每个分镜视频地址 url

AiTemplateTaskETA

字段名	类型	描述
remaining_ms	i64	任务预估剩余时长，单位毫秒
confidence	string	置信度（样本数据是否充足，决定数据可信度高低） high（样本数据充足） medium（样本数据一般） unknown（样本数据不足）

cURL 请求示例

响应示例（任务成功）

响应示例（任务进行中）

响应示例（任务失败）

取消异步任务

在提交异步任务后，您可以通过此接口，使用 task_id 来轮询任务的执行状态、处理进度和最终结果（例如生成的图片或视频 URL）。

请求方法：POST

请求路径：/openapi/ai_effect/cancel

Timeout : 3600 秒

请求参数

字段名	类型	必填	示例	描述
task_id	string	是	"7573967600885514303"	要取消的任务 ID，来源于“提交异步任务”接口的成功响应。

响应参数

响应体中的 code 字段指示了任务是否取消成功，您需要依据此字段来判断任务是否已经成功取消或发起重试。

字段名	类型	描述
code	i32	任务状态码。关键值包括： 0：取消成功 1602：任务已取消 1603：任务已结束，不可取消 1604：任务取消失败，稍后重试其他非零值表示任务失败，具体含义请参考“错误码说明”章节。
message	string	任务状态的文本描述。例如 "Success"。
request_id	string	本次请求的唯一标识符。

cURL 请求示例

响应示例（取消成功）

响应示例（取消失败）

错误码说明

所有接口的响应体中都包含 code 和 message 字段，用于指示请求的处理结果。当 code 为 0 时，表示业务处理成功。非 0 值表示出现了异常。

通用错误码

错误码	错误类型(标记用, 不会返回)	描述与处理建议
1300	AuthFailed	认证失败：API Key 无效、过期或未激活。请检查您的 API Key 是否正确，或在火山引擎控制台确认其状态。
1400	ParamErr	参数错误：请求中包含无效或缺失的参数。请对照文档检查请求体结构、字段类型和必填项。
1401	ConcurrentErr	并发超限：您当前的并发请求数超过了约定的上限。请降低请求频率，或联系商务代表调整并发额度。
1403	QuotaErr	无权限：您的账户没有调用此接口的权限。请联系企业管理员为您开通相关服务的访问权限。
1402	InsufficientPoints	创点不足：账户余额不足以支付本次任务消耗。请及时充值。
1418	InvalidDurationBillingErr	无效时长参数：入参时长参数不满足接口入参要求
1500	InternalErr	内部错误：服务端发生未知错误。请记录 request_id 并联系技术支持。

接口特定错误码

/openapi/ai_effect/submit & /openapi/ai_effect/query & /openapi/ai_effect/cancel

错误码	错误类型(标记用, 不会返回)	描述与处理建议
0	Success	任务成功：任务处理完成，结果已生成。
1000	AsyncTaskRunning	任务运行中：任务正在处理，请稍后通过 AITemplateAsyncTaskQuery 接口轮询结果。
1410	TemplateIdNotExist	模板不存在：请求的 template_id 无效或对应的模板未上线。请通过 ListTemplateInfo 接口获取可用的模板列表。
1411	InputResolutionErr	分辨率错误：请求的 Resolution 不在模板支持的 resolutions 列表内。
1412	ImageFormatErr	图片格式错误：输入的图片格式不受支持或文件已损坏。建议使用常见的 JPEG 或 PNG 格式。
1413	InvalidMediaUrlErr	媒体 URL 无效：ResourceList 中的 URL 无法访问。请确保 URL 是公网可达的，且未过期。推荐接入火山的对象存储 https://console.volcengine.com/tos, 替换原有的TOS服务, 可提高大模型审核和生成的图片拉取成功率
1414	MediaSensitiveErr	内容安全问题：输入内容触发了平台的安全审核策略，请更换内容后重试。
1415	OutputMediaSensitiveErr	输出包含敏感信息错误：输出内容触发了平台的安全审核策略，请更换内容后重试。
1416	InvalidMediaCountErr	错误的媒体数量：输入的媒体数量超出限制，请更换内容后重试。
1417	ChatCompletionError	大模型调用错误：大模型调用失败，请稍后重试。
1418	InvalidDurationBillingErr	时长计费参数错误：时长计费参数缺失，请检查参数后重试。
1419	TemplateIdErr	模板ID错误：模板ID输入错误，请检查参数后重试。
1420	ImageDetectionRulesError	图片内容检测未匹配到规则错误：图片内容不符合规则，请更换内容后重试。
1421	DurationEnumError	入参时长枚举值错误：时长参数不符合要求，请检查参数后重试。
1422	GetDouDianProductInfoError	抖店商品信息获取失败错误：商品信息获取失败，请稍后重试或更换商品信息后重试。
1423	VideoResolutionError	参考视频分辨率错误：参考视频分辨率校验失败，请更换内容后重试。
1424	VideoDurationError	参考视频时长错误：参考视频时长校验失败，请更换内容后重试。
1425	VideoFormatError	参考视频格式错误：参考视频格式校验失败，请更换内容后重试。
1426	VideoSizeError	参考视频大小错误：参考视频内容大小校验失败，请更换内容后重试。
1427	RefVideoError	参考视频链接错误：参考视频链接校验失败，请更换内容后重试。
1428	LanguageEnumError	语言枚举值错误：语言输入参数错误，请检查参数后重试。
1429	ModelImageCountError	模型ImageCount错误，与模板配置不一致：输入图片数量不符合模板要求，请更换内容后重试。
1430	InputRatioError	输入图片比例错误：输入图片比例不符合模板要求，请更换内容后重试。
1431	CopyrightCheckFailed	版权校验失败：版权校验失败，请更换内容后重试。
1432	NoCopyright	输入媒资无版权：版权校验失败，请更换内容后重试。
1433	CopyrightCheckTimeout	版权校验超时：版权校验超时，请稍后重试。
1434	CopyrightMediaParamErr	版权校验媒资参数错误：版权校验失败，请更换内容后重试。
1435	OutputNoCopyright	输出媒资无版权：版权校验失败，请更换内容后重试。
1436	InputCopyrightChecking	输入版权校验中：任务查询正常状态，可继续轮询查询。
1437	OutputCopyrightChecking	输出版权校验中：任务查询正常状态，可继续轮询查询。
1438	InputCopyrightCheckFailed	输入版权校验失败：任务查询失败状态，可停止轮询。
1439	OutputCopyrightCheckFailed	输出版权校验失败：任务查询失败状态，可停止轮询。
1441	PrivateCopyrightQueryFail	私有版权查询失败：私有版权查询失败，请检查版权IP信息后重试。
1442	PrivateCopyrightExceed	私有版权超过5个：私有版权数量超出限制，请检查版权IP信息后重试。
1443	PrivateCopyrightNotFound	未找到对应模型的私有版权：服务模型未配置私有版权，请联系管理员确认。
1450	InputValidationErr	模板入参校验失败：同时会返回 code 和 message (告知多个字段和规则) { "code": 1450, "message": "模板入参校验失败: input_schema 校验失败: 字段 /language: value must be one of \"zh\", \"en\"; 字段 /product_name: length must be >= 1, but got 0", }
1600	AsyncTaskNotExist	任务不存在：查询的 task_id 无效。请检查 task_id 是否为 AITemplateAsyncTaskSubmit 接口成功返回的值。
1601	AsyncTaskTimeoutErr	任务超时：任务执行超过了系统设定的最长处理时间（当前为 1 小时）。
2000	AsyncTaskFailed	任务失败：任务在执行过程中发生未能归类的失败。
3000	TaskCallbackFailed	回调失败：向您配置的回调地址发送结果时失败。
5000	RiverWorkflowFailed	工作流失败：底层 AI 工作流执行失败，通常为更具体的错误（如 1412-1414）的兜底。