## **如需开通使用本API，请联系火山** 1. # 概述本文档为Kickart OpenAPI【爆款复刻API】的官方接入指引。旨在帮助开发者通过 API 接口，快速、高效地集成和使用平台提供的 AI 能力。 **对外地址:** [https://docs.volcengine.com/docs/6664/2483603?lang=zh](https://docs.volcengine.com/docs/6664/2483603?lang=zh) 2. # 快速开始仅需两步即可完成您的首次 API 调用： 1. **申请 API Key**：在[火山-Kickart控制台](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. # OpenAPI域名 **域名: ** [https://Kickart.volces.com](https://kickart.volces.com) 4. # APIKey 申请 1. **请通过主账号登录**[Kickart首页](https://console.volcengine.com/kickart) **，仅主账号可进行APIKey的管理和查看。** 2. 导航至 [Kickart-apikey申请页面](https://console.volcengine.com/kickart/fusion/setting/api-key) 。 ![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5fc008761cb2b27338ba7cd90cf2ef62.png) 3. 在左侧菜单中选择 **「API 密钥」** 模块，然后点击 **「+新建」** 按钮。 4. 输入 API Key 名称后，点击 **「创建」** 按钮完成创建。 5. 创建成功后，您将获得一个 API Key。请妥善保管此密钥，它将作为您调用所有接口的唯一凭证。 **权限说明**：在调用接口前，请确保您的账户已开通相关服务的访问权限。若在调用过程中遇到权限问题，请联系您的企业管理员或火山引擎商务代表。 1. ## 鉴权方式所有 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。 | --- 5. # 模板说明 |
**模板 ID**
|
**模板说明**
| |---|---| |
**如需使用，请联系火山**
|
**专业模式（2.0、720p）**
| |
**如需使用，请联系火山**
|
**进阶模式（2.0 fast、720p）**
| |
**如需使用，请联系火山**
|
**进阶模式（2.0 mini、720p）**
| |
**如需使用，请联系火山**
|
**Seedance2.5（2.5、720p）**
| 6. # 接口说明 1. ## 提交异步任务该接口用于提交一个爆款复刻API 的异步处理任务。调用成功后，会立即返回一个任务 ID (task_id)，您可以使用此 ID 来查询任务的执行状态和最终结果。 * **请求方法**：POST * **请求路径**：/openapi/ai_effect/submit ### 请求参数 |**字段名** |**中文** |**类型** |**必填** |**示例** |**描述** | |---|---|---|---|---|---| |template_id

|模板 ID |string |是 |"**208714754**"

|固定值

参考「[模板说明](https://bytedance.larkoffice.com/docx/Q12pdBlI9oZ8b5xk4ebcozYsnLg#doxcntDoPYqkvYNHZaj28F2ru8f)」 | |payload |参数 |[payload](https://bytedance.larkoffice.com/docx/Q12pdBlI9oZ8b5xk4ebcozYsnLg#doxcnDXLVct1IvDkDEDAVq0snse)

|是 |参考下方示例

| JSON Object，用于传递模板渲染所需的具体参数。其内部结构见下文。 | |callback_url

|回调地址 |string

|否 |回调任务结果的公网地址, 例如

https://ar.volces.com/callback |当任务完成（无论成功或失败）时，系统会向此 URL 发送一个 POST 请求，通知您结果。

回调结果就是查询的响应参数 | |watermark

|明水印 |boolean |否 |true

默认 false |视频右下角是否添加“AI生成”水印，若需添加则传入true | |private_ips |string[]

|私有版权ID数组

|否 |[767891111111111,

767892222222222,

767893333333333]

不能超过5个

|如果传入ips, 会根据该租户的我的版权配置, 匹配相应模型的私有版权进行校验

https://console.volcengine.com/kickart/copyright\-space

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_fe504a5fce6e15c0bb093a0119ab5791.jpeg) | |无需传入, 会读取 saas 页面中的配置

|暗水印 |无需传入

|否 |和你的 saas 中配置保持一致

|
![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_3601a2533c82bec610e2da51a3fe6b20.png)
| * payload 结构 |**字段名** |**类型** |**必填** |**说明** |**参考说明** | |---|---|---|---|---| |ref_video

|string

|是

|参考视频链接

* 支持格式：MP4/ MOV

* 文件大小：≤50MB

* 视频时长：\>5秒，≤ 60秒

* 分辨率：≥480p

* 支持的画面比例：支持 9:16 、 16:9 、 3:4 、 4:3 以及 1:1 |* "ref_video": "https://static.bytednsdoc.com/obj/example/demo_video.mp4" | |role_images

|list |否

|* 图片大小/格式/分辨率/数量要求

* 图片数量：1–10 张

