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

概述

本文档为创作Agent OpenAPI 的官方接入指引。旨在帮助开发者通过 API 接口，快速、高效地集成和使用平台提供的 AI 能力，如一键成片、风格化图生图、图生视频等。

快速开始

仅需两步即可完成您的首次 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} 需要替换为您在创作Agent平台申请到的真实 API Key。示例: Bearer 1jkdislxdsldjgeouqllsj8ko8gssccx
Content-Type	请求体的内容类型。固定值为 application/json。

模板说明

模板 ID	模板说明
如需使用，请联系火山	一键成片 - 故事板 API

接口说明

提交异步任务

该接口用于提交一个一键成片API的异步处理任务。调用成功后，会立即返回一个任务 ID (task_id)，您可以使用此 ID 来查询任务的执行状态和最终结果。

请求方法：POST

请求路径：/openapi/ai_effect/submit

请求参数

字段名	中文	类型	必填	示例	描述
template_id	模板 ID	string	是	60001	要使用的模板 ID。请从“模板说明”表格中获取
payload	参数	json	是	参考下方示例	JSON Object，用于传递模板渲染所需的具体参数。其内部结构见下文。
callback_url	回调地址	string	否	回调任务结果的公网地址。	当任务完成（无论成功或失败）时，系统会向此 URL 发送一个 POST 请求，通知您结果。回调结果就是查询的响应参数

payload 结构

字段名	类型	必填	说明	描述 or 举例
product_url	string	product_url product_id user_images user_videos 四个值至少有一个	抖店商品链接	"product_id": "172839182"
product_id	string			抖店商品ID	"product_url": "https://www.tiktok.com/view/product/172839182" 获取抖店商品链接、ID请参考：抖音商品ID、商品详情页链接怎么获取？
user_images	list<string>			用户提供的图片列表全部类型素材共：15 个上限如果多个字段同时传入，素材使用的优先级：user_images > user_videos>product_id>product_url	["https://lf3-static.bytednsdoc.com/obj/eden-cn/eteh7pbopxnuhf/IbcFBYHFrw20240701235334.jpg", "https://lf3-static.bytednsdoc.com/obj/eden-cn/eteh7pbopxnuhf/800.jpg"]
user_videos	list<string>			用户提供的视频列表全部类型素材共：15 个上限如果多个字段同时传入，素材使用的优先级：user_images > user_videos>product_id>product_url	["https://lf3-static.bytednsdoc.com/obj/eden-cn/nulozubqbd/product/02177484069763200000000000000000000ffffac15dcc482d342.mp4"]
product_name	string	否	商品名称 ≤ 500 字符商品url/id和“product_name”字段同时存在时，取传入的product_name	"有机牛奶"
prompt	string	否	用户自定义创意策略 / 爆点描述。用于指导故事板的创意方向和内容生成。不传则使用系统默认策略。 ≤ 5000字符	"参考视频<用户视频1>，结合商品<用户图片1>为一款保湿面霜制作一支突出天然成分和补水效果的视频，风格清新自然。"
language	string	是	视频语言，只会影响字幕subtitle 支持范围如下语言说明： zh：中文 en: 英文 en-us：英语（美国） pt-br: 葡萄牙语 ja：日语 es-mx：西班牙语（墨西哥） id：印度尼西亚语 ms：马来语 tl：他加禄语（菲律宾语）	"language": "zh"
purpose	string	是	支持选择一个细分分类, 下面是举例品牌广告好物推荐剧情演绎测评对比日常Vlog 生活服务	生活服务
duration	int	是	期望视频时长，AI生成可能小部分情况存在时长差异只能是15、30、45、60这四种	15 30 45 60
aspect_ratio	string	否	视频比例，需遵循 SaaS 平台约束。 9:16, 16:9, 3:4, 4:3, 1:1	9:16, 16:9, 3:4, 4:3, 1:1
ai_product_analysis	bool	否	是打开AI分析卖点、目标受众开关，默认"关闭"（false）。打开（true）：AI 自动分析商品卖点、目标受众关闭（false）：不进行卖点和目标受众分析	"ai_product_analysis": true
product_selling_points	string	否	商品卖点描述多个用 ; 分割就行(英文分号) ≤ 5000字符如果product_selling_points 传入同时ai_product_analysis= true ，优先取传入的product_selling_points	"天然有机"
product_target_audience	string	否	商品目标受众描述多个用 ; 分割就行(英文分号) ≤ 1000 字符如果product_target_audience 传入同时ai_product_analysis= true ，优先取传入的product_target_audience	"上班族，低头族"

