## **如需开通使用本API，请联系火山销售申请加白** 1. # 概述本文档为创作Agent OpenAPI 的官方接入指引。旨在帮助开发者通过 API 接口，快速、高效地集成和使用平台提供的 AI 能力，如一键成片、风格化图生图、图生视频等。 2. # 快速开始仅需两步即可完成您的首次 API 调用： 1. **申请 API Key**：在[火山-创作Agent控制台](https://console.volcengine.com/kickart/fusion/setting/api-key)获取用于OpenAPI请求的 API Key。 2. **调用接口**：根据本文档的指引，构造 HTTP 请求，并通过 API Key 进行鉴权，发起接口调用。 *\*调用 API 须确认有权使用所提交的信息及内容，承诺上传的人像素材均为已授权虚拟人像，并已阅读且同意*[《虚拟人像合规承诺函》](https://www.volcengine.com/docs/6664/2369812?lang=zh)*与*[《合规承诺函》](https://www.volcengine.com/docs/6664/2369383?lang=zh) 3. # 对外域名 **对外域名: ** [https://kickart.volces.com](https://kickart.volces.com) 4. # APIKey 申请 1. 请通过主账号登录[创作Agent首页](https://console.volcengine.com/kickart)。 2. 导航至 [kickart-apikey申请页面](https://console.volcengine.com/kickart/fusion/setting/api-key) 。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5aed9121074c11206d1359f733aad2ca.png)![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ad596bb44db69d5a1abf84ffa760d86d.png) 3. 在左侧菜单中选择 **「API Key」** 模块，然后点击 **「+New」** 按钮。 4. 输入 API Key 名称后，点击 **「Create」** 按钮完成创建。 5. 创建成功后，您将获得一个 API Key。请妥善保管此密钥，它将作为您调用所有接口的唯一凭证。 **权限说明**：在调用接口前，请确保您的账户已开通相关服务的访问权限。若在调用过程中遇到权限问题，请联系您的企业管理员或火山引擎商务代表。 1. ## 鉴权方式所有 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。 | --- 5. # 模板说明 |
**模板 ID**
|
**模板说明**
| |---|---| |如需使用，请联系火山

|**一键成片 \- 故事板 API**

| 6. # 接口说明 1. ## 提交异步任务该接口用于提交一个一键成片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、商品详情页链接怎么获取？](https://www.volcengine.com/docs/6664/1319938?lang=zh) | |user_images

|list

||用户提供的图片列表

* 全部类型素材共：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

||用户提供的视频列表