图片格式：JPEG / PNG

单张大小：≤ 8MB

单张分辨率：≥ 480p

* 图片长宽比：(0.4, 2.5)

* 宽高长度（px）:（300, 6000) |* "role_images": [

"https://static.example.com/role/1.jpg",

"https://static.example.com/role/2.png",

"https://static.example.com/role/3.jpg"

]

| |location_images |list

|否

|模型参考图

* 不传默认“**智能匹配**”

* 图片大小/格式/分辨率/数量要求

* 超出校验条件时按具体原因提示错误

* 图片数量：0–3 张

图片格式：JPEG / PNG

单张大小：≤ 8MB

单张分辨率：≥ 480p

* 最小像素总数： 300 \* 300 像素

* 最大像素总数： 36,000,000 像素（即 3600万像素）

* 最短边长度：最小 300 像素

* 最长边长度：最大 6000 像素 |* "location_images": [

"https://static.example.com/location/1.jpg",

"https://static.example.com/location/2.jpg"

]

| |language |string

|是

|视频语言，影响口播、字幕等

* 支持范围如下

* **default**：与原视频的语种一致

* 语言说明：

* zh：中文

* en: 英文

* en\-us：英语（美国）

* pt\-br: 葡萄牙语

* ja：日语

* es\-mx：西班牙语（墨西哥）

* id：印度尼西亚语

* ms：马来语

* tl：他加禄语（菲律宾语） |1. 默认：default

2. 举例：原视频为中文，则：

* 若用户选择default，提示词中没有明确的翻译需求，我们的输出视频的语种与原视频语种一致

* 若用户选择default，提示词中希望翻译成英文，我们的输出视频是英文视频

* 若用户在language字段选择en，提示词中没有明确的翻译需求，我们的输出视频的语种与选择的en一致

* 若用户选择en，提示词中写希望翻译成葡萄牙语，我们的输出视频是葡萄牙语视频

3. 注：

1. 尽量一段视频的语种是一致的（即，全局翻译），比如，中英混合的表现效果可能会不好

| |game_name

|string |否 |游戏名称

* ≤ 500 字符 |"剑与魔法" | |prompt |string

|否

|* 用户自定义创意策略 / 爆点描述。用于指导故事板的创意方向和内容生成。不传则使用系统默认策略。

* ≤ 5000字符 | "把视频中的人物形象换成图像中的形象，场景换成图片中的场景"

| |similarity

|string

|否

|控制复刻相似度。默认 medium

* high：高相似度，镜头结构、时长节奏、转场方式高度还原参考视频

* medium：中等相似度，保留整体风格，允许镜头组合和节奏创意调整 |* high

| |replace_images

|list

list |否

仅供 high similarity 使用，如果填入会走高相似度链路

|* 图片大小/格式/分辨率/数量要求

* 图片数量：1–10 张

图片格式：JPEG / PNG

单张大小：≤ 8MB

单张分辨率：≥ 480p

* 图片长宽比：(0.4, 2.5)

* 宽高长度（px）:（300, 6000)

* 兼容旧字段类型填入 types 字段，types 为数组类型支持单张图配置多个类型，取值范围为 "role" \| "product" \| "location" \| "default"。

```JSON```
```// 示例输入：```
```{```
``` "replace_images": [```
``` {```
``` "types":["role", "product"],```
``` "url": "https://static.example.com/1.jpg"```
``` },```
``` {```
``` "types":["role"],```
``` "url": "https://static.example.com/2.jpg"```
``` },```
``` ]```
```}```

* 支持纯 url 输入不配置图片类型

```JSON```
```// 示例输入```
```{```
``` "replace_images"：[```
``` "https://static.example.com/role/1.jpg",```
``` "https://static.example.com/role/2.png"```
``` ]```
```}```
|* 不区分role_images 和 location_images ，所有的图片统一上传到这个参数

* "replace_images"：[

"https://static.example.com/1.jpg",

"https://static.example.com/2.jpg"

"https://static.example.com/3.jpg"

]

| |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 | | |nle_subtitle_enabled

|bool

|否 |是否在生成视频中添加硬字幕（nle字幕），默认 true

true 开启，false 关闭 |true | |use_subtitle_erasure

|bool

|否

|是否在分镜渲染阶段尝试擦除视频底部字幕,默认 false

true 开启，false 关闭 |默认 false

| |resolution

|string |否 |* 视频分辨率，默认720p

* **模板604911874**：支持480p,720p,1080p,4k

* **模板463631106：** 支持480p,720p

* **模板1024515330：** 支持480p,720p

* 模板**1084731138：** 支持480p,720p,1080p |720p