响应参数

字段名	类型	描述
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
usage	double	本次任务消耗的创点数量，仅在任务成功时有效
payload	payload	任务详情

payload

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

字段名	类型	描述
storyboard	storyboard	故事板结构

storyboard 结构

字段名	类型	描述（含样例）
video_duration	double	视频总时长，等于各分镜时长之和, 单位为秒。示例：28.1
aspect_ratio	string	画面宽高比。示例：9:16、16:9、3:4、4:3、1:1
language	string	视频语言，影响口播文本、字幕等。示例："zh"
bgm_description	string	背景音乐与音效描述，用于说明节奏、乐器和氛围。示例："BPM为120的轻快灵动中式国风纯音乐..."
storyline	string	整体故事线 / 叙事脚本描述。示例："开篇展示弋阳手工年糕的多种形态与吃法..."
title	string	故事板标题。示例："江西弋阳手工年糕产品推广视频"
visual_style	string	整体视觉风格描述。示例："明亮柔和的中式美食风..."
shots	list<shots>	分镜数组，每个元素表示一个分镜片段。示例：[{"duration":9.8,"prompt":"【分镜1（9.8s）】...","subtitle":"江西弋阳正宗手工年糕来啦...","image_urls":["https://p9-aio.bytedance.com/..."],"audio_urls":["https://lf3-river-platform-cdn-sign.volces.com/..."]}]
material_list	StoryboardMaterial[]	当前分镜使用的素材列表

storyboard-shots 元素结构

字段名	类型	描述（含样例）
duration	double	单个分镜时长，单位为秒。示例：9.8
prompt	string	分镜脚本与镜头说明。示例："【分镜1（9.8s）】：0-1s：全景固定机位平视..."
subtitle	string	该分镜对应的字幕或口播文案。示例："江西弋阳正宗手工年糕来啦。这可是正宗江西弋阳特产..."
image_urls	array<string>	该分镜依赖的图片素材 URL 列表。示例：["https://p9-aio.bytedance.com/...","https://lf26-river-platform-cdn-sign.volces.com/..."]
audio_urls	array<string>	该分镜依赖的音频素材 URL 列表。示例：["https://lf3-river-platform-cdn-sign.volces.com/...","https://lf26-river-platform-cdn-sign.volces.com/..."]
video_urls	array<string>	该分镜依赖的视频素材 URL 列表。示例：["https://lf3-river-platform-cdn-sign.volces.com/...","https://lf26-river-platform-cdn-sign.volces.com/..."]

StoryboardMaterial

字段名	类型	描述（含样例）
index	number	素材在image_urls、audio_urls或video_urls中的索引，下标从1开始
name	string	全局唯一名称，例如素材x
name_in_prompt	string	局部名称，素材在 prompt 中的引用名称，例如图x，音频x
type	string	素材类型，例如 image、audio、video
group	string	素材分组，例如生活服务中的 role、location，其余默认不返回
url	string	素材 URL；
description	string	素材描述
source_type	string	素材来源，例如 USER、AIGC

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

https://bytedance.larkoffice.com/sync/MmvedFnHjsSV1dbAj2McVA65nue

代码口径补充：一键成片故事板 API 参数

1. 能力说明

根据商品信息、用户素材和用户创作要求生成结构化故事板，不执行视频渲染。该入口输出首个 storyboard，适合作为上层一键成片链路中的故事板生成 API。

2. 标识信息

能力 / 入口	workflowId	serviceId（CN）	说明
一键成片故事板 API	409198594	待确认	固定生成 2.0-standard 故事板

代码入口：apps/kickart/03-gen-storyboard/src/workflow/main/api.ts

下游故事板链路：

purpose=生活服务或 purpose=剧情演绎：走 SingleAgent

其他 purpose：走 MVA 故事板链路

示例输入：apps/kickart/05-e2e-gen-video/fixtures/life-service.json 可转换为该入口参数使用

3. 输入说明