* 全部类型素材共：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 请求示例 ```Bash curl --location 'https://kickart.volces.com/openapi/ai_effect/submit' \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "template_id": "3312XXXX", "callback_url": {YOUR_CALLBACK_URL},, "payload": { "aspect_ratio": "9:16", "duration": 15, "language": "zh", "prompt": "（上传的图片作为主播形象）基于参考图生成视频\n一、车内内饰 & 中控屏固定规则\n中控屏位置锁定：车机中控屏位置严格按照参考图生成，全程不得出现在车门、A 柱、座椅、顶棚等非原车安装位；屏幕贴合中控台实体结构，杜绝悬浮、漂浮、悬空、穿透车体、镜头异动偏移、画面内无故位移缩放。\n整车内饰布局保真：严格遵循量产原车物理尺寸与装配比例，方向盘、仪表盘、仪表台、空调出风口、座椅、车门门板各零部件相对坐标全程固定不变；全片运镜、镜头切换时，内饰无穿模、扭曲、形变、错位、穿插 bug。\n中控屏形态稳定：任意镜头推拉摇移、画面切换场景，中控屏安装角度、物理尺寸、空间位置恒定不变。\n二、车辆外观标识约束\n完整沿用参考图原车车身造型、品牌车标 LOGO、车身原厂文字标识；严禁篡改、变形、替换车标，禁止私自修改原车标识样式。\n三、全局禁用清单\n❌ 禁止中控屏移动至车门、座椅、立柱；\n❌ 禁止屏幕悬浮漂浮、移位穿透；\n❌ 禁止内饰构件穿模、比例失真、结构错位；\n❌ 禁止擅自添加参考图、脚本未注明的多余装饰、无关零部件；\n❌ 禁止视频中出现无人驾驶画面。\n三、分镜约束\n所有分镜的描述主题、人物要保持一致性。\n所有分镜中主播口播有字幕、匹配口型、有音色、有BGM。\n画面与动态描述：\n【融合后完整参数】\n1. 画面主体：甜美少女驾驶员驾驶宝马i7行驶在月球表面，全力躲避后方外星飞船的追踪与攻击，驾驶员紧盯前方、双手把控方向盘不断调整路线规避锁定；外星飞船锁定车辆后发射导弹，导弹越过车顶落在车辆正前方爆炸，扬起大片灰尘烟雾笼罩前方路径；驾驶员操控车辆径直穿过烟尘区域，宝马i7冲破烟雾带后毫发无损，调整朝向朝地球方向全速驶去\n2. 镜头运镜：平稳慢推与环绕结合，远近景切换，适度特写，固定与推拉摇移搭配\n3. 画质分辨率：4K超清高清画质\n4. 画面风格：动感十足，节奏明快，吸引年轻客户\n5. 光影色调：自然光暖调，明亮通透，适度氛围感\n6. 构图比例：9:16\n7. 细节质感：细节拉满，真实肌理，画面清晰无模糊无变形\n8. 氛围背景：月球表面地貌，星空背景，爆炸产生的烟尘特效\n9. 动态速度：流畅动感，快节奏\n10.视频总时长：30s\n11.人物形象：甜美少女形象主播，五官柔和、齐肩碎发、休闲机能风穿搭，气质灵动，妆容清透自然\n【完整视频创意总指令】\n生成9:16竖屏、30s时长、4K超清的动感科幻风格短视频，整体节奏明快。画面围绕甜美少女驾驶员驾驶宝马i7在月球躲避外星飞船追击的剧情展开：少女驾驶宝马i7在月球表面疾驰规避后方外星飞船攻击，飞船发射导弹在车前爆炸产生烟尘，车辆穿过烟尘后毫发无损朝地球全速前进。画面细节拉满，清晰呈现宝马车标、车身线条，少女形象全程保持甜美灵动的主播特征，光影明亮通透带科幻氛围感，运镜结合快慢切换、远近景交替，适配年轻用户喜好，搭配贴合剧情的燃向旁白。\n【详细分镜脚本】\n分镜总时长：30s\n分镜数量：6镜\n分镜1：\n- 分镜时长：5s\n- 分镜台词/旁白：没想到月球飙车的刺激，今天被我遇上了！\n- 分镜画面详细描述：近景特写驾驶位，甜美少女主播（齐肩碎发、浅灰机能风外套、清透元气妆容）双手紧握宝马i7方向盘，眼神紧盯前方，嘴角带点紧绷的专注感，方向盘上的宝马车标清晰可见，背景是快速后移的月球灰色岩土，镜头轻微晃动模拟车辆行驶动感，暖冷结合的光影打在少女面部和中控台上，内饰按键细节清晰。\n分镜2：\n- 分镜时长：5s\n- 分镜台词/旁白：身后的外星飞船紧追不舍，得赶紧甩开它！\n- 分镜画面详细描述：中景后拉镜头，展示宝马i7银灰色车身在月球凹凸的表面疾驰，车轮卷起细碎月尘，后方远处碟形外星飞船发着淡红色追踪光跟在车后，镜头跟拍车辆行驶轨迹，背景是布满星星的暗蓝色深空，车身金属肌理真实清晰。\n分镜3：\n- 分镜时长：5s\n- 分镜台词/旁白：不好，被锁定了！\n- 分镜画面详细描述：特写快速从车尾摇到后上方，外星飞船前端亮起红色锁定光，一枚银灰色导弹拖着火焰从飞船射出，快速越过宝马i7车顶，镜头跟随导弹前进轨迹向前移动，导弹尾焰的暖光和深空冷光形成对比。\n分镜4：\n- 分镜时长：5s\n- 分镜台词/旁白：就这点本事？拦不住我！\n- 分镜画面详细描述：远景镜头，导弹在宝马i7正前方十几米处爆炸，橙红色火光炸开，扬起大面积灰白色烟尘瞬间覆盖前方路面，镜头慢放爆炸瞬间，火光和烟尘的层次细节清晰，宝马i7在爆炸气浪中保持行驶姿态稳速向前。\n分镜5：\n- 分镜时长：5s\n- 分镜台词/旁白：宝马i7的品质，可经得住这种考验！\n- 分镜画面详细描述：跟拍镜头，宝马i7一头扎进灰白色烟尘中，镜头跟随车辆穿过烟雾，过程中逐渐清晰露出完好无损的车身，车漆没有任何刮痕，车窗完整透亮，车标在烟尘缝隙的光线下依旧清晰，少女握着方向盘的手稳定没有晃动。\n分镜6：\n- 分镜时长：5s\n- 分镜台词/旁白：走，咱们回地球！\n- 分镜画面详细描述：远景慢推镜头，宝马i7调整行驶方向，车头朝向画面远处蓝白色的地球全速前进，后方外星飞船被远远甩在烟尘后方，镜头跟着车辆前进方向缓缓推进，背景中地球的轮廓明亮清晰，月球表面延伸向远方，整体画面开阔有冲击力。", "purpose": "好物推荐", "user_images": [ "https://lf3-static.bytednsdoc.com/obj/eden-cn/jhteh7uhpxnult/test_image/car/car_1.png", "https://lf3-static.bytednsdoc.com/obj/eden-cn/jhteh7uhpxnult/test_image/car/car_2.png", "https://lf3-static.bytednsdoc.com/obj/eden-cn/jhteh7uhpxnult/test_image/car/woman_30.png" ], "product_selling_points": "速度感;安静;舒适性", "product_target_audience": "SUV爱好者", "product_name": "别克汽车E7" } }' ``` ### 响应示例（成功） ```JSON { "code": 0, "data": { "task_id": "7621886649043206198" //用来做查询任务的入参, 也可以等待callback }, "message": "success", "request_id": "20260330132131910C619A3D2F5FF87656" } ``` ### 响应示例（失败） ```JSON { "code": 1410, // 请参考5.3 通用错误码 "data": {}, "message": "template_id not exist", "request_id": "202603301322133EB7BAD7D1B156F75CF7" } ``` --- 2. ## 查询任务结果在提交异步任务后，您可以通过此接口，使用 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](https://bytedance.larkoffice.com/docx/A9MVdVTvvo93u6xL3Zhc92j9nph?contentTheme=DARK&last_doc_message_id=7622959140566371552&preview_comment_id=7622959347257215958&sourceType=feed&theme=light#doxcnHFeVTIPXp65v0eKqdxJI0e) |包含任务详细信息的对象，见下文 QueryData 结构。 | #### queryData |**字段名** |**类型** |**描述** | |---|---|---| |task_id |string |任务的唯一 ID | |usage |double |本次任务消耗的创点数量，仅在任务成功时有效 | |payload |payload |任务详情 | #### payload 任务结果详情，不同类型任务的结果字段可能存在差异，以下字段为结果公共字段。 |**字段名** |**类型** |**描述** | |---|---|---| |storyboard |[storyboard](https://bytedance.larkoffice.com/wiki/BtSLwiw3ei8HZakhuB6cBd24nTd#share-TjHxdvT4MoKdUrxhHWwcFB7GnIg) |故事板结构 | #### 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](https://bytedance.larkoffice.com/wiki/BtSLwiw3ei8HZakhuB6cBd24nTd#share-Oa8oddghToSHrmxWr0ycW9Xbnub)\>

