概述

本文档为创作Agent OpenAPI【爆款裂变 API】的官方接入指引。旨在帮助开发者通过 API 接口，快速、高效地集成和使用平台提供的 AI 能力。

快速开始

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

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

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

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

OpenAPI域名

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

APIKey 申请

请通过主账号登录创作Agent首页，仅主账号可进行APIKey的管理和查看。

导航至 kickart-apikey申请页面。

在左侧菜单中选择「API 密钥」模块，然后点击「+新建」按钮。

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

创建成功后，您将获得一个 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	模板说明
978755330	专业模式（seedance 2.5、720p）
208714754	专业模式（seedance 2.0、720p）
346374402	进阶模式（seedance 2.0 fast、720p）
1028571394	mini模式（seedance 2.0 mini、720p）

接口说明

提交异步任务

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

请求方法：POST

请求路径：/openapi/ai_effect/submit

请求参数

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

payload 结构

字段名	类型	必填	说明	参考说明
ref_video	string	是	参考视频链接支持格式：MP4/ MOV 文件大小：≤200MB 视频时长：>5秒，≤ 60秒分辨率：≥480p 支持的画面比例：支持 9:16 、 16:9 、 3:4 、 4:3 以及 1:1 成片视频会参考ref_video的视频的比例	"ref_video": "https://static.bytednsdoc.com/obj/example/demo_video.mp4"
product_url	string	product_url、product_id、product_images至少存在一个有效值高相似度下非必填	输入抖店商品链接高相似度暂不支持	商品链接和商品ID同时存在的情况，取商品ID "product_url": "https://www.tiktok.com/view/product/172839182" "product_id": "172839182" 获取抖店商品链接、ID请参考：抖音商品ID、商品详情页链接怎么获取？
product_id	string				输入抖店商品ID 高相似度暂不支持
product_images	list<string>			商品图链接图片数量：1–10 张图片格式：JPEG / PNG 单张大小：≤ 30MB 单张分辨率：≥ 480p 宽高比 >0.4 ，< 2.5 最小像素总数： 300 * 300 像素最大像素总数： 36,000,000 像素（即 3600万像素）最短边长度：最小 300 像素最长边长度：最大 6000 像素	"product_images": [ "https://static.example.com/product/1.jpg", "https://static.example.com/product/2.png", "https://static.example.com/product/3.jpg" ]
model_images	list <string>	否	模特参考图不传默认“智能匹配” 图片大小/格式/分辨率/数量要求超出校验条件时按具体原因提示错误图片数量：0–3 张图片格式：JPEG / PNG 单张大小：≤ 30MB 单张分辨率：≥ 480p 最小像素总数： 300 * 300 像素最大像素总数： 36,000,000 像素（即 3600万像素）最短边长度：最小 300 像素最长边长度：最大 6000 像素	"model_images": [ "https://static.example.com/model/model_1.jpg", "https://static.example.com/model/model_2.jpg" ]
language	string	是	视频语言，影响口播、字幕等支持范围如下语言说明： zh：中文 en: 英文 en-us：英语（美国） pt-br: 葡萄牙语 ja：日语 es-mx：西班牙语（墨西哥） id：印度尼西亚语 ms：马来语 tl：他加禄语（菲律宾语）	"language": "zh"
ai_product_analysis	bool	否	是打开AI分析卖点、目标受众不传默认开启参数说明 true：开启 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	"上班族，低头族"
nle_subtitle_enabled	bool	否	是否在生成视频中添加硬字幕（nle字幕），默认 true true 开启，false 关闭	true
prompt	string	否	用户自定义创意策略 / 爆点描述。用于指导故事板的创意方向和内容生成。 ≤ 5000字符	“结合我的商品<商品图1><商品图2>，模特图<模特图2>，场景图<场景图1>参考提供视频的故事情节、剧情节奏、口播风格，生成视频”
use_subtitle_erasure	bool	否	是否在分镜视频渲染阶段，尝试擦除模型生成的字幕注意字幕擦除等待时间较长，根据视频时长增加 true 尝试擦除，false 不擦除	默认 false
location_images	string[]	否	场景 / 地点参考图，图片格式要求同上 purpose =生活服务的时候生效，最多支持3张	默认空数组
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	720p
purpose	string	否	默认（电商），枚举值：电商、生活服务	生活服务
compliance_enabled	bool	否	是否开启合规预审，默认false	false
bgm_mode	string	否	BGM 使用模式，不传默认 auto： none：无 BGM，静音BGM auto：智能识别BGM意图 custom：使用自定义 BGM（需配合 bgm_url） origin_bgm：从原始音频分离BGM纯音乐	"auto"
bgm_url	string	仅当 bgm_mode=custom 时必填	自定义 BGM 文件 URL。时长适配策略：BGM 短于视频时循环播放；长于视频时截取（以视频时长为准）校验规则：格式 mp3 / wav；大小 ≤ 50MB
similarity	string	否	复刻相似度 high 为高相似度复刻 medium 为中等相似度复刻	high