字段	类型	必填	说明	默认值 / 备注
language	string	是	视频语言，影响故事板文案、字幕、口播语言等生成内容	支持 zh、en、pt-br、en-us、ja、es-mx、id、ms、tl
purpose	string	是	视频目的 / 视频类型	支持好物推荐、测评对比、品牌广告、日常Vlog、剧情演绎、生活服务
duration	number	是	期望视频时长，单位秒	仅支持 15、30、45、60；内部会转换为 [duration - 15, duration]
product_url	string	否	抖店商品链接	默认空字符串；非生活服务时和 product_id/user_images/user_videos 四者至少传一个
product_id	string	否	抖店商品 ID	默认空字符串；非生活服务时和 product_url/user_images/user_videos 四者至少传一个
user_images	string[]	否	用户提供的图片 URL 列表	默认空数组；非生活服务时可作为商品 / 人物 / 场景素材输入
user_videos	string[]	否	用户提供的视频 URL 列表	默认空数组；非生活服务时可作为商品分析素材输入
product_name	string	否	商品名称	默认空字符串；商品 URL / ID 与该字段同时存在时，优先使用该字段覆盖商品标题
prompt	string	否	用户自定义创意策略 / 爆点描述 / 创意包内容	默认空字符串；生活服务会直接以该字段作为权威创意包来源
aspect_ratio	string	否	视频画幅比例	默认 9:16；支持 9:16、16:9、3:4、4:3、1:1
ai_product_analysis	boolean	否	是否保留 AI 自动分析出的商品卖点和目标受众	默认 false；为 false 时清空分析出的 product_features/product_audiences，但不影响显式覆盖字段
product_selling_points	string	否	商品卖点描述	默认空字符串；非空时覆盖 product_features，多个卖点建议用英文分号分隔
product_target_audience	string	否	商品目标受众描述	默认空字符串；非空时覆盖 product_audiences，多个受众建议用英文分号分隔

4. 生活服务规则

purpose=生活服务时走 SingleAgent 链路。

purpose=生活服务时允许 product_url/product_id/user_images/user_videos 全部为空。

purpose=生活服务时跳过抖店商品解析，直接使用 prompt 构造故事板输入。

prompt 中如包含人物描述，会由生活服务链路判断并生成 group=role 的 AIGC 角色参考图。

prompt 中如包含场景描述，会由生活服务链路判断并生成 group=location 的 AIGC 场景参考图。

生活服务参考图使用 seedream-5.0-pro。

生活服务默认不强制生成口播、字幕或配音。

5. 示例输入

6. 输出说明

字段	类型	说明
storyboard	object	生成的首个故事板
storyboard.aspect_ratio	string	输入画幅比例
storyboard.language	string	输入视频语言
storyboard.video_duration	number	故事板总时长
storyboard.bgm_description	string	BGM 描述
storyboard.storyline	string	故事线总结
storyboard.title	string	故事板标题
storyboard.visual_style	string	视觉风格
storyboard.shots	StoryboardShot[]	分镜列表

StoryboardShot

字段	类型	说明
duration	number	当前分镜时长，单位秒
prompt	string	当前分镜生成提示词
subtitle	string	当前分镜字幕；无字幕时为空字符串
image_urls	string[]	当前分镜引用的图片 URL 列表
audio_urls	string[]	当前分镜引用的音频 URL 列表
material_list	StoryboardMaterial[]	当前分镜使用的素材列表

StoryboardMaterial

字段	类型	说明
index	number	素材在当前分镜中的序号
name	string	素材名称
name_in_prompt	string	素材在 prompt 中的引用名称
type	string	素材类型，例如 image、video、audio
group	string	素材分组，例如生活服务中的 role、location
url	string	素材 URL；部分 AIGC 素材可能只在 image_urls/audio_urls 中出现
description	string	素材描述
source_type	string	素材来源，例如 USER、AIGC

7. 链路拆解

校验 language/purpose/duration/aspect_ratio 枚举。

非生活服务校验 product_url/product_id/user_images/user_videos 至少一个非空。

非生活服务调用抖店解析与商品分析，生成商品、受众、卖点和媒体分析结果。

生活服务跳过抖店解析，直接用 prompt 构造空媒体商品分析结果。

构造故事板 payload，固定 version=2.0-standard。

生活服务、剧情演绎走 SingleAgent；其他 purpose 走 MVA。

输出首个 storyboard，并格式化返回 shots[].material_list。

8. 备注

当前文档描述的是仓库内 River workflow 入口，不是完整 HTTP REST API。

当前入口只生成故事板，不执行视频渲染，不返回 resultURL/shot_list/produceID。

生活服务的 material_list 可用于识别自动生成的角色图和场景图：group=role / group=location。

Kickart