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 进行鉴权，发起接口调用。 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_2f89685f89b61af9e13330b494520136.png)![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ec73216b265c98d2ddc9b843f6e3662f.png) 1. 在左侧菜单中选择 **「API Key」** 模块，然后点击 **「+New」** 按钮。 2. 输入 API Key 名称后，点击 **「Create」** 按钮完成创建。 3. 创建成功后，您将获得一个 API Key。请妥善保管此密钥，它将作为您调用所有接口的唯一凭证。 **权限说明**：在调用接口前，请确保您的账户已开通相关服务的访问权限。若在调用过程中遇到权限问题，请联系您的企业管理员或火山引擎商务代表。 1. ## 鉴权方式所有 API 接口均采用基于 HTTP Header 的 Bearer Token 鉴权方案。您需要在每次请求的 Header 中附带 Authorization 和 Content\-Type 字段。 |**Header** |**说明** | |---|---| |Authorization |认证凭证。格式必须为 Bearer {API_KEY}，其中 {API_KEY} 需要替换为您在BytePlus\-Kickart平台申请到的真实 API Key。

**示例**: Bearer 1jkdislxdsldjgeouqllsj8ko8gssccx | |Content\-Type |请求体的内容类型。固定值为 application/json。 | --- 5. # 接口说明 1. ## 提交异步任务该接口用于提交一个 AI 特效模板的异步处理任务。调用成功后，会立即返回一个任务 ID (task_id)，您可以使用此 ID 来查询任务的执行状态和最终结果。 * **请求方法**：POST * **请求路径**：/openapi/ai_effect/submit ### 请求参数 |**字段名** |**类型** |**必填** |**示例** |**描述** |说明 | |---|---|---|---|---|---| |template_id |string |是 |"1001"