响应参数

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

cURL 请求示例

响应示例（成功）

响应示例（失败）

代码示例

Python	Java	Golang
import requests import json url = "https://kickart.volces.com/openapi/ai_effect/submit" payload = json.dumps({ "template_id": "208714754", "callback_url": "https://xxx", "payload": { "ref_video": "https://static.bytednsdoc.com/obj/example/demo_video.mp4", "product_url": "https://www.tiktok.com/view/product/172839182", "product_id": "172839182", "product_images": [ "https://static.example.com/product/1.jpg", "https://static.example.com/product/2.png" ], "model_images": [ "https://static.example.com/model/model_1.jpg", "https://static.example.com/model/model_2.jpg" ], "language": "zh", "ai_product_analysis": True } }) headers = { 'Authorization': 'Bearer <your API_key>', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)	import java.io.IOException; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class KickArtDemo { public static void main(String[] args) throws IOException, InterruptedException { String url = "https://kickart.volces.com/openapi/ai_effect/submit"; String jsonBody = """ { "template_id": "208714754", "callback_url": "https://xxx", "payload": { "ref_video": "https://static.bytednsdoc.com/obj/example/demo_video.mp4", "product_url": "https://www.tiktok.com/view/product/172839182", "product_id": "172839182", "product_images": [ "https://static.example.com/product/1.jpg", "https://static.example.com/product/2.png" ], "model_images": [ "https://static.example.com/model/model_1.jpg", "https://static.example.com/model/model_2.jpg" ], "language": "zh", "ai_product_analysis": true } } """; HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Authorization", "Bearer <your API_key>") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(jsonBody)) .build(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString() ); System.out.println("HTTP Status: " + response.statusCode()); System.out.println("Response Body:"); System.out.println(response.body()); } }	package main import ( "bytes" "fmt" "io" "net/http" ) func main() { url := "https://kickart.volces.com/openapi/ai_effect/submit" jsonBody := `{ "template_id": "208714754", "callback_url": "https://xxx", "payload": { "ref_video": "https://static.bytednsdoc.com/obj/example/demo_video.mp4", "product_url": "https://www.tiktok.com/view/product/172839182", "product_id": "172839182", "product_images": [ "https://static.example.com/product/1.jpg", "https://static.example.com/product/2.png" ], "model_images": [ "https://static.example.com/model/model_1.jpg", "https://static.example.com/model/model_2.jpg" ], "language": "zh", "ai_product_analysis": true } }` req, err := http.NewRequest( "POST", url, bytes.NewBuffer([]byte(jsonBody)), ) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer <your API_key>") req.Header.Set("Content-Type", "application/json") client := &http.Client{} resp, err := client.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { panic(err) } fmt.Println("HTTP Status:", resp.StatusCode) fmt.Println("Response:", string(body)) }

查询任务结果

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

请求方法：POST

请求路径：/openapi/ai_effect/query

请求参数

字段名	类型	必填	示例	描述
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

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

字段名	类型	描述
result_url	string	任务结果地址

关于 result_url 的有效期

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

cURL 请求示例

响应示例（任务成功）

响应示例（任务进行中）

响应示例（任务失败）

代码示例

python	Java	golang
import requests import json url = "https://kickart.volces.com/openapi/ai_effect/query" payload = json.dumps({ "task_id": "7641870195945947146" }) headers = { 'Authorization': 'Bearer <API—key>', 'Content-Type': 'application/json' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)	import java.io.BufferedReader; import java.io.InputStreamReader; import java.io.OutputStream; import java.net.HttpURLConnection; import java.net.URL; public class QueryTaskExample { public static void main(String[] args) { try { String url = "https://kickart.volces.com/openapi/ai_effect/query"; String jsonInputString = "{\n" + " \"task_id\": \"7641870195945947146\"\n" + "}"; URL obj = new URL(url); HttpURLConnection connection = (HttpURLConnection) obj.openConnection(); // 设置请求方式 connection.setRequestMethod("POST"); // 设置请求头 connection.setRequestProperty("Authorization", "Bearer <API-key>"); connection.setRequestProperty("Content-Type", "application/json"); // 允许写入请求体 connection.setDoOutput(true); // 写入请求体 try (OutputStream os = connection.getOutputStream()) { byte[] input = jsonInputString.getBytes("utf-8"); os.write(input, 0, input.length); } // 获取响应 int responseCode = connection.getResponseCode(); System.out.println("Response Code: " + responseCode); BufferedReader br = new BufferedReader( new InputStreamReader(connection.getInputStream(), "utf-8") ); StringBuilder response = new StringBuilder(); String responseLine; while ((responseLine = br.readLine()) != null) { response.append(responseLine.trim()); } System.out.println("Response Body:"); System.out.println(response.toString()); } catch (Exception e) { e.printStackTrace(); } } }	package main import ( "bytes" "fmt" "io" "net/http" ) func main() { url := "https://kickart.volces.com/openapi/ai_effect/query" payload := []byte(`{ "task_id": "7641870195945947146" }`) req, err := http.NewRequest("POST", url, bytes.NewBuffer(payload)) if err != nil { panic(err) } // 设置请求头 req.Header.Set("Authorization", "Bearer <API-key>") req.Header.Set("Content-Type", "application/json") // 发起请求 client := &http.Client{} resp, err := client.Do(req) if err != nil { panic(err) } defer resp.Body.Close() // 读取响应 body, err := io.ReadAll(resp.Body) if err != nil { panic(err) } fmt.Println("Response Status:", resp.Status) fmt.Println("Response Body:", string(body)) }

取消异步任务

在提交异步任务后，您可以通过此接口，使用 task_id 来提交申请取消任务。

请求方法：POST

请求路径：/openapi/ai_effect/cancel

请求参数

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

响应参数

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

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

cURL 请求示例

响应示例（取消成功）

响应示例（取消失败）

代码示例

Python	Java	Golang
import requests import json url = "https://kickart.volces.com/openapi/ai_effect/cancel" payload = json.dumps({ "task_id": "7573967600885514303" }) headers = { "Authorization": "Bearer <API-key>", "Content-Type": "application/json" } response = requests.post( url, headers=headers, data=payload ) print("Status Code:", response.status_code) print("Response:", response.text)	import java.io.BufferedReader; import java.io.InputStreamReader; import java.io.OutputStream; import java.net.HttpURLConnection; import java.net.URL; public class CancelTaskHttpURLConnection { public static void main(String[] args) { try { String url = "https://kickart.volces.com/openapi/ai_effect/cancel"; String jsonInputString = "{\n" + " \"task_id\": \"7573967600885514303\"\n" + "}"; URL obj = new URL(url); HttpURLConnection connection = (HttpURLConnection) obj.openConnection(); connection.setRequestMethod("POST"); connection.setRequestProperty( "Authorization", "Bearer <API-key>" ); connection.setRequestProperty( "Content-Type", "application/json" ); connection.setDoOutput(true); try (OutputStream os = connection.getOutputStream()) { byte[] input = jsonInputString.getBytes("utf-8"); os.write(input, 0, input.length); } int responseCode = connection.getResponseCode(); System.out.println("HTTP Status: " + responseCode); BufferedReader br = new BufferedReader( new InputStreamReader( connection.getInputStream(), "utf-8" ) ); StringBuilder response = new StringBuilder(); String responseLine; while ((responseLine = br.readLine()) != null) { response.append(responseLine.trim()); } System.out.println("Response:"); System.out.println(response.toString()); } catch (Exception e) { e.printStackTrace(); } } }	package main import ( "bytes" "encoding/json" "fmt" "io" "net/http" ) type CancelTaskRequest struct { TaskID string `json:"task_id"` } func main() { url := "https://kickart.volces.com/openapi/ai_effect/cancel" reqBody := CancelTaskRequest{ TaskID: "7573967600885514303", } jsonData, err := json.Marshal(reqBody) if err != nil { panic(err) } req, err := http.NewRequest( "POST", url, bytes.NewBuffer(jsonData), ) if err != nil { panic(err) } req.Header.Set( "Authorization", "Bearer <API-key>", ) req.Header.Set( "Content-Type", "application/json", ) client := &http.Client{} resp, err := client.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { panic(err) } fmt.Println("Response:") fmt.Println(string(body)) }

错误码说明

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

通用错误码

错误码	错误类型(标记用, 不会返回)	描述与处理建议
1300	AuthFailed	认证失败：API Key 无效、过期或未激活。请检查您的 API Key 是否正确，或在火山引擎控制台确认其状态。
1400	ParamErr	参数错误：请求中包含无效或缺失的参数。请对照文档检查请求体结构、字段类型和必填项。
1401	ConcurrentErr	并发超限：您当前的并发请求数超过了约定的上限。请降低请求频率，或联系商务代表调整并发额度。
1403	QuotaErr	无权限：您的账户没有调用此接口的权限。请联系企业管理员为您开通相关服务的访问权限。
1402	InsufficientPoints	创点不足：账户余额不足以支付本次任务消耗。请及时充值。
1418	InvalidDurationBillingErr	无效时长参数：入参时长参数不满足接口入参要求
1423	VideoResolutionError	参考视频分辨率错误
1424	VideoDurationError	参考视频时长错误
1425	VideoFormatError	参考视频格式错误
1426	VideoSizeError	参考视频大小错误
1427	RefVideoError	参考视频链接错误
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 无效：payload.model_images 中的 URL 无法访问。请确保 URL 是公网可达的，且未过期。
1414	MediaSensitiveErr	内容安全问题：输入内容触发了平台的安全审核策略。请更换内容后重试。
1415	OutputMediaSensitiveErr	内容安全问题：输出内容触发了平台的安全审核策略。请更换内容后重试。
1416	InvalidMediaCountErr	错误的媒体数量：检查素材的数量是否满足模板要求。
1417	ChatCompletionError	大模型调用错误：大模型在调用时抛出的异常，请根据具体的错误信息进行重试。
1421	DurationEnumError	入参时长枚举值错误：入参时长参数不满足接口入参枚举值要求
1422	GetDouDianProductInfoError	抖店商品信息获取失败错误：检查抖店商品链接或ID是否正确
1428	LanguageEnumError	语言枚举值错误：检查入参的语言字段是否与模板支持的语言枚举值匹配
1429	ModelImageCountError	图片数量超出：payload.model_images 图片数量不能超过4个
1600	AsyncTaskNotExist	任务不存在：查询的 task_id 无效。请检查 task_id 是否为 AITemplateAsyncTaskSubmit 接口成功返回的值。
1601	AsyncTaskTimeoutErr	任务超时：任务执行超过了系统设定的最长处理时间（当前为 1 小时）。
1602	AsyncTaskCanceled	任务已取消：任务已取消
1603	AsyncTaskEnded	任务已结束：任务已处于成功/失败状态，不可取消
1604	AsyncTaskCancelFailed	任务取消失败：任务取消失败，请稍后重试
2000	AsyncTaskFailed	任务失败：任务在执行过程中发生未能归类的失败。
5000	RiverWorkflowFailed	工作流失败：底层 AI 工作流执行失败，通常为更具体的错误（如 1412-1414）的兜底。

Kickart