| ### 响应参数 |**字段名** |**类型** |**描述** | |---|---|---| |code |int32 |状态码。0 表示任务已成功提交。非 0 值表示提交失败，原因见 message 字段。 | |message |string |状态描述信息。 | |request_id |string |本次请求的唯一标识符，可用于问题排查。 | |data |object |包含任务 ID 的数据对象。其结构为 **{"task_id": "..."}** 。 | ### cURL 请求示例中相似度请求示例 ```Shell curl --location 'https://Kickart.volces.com/openapi/ai_effect/submit' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "template_id": "208714754", "callback_url": "https://xxx", "watermark": true, "payload": { "ref_video": "https://static.bytednsdoc.com/obj/example/demo_video.mp4", "role_images": [ "https://static.example.com/role/1.jpg", "https://static.example.com/role/2.png" ], "location_images": [ "https://static.example.com/location/1.jpg", "https://static.example.com/location/2.jpg" ], "language": "zh", "game_name": "我的游戏名字", "prompt": "把视频中的人物形象换成图像中的形象，场景换成图片中的场景" } }' ``` 高相似度请求示例 ```Shell curl --location 'https://Kickart.volces.com/openapi/ai_effect/submit' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "template_id": "208714754", "callback_url": "https://xxx", "payload": { "ref_video": "https://static.bytednsdoc.com/obj/example/demo_video.mp4", "replace_images": [ "https://static.example.com/product/1.jpg", "https://static.example.com/product/2.png" ], "prompt": "将参考视频中的xx替换为图1，xx替换为图2", "language": "zh", "similarity": "high", "ai_product_analysis": true } }' ``` ### 响应示例（成功） ```JSON { "code": 0, "data": { "task_id": "7621886649043206198" //用来做查询任务的入参, 也可以等待callback }, "message": "success", "request_id": "20260330132131910C619A3D2F5FF87656" } ``` ### 响应示例（失败） ```JSON { "code": 1410, // 请参考通用错误码 "data": {}, "message": "template_id not exist", "request_id": "202603301322133EB7BAD7D1B156F75CF7" } ``` --- 2. ## 查询任务结果在提交异步任务后，您可以通过此接口，使用 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 请求示例 ```Bash curl --location 'https://Kickart.volces.com/openapi/ai_effect/query' \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "task_id": "7641408408654053419" }' ``` ### 响应示例（任务成功） ```JSON { "code": 0, "data": { "payload": { "produce_id": "1fe8d587-7eb3-4094-8624-1abc847e9248", "result_url": "https://lf11-river-service-sign.volccdn.com/river-service/tmp/c1da9aa0-ea65-422b-8e1e-04823913a84a.mp4?x-expires=1779242442&x-signature=3wXoQlARIoJZgYdJBp4q5IjsRvg%3D" }, "progress": 100, "task_id": "7641408408654053419", "usage": 1.75 }, "message": "success", "request_id": "2026051910015945648877F6FC74B0146A" } ``` ### 响应示例（任务进行中） ```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" } ``` --- ### 代码示例 |python |Java |golang | |---|---|---| |```Python```
```import requests```
```import json```
``````
```url = "https://Kickart.volces.com/openapi/ai_effect/query"```
``````
```payload = json.dumps({```
``` "task_id": "7641870195945947146"```
```})```
```headers = {```
``` 'Authorization': 'Bearer ',```
``` 'Content-Type': 'application/json'```
```}```
``````
```response = requests.request("POST", url, headers=headers, data=payload)```
``````
```print(response.text)```
|```JavaScript```
```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 ");```
``` 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();```
``` }```
``` }```
```}```
|```Go```
```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 ")```
``` 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))```
```}```
| 3. ## 取消异步任务在提交异步任务后，您可以通过此接口，使用 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 请求示例 ```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" } ``` --- ### 代码示例 |Python |Java |Golang | |---|---|---| |```Python```
```import requests```
```import json```
``````
```url = "https://Kickart.volces.com/openapi/ai_effect/cancel"```
``````
```payload = json.dumps({```
``` "task_id": "7573967600885514303"```
```})```
``````
```headers = {```
``` "Authorization": "Bearer ",```
``` "Content-Type": "application/json"```
```}```
``````
```response = requests.post(```
``` url,```
``` headers=headers,```
``` data=payload```
```)```
``````
```print("Status Code:", response.status_code)```
```print("Response:", response.text)```
|```JavaScript```
```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 "```
``` );```
``````
``` 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();```
``` }```
``` }```
```}```
|```Go```
```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 ",```
``` )```
``````
``` 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))```
```}```
| 4. ## 错误码说明所有接口的响应体中都包含 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 无效**：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 (告知多个字段和规则)

```JSON```
```{```
``` "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）的兜底。 |