|要使用的模板 ID。请从“[AI特效模板列表](https://docs.volcengine.com/docs/CreativeAgent/ai-effects-template-apiapikey-version?lang=zh#fOiLgLdx)”接口的响应中获取。 | | |payload |json

|是 |参考下方示例

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

|string

|否 |任务结果公网回调地址。

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

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

|明水印

|boolean |否 |true

默认 false

视频右下角是否添加“AI生成”水印，若需添加则传入true | | |content_producer

|string |暗水印生产者

|否 |GB45438 标识中的内容生戸者的社会信用代码 |暗水印生产者的社会信用代码。未传入时以 SaaS 配置为准；传入时以传入内容为准

![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f34ba87acb27f215470ca8d05dc06dbd.png)
| |content_propagator

|string

|暗水印内容传播者 |否

|GB45438 标识中的内容传播者

的社会信用代码 |暗水印内容传播者的社会信用代码。未传入时以 SaaS 配置为准；传入时以传入内容为准

![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4c0cab0048cb2118eb94ec6799559e33.png)

| #### payload 结构 |**字段名** |**类型** |**必填** |**描述** | |---|---|---|---| |resource_list |array

|是

|需要处理的原始媒资 URL 列表。支持公网可访问的图片 URL 或图片的 Base64 Data URI。为保证请求的稳定性和速度，强烈建议使用 **Data URI** 格式。

推荐接入火山的对象存储 https://console.volcengine.com/tos, 替换原有的TOS服务, 可提高大模型审核和生成的图片拉取成功率 | |resolution

|string

|否

|指定输出作品的分辨率，例如 "1080p"。支持的值请参考“获取模板列表”接口返回的 resolutions 字段。如果留空，将使用模板的默认分辨率。

备注: 有的模板template_id 仅支持固定的分辨率, 请在模板详情页查看 | |ratio |string |否 |选择范围: "9:16","3:4","1:1","4:3","16:9"

* 如果不指定, 系统会根据上传的图片匹配最接近的比例

* 如果指定, 可以在支持的选项中选一个, 会强制输出该尺寸, 接入方要自行控制输入图的比例来达到自己想要的效果

* 如果是多图输入模板, 必须指定一个比率

可以指定输出的画面比例, 可以在模板详情支持比例栏查询

备注: 有的模板 ratio 仅支持固定的分辨率,

![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f35f68081c8e40f0bd8e44706ddf19d8.png)
| ### 响应参数 |**字段名** |**类型** |**描述** | |---|---|---| |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": "1690784258", "callback_url": "https://muse.console.volcengine.com/api/muse/product/13477/callback", "payload": { "resolution": "1080p", "resource_list": [ "https://lf-iccloud-muse.volcmusecdn.com/obj/labcv-tob/xx.jpg" ] } }' ``` ### 响应示例（成功） ```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" } ``` ### 代码示例 |python |node |golang | |---|---|---| |```Python```
```import requests```
```import json```
``````
```API_KEY = "your_api_key_here"```
```TEMPLATE_ID = "your_template_id_here"```
```RESOURCE_LIST = ["your_resource_url_1", "your_resource_url_2"]```
```CALLBACK_URL = None```
```RESOLUTION = None```
``````
```BASE_URL = "https://kickart.volces.com"```
``````
```headers = {```
``` "Authorization": f"Bearer {API_KEY}",```
``` "Content-Type": "application/json"```
```}```
``````
```url = f"{BASE_URL}/openapi/ai_effect/submit"```
``````
```payload = {```
``` "resource_list": RESOURCE_LIST```
```}```
```if RESOLUTION:```
``` payload["resolution"] = RESOLUTION```
``````
```data = {```
``` "template_id": TEMPLATE_ID,```
``` "payload": payload```
```}```
```if CALLBACK_URL:```
``` data["callback_url"] = CALLBACK_URL```
``````
```try:```
``` response = requests.post(url, headers=headers, data=json.dumps(data))```
``` response.raise_for_status()```
``` result = response.json()```
``` ```
``` if result.get("code") == 0 and result.get("data"):```
``` task_id = result["data"]["task_id"]```
``` else:```
``` print(f"submit task failed: {result.get('message', 'Unknown error')}")```
``````
```except requests.exceptions.RequestException as e:```
``` print(f"error: {e}")```
```except Exception as e:```
``` print(f"error: {e}")```
|```JavaScript```
```const BASE_URL = 'https://kickart.volces.com';```
``````
```const API_KEY = 'YOUR_API_KEY';```
```const TEMPLATE_ID = 'YOUR_TEMPLATE_ID';```
```const RESOURCE_LIST = ['resource_url_1', 'resource_url_2'];```
```const RESOLUTION = '1080p';```
```const CALLBACK_URL = 'https://your-domain.com/callback';```
``````
```async function submitTask() {```
``` const url = `${BASE_URL}/openapi/ai_effect/submit`;```
``` ```
``` const requestBody = {```
``` template_id: TEMPLATE_ID,```
``` payload: {```
``` resource_list: RESOURCE_LIST,```
``` resolution: RESOLUTION```
``` },```
``` callback_url: CALLBACK_URL```
``` };```
``````
``` try {```
``` const response = await fetch(url, {```
``` method: 'POST',```
``` headers: {```
``` 'Authorization': `Bearer ${API_KEY}`,```
``` 'Content-Type': 'application/json'```
``` },```
``` body: JSON.stringify(requestBody)```
``` });```
``````
``` if (!response.ok) {```
``` throw new Error(`HTTP error! status: ${response.status}`);```
``` }```
``````
``` const result = await response.json();```
``` ```
``` return result;```
``` } catch (error) {```
``` console.error('error:', error);```
``` throw error;```
``` }```
```}```
``````
```submitTask();```
|```Go```
```package main```
``````
```import (```
``` "bytes"```
``` "encoding/json"```
``` "fmt"```
``` "io"```
``` "net/http"```
``` "time"```
```)```
``````
```func SubmitTask() {```
``` const (```
``` apiKey = "YOUR_API_KEY"```
``` templateID = "YOUR_TEMPLATE_ID"```
``` callbackURL = "YOUR_CALLBACK_URL"```
``` resolution = "1080p"```
``` )```
``````
``` resourceList := []string{"resource_url_1", "resource_url_2"}```
``````
``` requestBody := map[string]interface{}{```
``` "template_id": templateID,```
``` "payload": map[string]interface{}{```
``` "resource_list": resourceList,```
``` "resolution": resolution,```
``` },```
``` "callback_url": callbackURL,```
``` }```
``````
``` body, err := json.Marshal(requestBody)```
``` if err != nil {```
``` return```
``` }```
``````
``` url := "https://kickart.volces.com/openapi/ai_effect/submit"```
``` req, err := http.NewRequest("POST", url, bytes.NewReader(body))```
``` if err != nil {```
``` return```
``` }```
``````
``` req.Header.Set("Authorization", "Bearer "+apiKey)```
``` req.Header.Set("Content-Type", "application/json")```
``````
``` client := &http.Client{```
``` Timeout: 30 * time.Second,```
``` }```
``````
``` resp, err := client.Do(req)```
``` if err != nil {```
``` return```
``` }```
``` defer resp.Body.Close()```
``````
``` respBody, err := io.ReadAll(resp.Body)```
``` if err != nil {```
``` return```
``` }```
``````
``` var response map[string]interface{}```
``` if err := json.Unmarshal(respBody, &response); err != nil {```
``` return```
``` }```
``````
``` if data, ok := response["data"].(map[string]interface{}); ok {```
``` fmt.Printf("task_id: %s\n", data["task_id"])```
``` }```
``` fmt.Printf("response: %s\n", string(respBody))```
```}```
| ```JSON { "code": 0, "message": "success", "request_id": "2024031211223301017205503512345678", "data": { "task_id": "7573967600885514303" } } ``` --- 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/OfLwdwNPEopsoPxVW6xcpDl3n0e?contentTheme=DARK&last_doc_message_id=7622959140566371552&preview_comment_id=7622959347257215958&sourceType=feed&theme=light#doxcnmvEX0sGNmmgaoFDcwWLERL) |包含任务详细信息的对象，见下文 QueryData 结构。 | #### queryData |**字段名** |**类型** |**描述** | |---|---|---| |task_id |string |任务的唯一 ID | |usage |double |本次任务消耗的创点数量，仅在任务成功时有效 | |payload |[payload](https://bytedance.larkoffice.com/docx/OfLwdwNPEopsoPxVW6xcpDl3n0e?contentTheme=DARK&last_doc_message_id=7622959140566371552&preview_comment_id=7622959347257215958&sourceType=feed&theme=light#doxcn2liETCALAy6ek51BFDLrjf) |任务详情 | #### 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": "7620360162389278779" }' ``` ### 响应示例（任务成功） ```JSON { "code": 0, "data": { "payload": { "result_url": "https://lf16-river-service-sign.creative-agent-cdn.com/obj/river-service-asiasebd/tmp/7865e9bf-35a5-4775-89cd-f323499efa54.mp4?x-expires=1773802681&x-signature=WqtrjGoK3IE6i6G1a6t0ChToEUw%3D", "produce_id": "06fc1bda-e077-4ed9-9fbc-8ff137e5d03e", "any_key": "value1" }, "task_id": "7617833350455099399", "usage": 0.36 }, "message": "success", "request_id": "202603171105302BE4CA2F5B03C331AEBD" } ``` ### 响应示例（任务进行中） ```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 |node |golang | |---|---|---| |```Python```
``` import requests```
```import json```
``````
```BASE_URL = "https://kickart.volces.com"```
```API_KEY = "YOUR_API_KEY"```
```TASK_ID = "YOUR_TASK_ID"```
``````
```def query_task():```
``` url = f"{BASE_URL}/openapi/ai_effect/query"```
``` ```
``` headers = {```
``` "Authorization": f"Bearer {API_KEY}",```
``` "Content-Type": "application/json"```
``` }```
``` ```
``` data = {```
``` "task_id": TASK_ID```
``` }```
``` ```
``` try:```
``` response = requests.post(url, headers=headers, data=json.dumps(data))```
``` response.raise_for_status()```
``` ```
``` result = response.json()```
``` print(json.dumps(result, indent=2, ensure_ascii=False))```
``` ```
``` if result.get("code") == 0:```
``` print(f"task id: {result.get('data', {}).get('task_id')}")```
``` if result.get('data', {}).get('usage') is not None:```
``` print(f"usage: {result['data']['usage']:.2f}")```
``` if result.get('data', {}).get('payload'):```
``` print("result payload:")```
``` print(json.dumps(result['data']['payload'], indent=2, ensure_ascii=False))```
``` else:```
``` print(f"\nquery failed: {result.get('message')}")```
``` ```
``` except requests.exceptions.RequestException as e:```
``` print(f"error: {e}")```
``` except Exception as e:```
``` print(f"error: {e}")```
``````
```if __name__ == "__main__":```
``` query_task()```
|```JavaScript```
```const BASE_URL = 'https://kickart.volces.com';```
```const API_KEY = 'YOUR_API_KEY';```
```const TASK_ID = 'YOUR_TASK_ID';```
``````
```async function queryTask() {```
``` const url = `${BASE_URL}/openapi/ai_effect/query`;```
``` const requestBody = {```
``` task_id: TASK_ID```
``` };```
``````
``` try {```
``` const response = await fetch(url, {```
``` method: 'POST',```
``` headers: {```
``` 'Authorization': `Bearer ${API_KEY}`,```
``` 'Content-Type': 'application/json'```
``` },```
``` body: JSON.stringify(requestBody)```
``` });```
``````
``` if (!response.ok) {```
``` throw new Error(`HTTP error! status: ${response.status}`);```
``` }```
``````
``` const data = await response.json();```
``````
``` if (data.code === 0) {```
``` console.log(`task id: ${data.data.task_id}`);```
``` if (data.data.usage) {```
``` console.log(`usage: ${data.data.usage.toFixed(2)}`);```
``` }```
``` if (data.data.payload) {```
``````
``` console.log(JSON.stringify(data.data.payload, null, 2));```
``` }```
``` } else {```
``` console.log('\nquery task failed:', data.message);```
``` }```
``` } catch (error) {```
``` console.error('query task failed:', error);```
``` }```
```}```
``````
```queryTask();```
|```Go```
```package main```
``````
```import (```
``` "bytes"```
``` "encoding/json"```
``` "fmt"```
``` "io"```
``` "net/http"```
``` "time"```
```)```
``````
```func QueryTask() {```
``` const (```
``` apiKey = "YOUR_API_KEY"```
``` taskID = "YOUR_TASK_ID"```
``` )```
``````
``` requestBody := map[string]interface{}{```
``` "task_id": taskID,```
``` }```
``````
``` body, err := json.Marshal(requestBody)```
``` if err != nil {```
``````
``` return```
``` }```
``````
``` url := "https://kickart.volces.com/openapi/ai_effect/query"```
``` req, err := http.NewRequest("POST", url, bytes.NewReader(body))```
``` if err != nil {```
``` ```
``` return```
``` }```
``````
``` req.Header.Set("Authorization", "Bearer "+apiKey)```
``` req.Header.Set("Content-Type", "application/json")```
``````
``` client := &http.Client{```
``` Timeout: 30 * time.Second,```
``` }```
``````
``` resp, err := client.Do(req)```
``` if err != nil {```
``` return```
``` }```
``` defer resp.Body.Close()```
``````
``` respBody, err := io.ReadAll(resp.Body)```
``` if err != nil {```
``` return```
``` }```
``````
``` var response map[string]interface{}```
``` if err := json.Unmarshal(respBody, &response); err != nil {```
``` return```
``` }```
``````
``` if data, ok := response["data"].(map[string]interface{}); ok {```
``` fmt.Printf("task_id: %s\n", data["task_id"])```
``` if usage, ok := data["usage"]; ok {```
``` fmt.Printf("usage: %.2f\n", usage)```
``` }```
``` if payload, ok := data["payload"]; ok {```
``` fmt.Printf("task result: %v\n", payload)```
``` }```
``` }```
``` fmt.Printf("response: %s\n", string(respBody))```
```}```
| 3. ## AI特效模板列表该接口用户分页查询平台提供的AI特效模板列表，返回的模板数据中 template_id 可用于生成对应AI特效视频效果。 * **请求方法**：POST * **请求路径**：/openapi/ai_effect/list_ai_templates ### 请求参数 |**字段名** |**类型** |**必填** |**示例** |**描述** | |---|---|---|---|---| |page_number

|int

|否 |1

|列表分页参数，默认从1 | |page_size

|int

|否 |10 |每页大小，取值范围[10,50] | |category_code |string

|否

|2114584576

|模板分类，见[CategoryCode可选值](https://bytedance.larkoffice.com/wiki/CuN9wqKsPiWaLDkwCbGc6uAonre#share-I9t5dtJEKoJvOOxmEm6c7sYen4c)。

不传则默认拉取【全部】分类 | |keyword |string |否 |模板名称 |名称搜索 | |release_online_time_range |list |否 |[1775112021, 1775112022] |上线时间区间，秒级时间戳。

| |template_type |string |否 |IMAGE_TO_IMAGE |模板类型，见 [template_type可选值](https://bytedance.larkoffice.com/wiki/CuN9wqKsPiWaLDkwCbGc6uAonre#share-OeKod7wOsoNbjLxLx2cc7s5Onth)。 | |template_id |string |否 |123 |模板ID | |service_id |string |否 |12345 |服务ID | |input_requirement |string |否 |SINGLE_PERSON |输入图要求，见 [input_requirement可选值](https://bytedance.larkoffice.com/wiki/CuN9wqKsPiWaLDkwCbGc6uAonre#share-V2zidGMByoo7nLxE10YcQrbwnOe) | |input_num |int |否 |1 |输入图数量 | |sort_reg |int |否 |1 |1是升序，\-1是降序 | |sort_name |string |否 |release_online_time |支持按上线时间排序:release_online_time，不传按默认顺序 | #### category_code 可选值 |全部 |最新上线 |热门 |节日 |可爱萌宠 |华丽变身 |风格重塑 |超能力创意 |趣味搞怪 |TOP10调用榜 | |---|---|---|---|---|---|---|---|---|---| |2114584576 |2115108864 |2113994752 |2114060288 |2114256896 |2114322432 |2114387968 |2114453504 |2114519040 |2114846720 | #### template_type 可选值 |图生图 |图生视频 |首尾帧 |全能参考 | |---|---|---|---| |IMAGE_TO_IMAGE |IMAGE_TO_VIDEO |BEGIN_END_FRAME |OMNI_REFERENCE | #### input_requirement可选值 |单人 |两人 |多人 |宠物 |无限制 |单人女性 |单人男性 |门 | |---|---|---|---|---|---|---|---| |SINGLE_PERSON |DOUBLE_PRESON |MULTI_PRESON |PET |NO_LIMIT |SINGLE_WOMAN |SINGLE_MAN |DOOR | ### 响应参数 |**字段名** |**类型** |**描述** | |---|---|---| |code |int32 |状态码。0 表示请求成功。非 0 值表示请求失败，原因见 message 字段，具体含义请参考“[错误码说明](https://bytedance.larkoffice.com/docx/Q1yjdWNbyolu3FxRgu0cVO9ynib#share-QSSIdUp7FoTxPuxdlDacs0H4n1c)”章节。 | |message |string |状态描述信息。 | |request_id |string |本次请求的唯一标识符，可用于问题排查。 | |data |object |包含AI特效模板数据的对象，其结构见下文 data 结构。 | #### data 结构 |**字段名** |**类型** |**描述** | |---|---|---| |medias |list |AI特效模板列表，可能为空列表 | |total_count |int |模板总数（指定条件下的数量） | #### medias 列表元素结构 |**字段名** |**类型** |**描述** | |---|---|---| |media_id |string |素材id | |title |string |模板名称 | |cover |string |模板封面图 | |duration |double |模板视频时长（单位毫秒） | |preview_video |string |封面预览视频 | |tags |list |模板标签 | |service_id |string |服务ID | |template_id |string |模板ID | |template_type |string |模板类型 | |input_requirement |string |输入图要求 | |input_num |int |输入图数量 | |release_online_time |int64 |模板发布上线时间 | |consume_items |list |模板支持的分辨率及创点消耗列表 | #### consume_items 列表元素结构 |**字段名** |**类型** |**描述** | |---|---|---| |resolution |string |模板支持的分辨率 | |usage |double |分辨率对应的创点消耗 | 4. ## 错误码说明所有接口的响应体中都包含 code 和 message 字段，用于指示请求的处理结果。当 code 为 0 时，表示业务处理成功。非 0 值表示出现了异常。 ### 通用错误码 |错误码 |错误类型(标记用, 不会返回) |描述与处理建议 | |---|---|---| |1300 |AuthFailed

|**认证失败**：API Key 无效、过期或未激活。请检查您的 API Key 是否正确，或在火山引擎控制台确认其状态。 | |1400 |ParamErr

|**参数错误**：请求中包含无效或缺失的参数。请对照文档检查请求体结构、字段类型和必填项。 | |1401 |ConcurrentErr

|**并发超限**：您当前的并发请求数超过了约定的上限。请降低请求频率，或联系商务代表调整并发额度。 | |1403 |QuotaErr |**无权限**：您的账户没有调用此接口的权限。请联系企业管理员为您开通相关服务的访问权限。 | |1402

|InsufficientPoints

|**创点不足**：账户余额不足以支付本次任务消耗。请及时充值。 | |1500 |InternalErr |**内部错误**：服务端发生未知错误。请记录 request_id 并联系技术支持。 | ### 接口特定错误码 #### /openapi/ai_effect/submit & /openapi/ai_effect/query |错误码 |错误类型(标记用, 不会返回) |描述与处理建议 | |---|---|---| |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）的兜底。 |