|分镜数组，每个元素表示一个分镜片段。示例：[{"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 |该分镜依赖的图片素材 URL 列表。示例：["https://p9\-aio.bytedance.com/...","https://lf26\-river\-platform\-cdn\-sign.volces.com/..."] | |audio_urls |array |该分镜依赖的音频素材 URL 列表。示例：["https://lf3\-river\-platform\-cdn\-sign.volces.com/...","https://lf26\-river\-platform\-cdn\-sign.volces.com/..."] | |video_urls

|array |该分镜依赖的视频素材 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 请求示例 ```Bash curl --location 'https://kickart.volces.com/openapi/ai_effect/query' \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "task_id": "7651900703870337075" }' ``` ### 响应示例（任务成功） ```JSON { "code": 0, "data": { "payload": { "storyboard": { "aspect_ratio": "9:16", "bgm_description": "轻快科幻,活力动感,年轻潮流,节奏明快", "language": "zh", "shots": [ { "audio_urls": [ "https://lf26-river-service-sign.volccdn.com/river-service/data/kickart/audio_assets/f1f97889-1c5a-4289-8e53-624067e50c66?x-expires=1790240721&x-signature=E1NeZ7vLQR3nLh5Un0%2BGlV6wQyk%3D" ], "duration": 4, "image_urls": [ "https://lf26-river-service-sign.volccdn.com/river-service/tmp/7952bedb-562f-4513-aceb-ce786263de2b.png?x-expires=1781687010&x-signature=H%2BOsk%2FH2c0esp25HUIw3PokZXQk%3D", "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-4-5/021781600694942ba35b7513d54f335cf228d031e636922134c00_0.jpeg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260616%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260616T090510Z&X-Tos-Expires=86400&X-Tos-Signature=4fb56a85dbff8a9c749d559881727883227ce86487c56e77e463e03e771e970d&X-Tos-SignedHeaders=host" ], "prompt": "镜头1：特写镜头，固定机位，主体为<图1>别克ELECTRA E7纯电动SUV的封闭式格栅与贯穿式分体灯组，银白香槟色车身漆面在暖调自然光下呈现细腻金属肌理，灯组结构清晰有光泽，无多余装饰。旁白内容为：想要月球飙车同款质感SUV？，音色参考<音频1>，语速每秒五个字，预留一秒画面展示缓冲。风格美学为4K超清商业质感，暖调自然光均匀照射，细节清晰。音频与音效：轻柔的车辆灯组点亮音效。模型生成限制：避免车标变形，禁止出现多余杂物。全程不要有字幕和BGM。全程不要有字幕和BGM。全程不要有字幕和BGM。", "subtitle": "想要月球飙车同款质感SUV？" }, { "audio_urls": [ "https://lf26-river-service-sign.volccdn.com/river-service/data/kickart/audio_assets/f1f97889-1c5a-4289-8e53-624067e50c66?x-expires=1790240721&x-signature=E1NeZ7vLQR3nLh5Un0%2BGlV6wQyk%3D" ], "duration": 4, "image_urls": [ "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-4-5/021781600696255505556b4fcdbd9fbe9195c53d59d355f63451e_0.jpeg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260616%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260616T090509Z&X-Tos-Expires=86400&X-Tos-Signature=df980bd3b53cf7b71e4e2a1b09628568bba8ef8f8a7d6c395034cecd0b40cbcf&X-Tos-SignedHeaders=host", "https://lf26-river-service-sign.volccdn.com/river-service/tmp/7952bedb-562f-4513-aceb-ce786263de2b.png?x-expires=1781687010&x-signature=H%2BOsk%2FH2c0esp25HUIw3PokZXQk%3D", "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-4-5/021781600694942ba35b7513d54f335cf228d031e636922134c00_0.jpeg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260616%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260616T090510Z&X-Tos-Expires=86400&X-Tos-Signature=4fb56a85dbff8a9c749d559881727883227ce86487c56e77e463e03e771e970d&X-Tos-SignedHeaders=host" ], "prompt": "镜头1：中景镜头，环绕半圈移动，主体为<图1>甜美少女主播站在<图2>别克ELECTRA E7纯电动SUV旁，齐肩碎发、穿浅灰休闲机能风外套，指尖轻触车辆隐藏式门把手，车门解锁弹出的瞬间镜头环绕车身半圈，清晰呈现银白香槟色撞色悬浮黑顶的车身造型，车顶激光雷达细节清晰，车标完整保真。旁白内容为：今天带你解锁地面极速体验！，音色参考<音频1>，语速每秒五个字，预留一秒画面展示缓冲。风格美学为4K超清商业质感，暖调自然光柔和，车身金属肌理真实。音频与音效：隐藏式门把手弹出的轻脆音效。模型生成限制：避免车身比例失真，禁止少女形象与参考不符。全程不要有字幕和BGM。全程不要有字幕和BGM。全程不要有字幕和BGM。", "subtitle": "今天带你解锁地面极速体验！" }, { "audio_urls": [ "https://lf26-river-service-sign.volccdn.com/river-service/data/kickart/audio_assets/f1f97889-1c5a-4289-8e53-624067e50c66?x-expires=1790240721&x-signature=E1NeZ7vLQR3nLh5Un0%2BGlV6wQyk%3D" ], "duration": 4, "image_urls": [ "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-4-5/021781600696255505556b4fcdbd9fbe9195c53d59d355f63451e_0.jpeg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260616%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260616T090509Z&X-Tos-Expires=86400&X-Tos-Signature=df980bd3b53cf7b71e4e2a1b09628568bba8ef8f8a7d6c395034cecd0b40cbcf&X-Tos-SignedHeaders=host", "https://lf26-river-service-sign.volccdn.com/river-service/tmp/7952bedb-562f-4513-aceb-ce786263de2b.png?x-expires=1781687010&x-signature=H%2BOsk%2FH2c0esp25HUIw3PokZXQk%3D", "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-4-5/0217816006949445630b2fa661ac131412e72f6bdd3759f4b81a7_0.jpeg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260616%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260616T090507Z&X-Tos-Expires=86400&X-Tos-Signature=4af38de8b4c50beada8fc98bd3edb3eca6ac231f44d0757315f713c848e436db&X-Tos-SignedHeaders=host" ], "prompt": "镜头1：中景镜头，固定机位，主体为<图1>甜美少女主播坐进<图3>别克ELECTRA E7驾驶舱内，手指轻点中控屏，中控屏严格贴合中控台原车安装位，内饰布局遵循量产车比例无错位，按键、座椅细节清晰，座舱内光线明亮通透。旁白内容为：搭载激光雷达，座舱静谧又舒服，音色参考<音频1>，语速每秒五个字，预留一秒画面展示缓冲。风格美学为4K超清写实质感，座舱内光线明亮，细节清晰。音频与音效：触屏点击的轻响音效。模型生成限制：禁止中控屏悬浮、穿模，避免内饰结构错位。全程不要有字幕和BGM。全程不要有字幕和BGM。全程不要有字幕和BGM。", "subtitle": "搭载激光雷达，座舱静谧又舒服" }, { "audio_urls": [ "https://lf26-river-service-sign.volccdn.com/river-service/data/kickart/audio_assets/f1f97889-1c5a-4289-8e53-624067e50c66?x-expires=1790240721&x-signature=E1NeZ7vLQR3nLh5Un0%2BGlV6wQyk%3D" ], "duration": 4, "image_urls": [ "https://lf26-river-service-sign.volccdn.com/river-service/tmp/7952bedb-562f-4513-aceb-ce786263de2b.png?x-expires=1781687010&x-signature=H%2BOsk%2FH2c0esp25HUIw3PokZXQk%3D", "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-4-5/021781600694937da22f1f1183cde111ae4437ca04d4ff480a4fe_0.jpeg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260616%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260616T090506Z&X-Tos-Expires=86400&X-Tos-Signature=9117e56700b79f53fb1ea95f0e0c6daff2c67bee3b1e5deaf5e4c49424f4173f&X-Tos-SignedHeaders=host" ], "prompt": "镜头1：中景跟拍镜头，平稳移动，主体为<图1>别克ELECTRA E7纯电动SUV平稳驶出<图2>地下车库出口，车身行驶姿态稳定，车轮碾过地面无明显颠簸，车窗外风景匀速后移，整体画面流畅有动感。旁白内容为：开起来又稳又顺，驾乘感拉满，音色参考<音频1>，语速每秒五个字，预留一秒画面展示缓冲。风格美学为4K超清动感质感，明暗过渡柔和，车身线条流畅。音频与音效：车辆行驶的低噪胎音。模型生成限制：避免车身变形，禁止车库出现多余杂物。全程不要有字幕和BGM。全程不要有字幕和BGM。全程不要有字幕和BGM。", "subtitle": "开起来又稳又顺，驾乘感拉满" }, { "audio_urls": [ "https://lf26-river-service-sign.volccdn.com/river-service/data/kickart/audio_assets/f1f97889-1c5a-4289-8e53-624067e50c66?x-expires=1790240721&x-signature=E1NeZ7vLQR3nLh5Un0%2BGlV6wQyk%3D" ], "duration": 4, "image_urls": [ "https://lf26-river-service-sign.volccdn.com/river-service/tmp/7952bedb-562f-4513-aceb-ce786263de2b.png?x-expires=1781687010&x-signature=H%2BOsk%2FH2c0esp25HUIw3PokZXQk%3D", "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/doubao-seedream-4-5/0217816006949352434549f79b621a35fed67acc24358c0ac379c_0.jpeg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYWJkZTExNjA1ZDUyNDc3YzhjNTM5OGIyNjBhNDcyOTQ%2F20260616%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260616T090507Z&X-Tos-Expires=86400&X-Tos-Signature=65298fde16b7f1719d11d78b67b9397850d22c6ddfced5674e18508e6801ac4b&X-Tos-SignedHeaders=host" ], "prompt": "镜头1：远景慢推镜头，平稳推进，主体为<图1>别克ELECTRA E7纯电动SUV在<图2>晴朗城市道路平稳行驶，流畅车身线条清晰呈现，背景是晴朗的城市街景，画面右下角弹出“即刻出发”的引导标识。旁白内容为：现在就和别克E七一起出发吧！，音色参考<音频1>，语速每秒五个字，预留一秒画面展示缓冲。风格美学为4K超清开阔质感，光线充足，画面明亮有活力。音频与音效：流畅的行驶风声。模型生成限制：避免车标模糊，禁止道路出现杂乱元素。全程不要有字幕和BGM。全程不要有字幕和BGM。全程不要有字幕和BGM。", "subtitle": "现在就和别克E七一起出发吧！" } ], "storyline": "*画面切入：近景特写别克ELECTRA E7封闭式格栅与贯穿灯组（目的：3秒抓眼钩子）* 甜美女主播坐进驾驶位，指尖轻触隐藏式门把手解锁车辆，镜头环绕车身展示银白香槟色撞色黑顶质感。旁白：“月球飙车同款质感SUV，今天带你解锁地面极速体验！” 镜头切到中控屏，主播轻点屏幕：“搭载激光雷达，安静静谧座舱，开起来稳得一批”，随后车辆平稳驶出车库，背景搭配轻快科幻BGM，结尾弹出“即刻出发”CTA贴纸。", "title": "月球同款质感！别克E7带你解锁地面极速狂飙", "video_duration": 20, "visual_style": "4K超清9:16竖屏，暖调科幻氛围感，金属车漆光泽真实，镜头运镜以环绕+跟拍为主" } }, "progress": 100, "task_id": "7651900703870337075", "usage": 0 }, "message": "success", "request_id": "202606161707599939201E5E5428518630" } ``` ### 响应示例（任务进行中） ```JSON { "code": 1000, "data": { "task_id": "7618132941507395592" }, "message": "running", "request_id": "20260317183056FA38F2B3914E1A517D02" } ``` ### 响应示例（任务失败） ```JSON { "code": 1413, "data": { "task_id": "7618132941507395594" }, "message": "ResourceDownloaderError:Failed to get resource, status: 404", "request_id": "202603171842504BE68774F527685BBBC0" } ``` --- 3. ## 取消异步任务在提交异步任务后，您可以通过此接口，使用 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 请求示例 ```Bash curl --location 'https://kickart.volces.com/openapi/ai_effect/cancel' \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "task_id": "7620360162389278779" }' ``` ### 响应示例（取消成功） ```JSON { "code": 0, "message": "success", "request_id": "202603171105302BE4CA2F5B03C331AEBD" } ``` ### 响应示例（取消失败） ```JSON { "code": 1604, "message": "river cancel failed", "request_id": "202603171842504BE68774F527685BBBC0" } ``` --- 4. ## 错误码说明所有接口的响应体中都包含 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](https://bytedance.larkoffice.com/sync/MmvedFnHjsSV1dbAj2McVA65nue) --- # 代码口径补充：一键成片故事板 API 参数 ## 1. 能力说明根据商品信息、用户素材和用户创作要求生成结构化故事板，不执行视频渲染。该入口输出首个 storyboard，适合作为上层一键成片链路中的故事板生成 API。 ## 2. 标识信息 |**能力 / 入口** |**workflowId** |**serviceId（CN）** |**说明** | |---|---|---|---| |一键成片故事板 API |[409198594](https://river.bytedance.net/space/259/workflow/409198594/draft/) |待确认 |固定生成 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. 示例输入 ```JSON { "language": "zh", "purpose": "生活服务", "duration": 45, "product_url": "", "product_id": "", "user_images": [], "user_videos": [], "product_name": "", "prompt": "目标成片时长：约44秒。\n【策划主题】\n一句话主题：承宋福雅韵，赴端午之约\n主题角度：人群=新中式长群女子；场景=竹林园林；节点=端午节；\n【关键词】\n核心关键词：典雅、清冷、静谧\n【关键结构】\n结构组成：氛围空镜/产品特写开场 + 人物带产品走场展示 + 品牌/节日祝福收尾\n【主要人物】\n25岁江南东亚女性，鹅蛋脸，柳叶眉，杏眼，冷白皮通透，宋妆淡雅，点绛唇，眉间珍珠花钿，温婉贵气，浅微笑；温柔恬静，眼神清澈；\n【场景设定】\n场景：户外中式景观场景，偏江南园林/西湖水岸风，夏日端午氛围", "aspect_ratio": "16:9", "ai_product_analysis": false, "product_selling_points": "", "product_target_audience": "" } ``` ## 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. 链路拆解 1. 校验 language/purpose/duration/aspect_ratio 枚举。 2. 非生活服务校验 product_url/product_id/user_images/user_videos 至少一个非空。 3. 非生活服务调用抖店解析与商品分析，生成商品、受众、卖点和媒体分析结果。 4. 生活服务跳过抖店解析，直接用 prompt 构造空媒体商品分析结果。 5. 构造故事板 payload，固定 version=2.0\-standard。 6. 生活服务、剧情演绎走 SingleAgent；其他 purpose 走 MVA。 7. 输出首个 storyboard，并格式化返回 shots[].material_list。 ## 8. 备注 * 当前文档描述的是仓库内 River workflow 入口，不是完整 HTTP REST API。 * 当前入口只生成故事板，不执行视频渲染，不返回 resultURL/shot_list/produceID。 * 生活服务的 material_list 可用于识别自动生成的角色图和场景图：group=role / group=location。

Kickart