# 版本变更记录 |版本 |修改时间 |变更内容 |备注 | |---|---|---|---| |v1.0 |2025\-11\-25 |1. 初始化文档 | | |v1.1 |2026\-02\-02 |1. 新增结果回调接入指引 | | |v1.2 |2026\-03\-27 |1. 新增AI特效模板列表接口 | | # 公共字段 ## 1. 请求Host * **https://icp.volcengineapi.com** ## 2. 请求Header * 描述：**Http请求中header需增加的字段** |**参数名** |**参数类型** |**是否必填** |**描述** | |---|---|---|---| |X\-Date |String |是 |使用UTC时间，精确到秒。请使用格式：`YYYYMMDD'T'HHMMSS'Z'` ，例如：`20201103T104027Z` | |Authorization |String |是 |`HMAC-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}`|\ | | | ||\ | | | |* 签名完整过程详见：[签名示例](https://www.volcengine.com/docs/6369/67269)|\ | | | |* 签名Demo详见下面 `3. 代码样例` | |Content\-Type |String |是 |MIME类型，**固定值：** **`application/json`** | |X\-Content\-Sha256 |String |否 |对完整请求Body的加密结果，`HexEncode(Hash(RequestPayload))`|\ | | | |> `HexEncode`HexEncode代指转16进制编码|\ | | | |> `Hash`代指SHA256算法|\ | | | |> `RequestPayload`代指完整的请求的body。 | **Authorization中的信息含义：** |**名称** |**类型** |**备注** | |---|---|---| |AccessKeyId |String |请求的AccessKey。|\ | | ||\ | | |* AK/SK获取说明|\ | | | * 说明：在调用火山引擎视觉智能控制台的各个能力之前，确保您已生成访问密钥（AccessKey）。AccessKey包括AccessKeyID（AK）和AccessKeySecret（SK），其中AccessKeyID用于标识用户，AccessKeySecret是用来验证用户的密钥，请妥善保管。|\ | | | * 获取方式：点击右上角账号，下拉列表选择【密钥管理】，点击【新建密钥】按钮，可获取AK/SK，可以此为凭证调用上述已接入应用的接口|\ | | | 注：安全起见，建议新建子账户，并使用子账户的AK/SK|\ | | ||\ | | |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_05dc7abdbe5f3b87c3645533ff067ca5.png) | |ShortDate |String |请求的短时间，使用UTC时间，精确到日。请使用格式：YYYYMMDD，例如：20221101 | |Region |String |请求的地域，**固定值：** **`cn-north-1`** | |Service |String |请求的服务，**固定值：** **`iccloud_muse`** | |SignedHeaders |String |参与签名的Header，用分号分隔。 | |Signature |String |计算完毕的签名。 | ## 3. 代码样例 |Java |Golang |Python | |---|---|---| |* 鉴权 : `getSignedKey`|* 鉴权 : `func getSignedKey`|* 鉴权 : `def get_signed_key`|\ |* 发起任务 : `doRequest`|* 发起任务 :`func do_request`|* 发起任务 :`def do_request`|\ |* 并通过 TaskId 轮询结果: `queryUntilDone` |* 并通过 TaskId 轮询结果: `func submitAndQuery` |* 并通过 TaskId 轮询结果: `def submit_and_query` | ||||\ |```sql|```sql|```sql|\ |java -cp "out:lib/*" VolcEngineApiClient|go run api_sample.go|python api_sample.py|\ |javac -encoding UTF-8 -cp "lib/*" -d out src/VolcEngineApiClient.java|```|```|\ |```| | |\ | | | | # HTTP接口详情 ## 1. AI模板消费 ### **SubmitAiTemplateTaskAsync** * 描述：提交AI模板消费异步任务 * Method：**POST** * 请求参数 |**参数** |**类型** |**参数类型** |**是否必填** |**描述** | |---|---|---|---|---| |Action |String |Query |是 |**SubmitAiTemplateTaskAsync** | |Version |String |Query |是 |2025\-11\-25 | |ServerId |Int |Body |是 |**服务ID , 固定值，可以在模板的详情弹窗中查看** | |PayloadJson |String |Body |是 |模板填充详情，根据不同模板入参要求构建的JSON字符串|\ | | | | |【详情需请参照具体[模板填充信息](../6664/1984743?lang=zh#.XzIt5qih5p2_5aGr5YWF5L-h5oGv)要求】 | * 响应参数 |**参数** |**类型** |**描述** | |---|---|---| |ResponseMetadata |[ResponseMetadata](../6664/1984743?lang=zh#_1-responsemetadata) |公共响应体 | |Result |[AsyncTaskResult](../6664/1984743?lang=zh#_2-asynctaskresult) |任务结果 | * 请求示例 \- ResourceList是URL 数组 ```json { "ServerId": 2540571789443387, "PayloadJson": "{\"ResourceList\":[\"https://lfxx1.jpg\"],\"TemplateId\":\"冷冬叙事拼图\"}" } ``` * 请求示例 \- ResourceList是DataUri 数组 > 应对海外CDN提供的URL服务访问不稳定, 可以自行转换成Base64编码, 每张图编码后的字符串大小不要超过8M ```json { "ServerId": 2540571789443387, "PayloadJson": "{\"ResourceList\":[\"data:image/jpeg;base64,/9j/4QKGRXhpZgAATU0AKgAAAAgACAEOAAIAAAGZAAAAbgESAAMAAAABAAEAAAEaAAUAAAABAAACCAEbAAUAAAABAAACEAEoAAMAAAABAAIAAAE7AAIAAAAKAAACGAITAAMAAAABAAEAAIdpAAQAAAABAAACIgAAAABBIHZlcnkgYmVhdXRpZnVsIHNtaWxpbmcgd29tYW4gY2FsbGVkIEVsbGUgd2VhcmluZyBhIGxvbmcgd2hpdGUgc2F0aW4gZHJlc3Mgc2l0dGluZyBvbiBhIGJyZWF0aHRha2luZyBuaWNlIGJlYWNoIHNvbWV3aGVyZSBpbiBHcmVlY2UgYXQgc3Vuc2V0LCBibHVycnkgYmFja2dyb3VuZCB3aXRoIG1vdW50YWlucywgd2hpdGUgaG91c2VzIGFuZCBibHVlIHJvb2ZzLCBzaWRlIHZpZXcsIGZhbnRhc3ksIGRyZWFtaW5nLCBjaW5lbWF0aWMsIHRyZW5kaW5nIG9uIEFydFN0YXRpb24sIGF3YXJk...\"],\"TemplateId\":\"冷冬叙事拼图\"}" } ``` * 响应示例 ```json { "ResponseMetadata": { "RequestId": "2025111816192007E6ED6D440FE65D0A1F", "Action": "SubmitAiTemplateTaskAsync", "Version": "2025-11-25", "Service": "iccloud_muse", "Region": "cn-north-1", "Code": 0 }, "Result": { "TaskId": "7573967600885514303" } } ``` ### **QueryAiTemplateTaskResult** * 描述：查询AI模板消费异步任务结果 * Method：**POST** * 请求参数 |**参数** |**类型** |**参数类型** |**是否必填** |**描述** | |---|---|---|---|---| |Action |String |Query |是 |**QueryAiTemplateTaskResult** | |Version |String |Query |是 |2025\-11\-25 | |TaskId |String |Body |是 |任务提交的ID|\ | | | | |来源于[异步任务结果](../6664/1984743?lang=zh#_2-asynctaskresult) | * 响应参数 |**参数** |**类型** |**描述** | |---|---|---| |ResponseMetadata |[ResponseMetadata](../6664/1984743?lang=zh#_1-responsemetadata) |公共响应体 | |Result |[AsyncTaskResult](../6664/1984743?lang=zh#_2-asynctaskresult) |任务结果 | * 请求示例 ```json { "TaskId": "7574258855660486699" } ``` * 响应示例 ```json { "ResponseMetadata": { "RequestId": "20251119123339DA1F93013A210DCD16FE", "Action": "QueryAiTemplateTaskResult", "Version": "2025-11-25", "Service": "iccloud_muse", "Region": "cn-north-1", "Code": 0 }, "Result": { "TaskId": "7574258855660486699", "Code": 0, "Progress": 100, "ResultUrl": "https://ark-content-generation-v2-cn-beijing.xxxx", "StartTime": "2025-11-19 12:32:51", "UpdateTime": "2025-11-19 12:33:21" } } ``` ## 2. 模板填充信息 * **说明** * 构建发起任务时的填充信息 * 参数用于任务发起时入参，参考「[模板消费请求参数](../6664/1984743?lang=zh#submitaitemplatetaskasync)」 * 该参数用于模板消费任务发起时的入参「[PayloadJson](../6664/1984743?lang=zh#submitaitemplatetaskasync)」 |**参数** |**类型** |**是否必填** |**描述** | |---|---|---|---| |TemplateId |String |是 |**模板ID**|\ | | | |来源于创作云AI模板广场的模板详情|\ | | | |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9e99557a98f4c23ceb4e6f3b206a2c41.png) |\ | | | |例："3D卡通绘" | |ResourceList |[ ]String |是 |待传入单张或多张图片对应的媒资 URL，具体数量由所选用模板指定|\ | | | ||\ | | | |* 图片格式要求|\ | | | |1. 支持格式：JPG/JPEG、PNG|\ | | | ||\ | | | |其他格式说明：图生图支持WebP格式，而图生视频和首尾帧不支持WebP格式。|\ | | | ||\ | | | |2. 图片比例说明：生成结果所支持的比例详见「模板详情」中的支持比例。|\ | | | ||\ | | | |服务端不进行图片比例校验，将依据用户输入图片的尺寸，自动适配最接近当前模板所支持比例的结果。|\ | | | |例：若当前模板支持比例为9:16、1:1、16:9、3:4、4:3，用户输入图片的比例为9:15，则输出结果比例为9:16。|\ | | | ||\ | | | |* 图片规格要求|\ | | | |1. 宽高尺寸范围：300px ~ 6000px（像素）|\ | | | |2. 文件大小限制：≤ 8MB|\ | | | |* 媒资URL要求|\ | | | |1. 需为公网可直接访问的有效地址（无访问权限限制、链路稳定）|\ | | | ||\ | | | |例：[ "https://lf\-/obj/1xxx.jpg", "https://lf\-/obj/2xxx.jpg" ] | |Resolution |String |否 |作品分辨率，模板具体支持的分辨率请参考模板详情分辨率字段|\ | | | |不同分辨率所消耗的创点不同，具体创点消耗明细可查看 SaaS 页面|\ | | | |取值范围：480p、720p、1080p、2k等「**p、k小写**」|\ | | | |默认值：|\ | | | ||\ | | | |* 图生视频、首尾帧：720p|\ | | | |* 图生图：2k | |Watermark |bool |否 |右下角是否添加“AI生成”水印，若需添加则传入true | * 构造示例【需要将对象序列化为JSON字符串】 ```json "{\"ResourceList\":[\"https://lf-xxx.jpg\"],\"TemplateId\":\"3D卡通绘\"}" ``` * [模板消费任务发起入口](../6664/1984743?lang=zh#submitaitemplatetaskasync) ## 3.模板列表 **ListAiTemplates** * 描述：获取AI特效模板列表 * Method：**POST** * 请求参数 |**参数** |**类型** |**参数类型** |**是否必填** |**描述** | |---|---|---|---|---| |Action |String |Query |是 |**ListAiTemplates** | |Version |String |Query |是 |2025\-11\-25 | |PageNumber|Int|Body |是 |列表分页参数，从1开始|\ | | | | | | |PageSize|Int|Body|是|每页大小，取值范围[10,50]|\ | | | | | | |CategoryCode |String |Body |否 |模板分类，见CategoryCode可选值。不传则默认拉取【全部】分类 | |Keyword |String |Body |否 |名称搜索 | CategoryCode可选值 |全部 |最新上线 |热门 |节日 |可爱萌宠 |华丽变身 |风格重塑 |超能力创意 |趣味搞怪 |TOP10调用榜 | |---|---|---|---|---|---|---|---|---|---| |2114584576 |2114781184 |2113994752 |2114060288 |2114256896 |2114322432 |2114387968 |2114453504 |2114519040 |2114846720 | * 响应参数 |**参数** |**类型** |**描述** | |---|---|---| |ResponseMetadata |[ResponseMetadata](https://www.volcengine.com/docs/6664/1984743?lang=zh#_1-responsemetadata) |公共响应体 | |Result |[ListAiTemplateResult](https://www.volcengine.com/docs/6664/1984743?lang=zh#.6ZSZ6K-v56CB) |模板列表数据 | * 请求示例 ```JSON { "page_number": 1, "page_size": 10, "category_code": "2114060288" } ``` * 响应示例 ```JSON { "ResponseMetadata": { "RequestId": "202603121936368A2CAEEE387525FC9C3B", "Action": "ListAiTemplates", "Version": "2025-11-25", "Service": "iccloud_muse", "Region": "cn-north-1", "Code": 0 }, "Result": { "Medias": [ { "MediaId": "7600358281369911336", "Title": "Valentine's Day building blocks", "Cover": "https://muse.console.volcengine.com/api/storage/objects/media/7600369931573739555_transcode_image_png_480p/ec7d697a-3cf0-4591-8ca9-2fcf4353b46d_png_480p.png?infer_mime=ext&x-muse-token=ChYIARABGMDKys0GIMDtz80GKgQ3Mzk4EmgKBgjpBxDpBxIAGgIYAiIICgJobBICY24qBgjaNBCGAzIAQhQKEmljYXJjaC5pYW0uYXV0aHJwY0ouL2FwaS9zdG9yYWdlL29iamVjdHMvbWVkaWEvNzYwMDM2OTkzMTU3MzczOTU1NRrYAk85V1BqOFBJbGF4OW5pcHorY2wzYjlnVW1lVXpiLzlqSnZwdE4veTFKQVhuNXhYUUVvbGlDMEdNY2pmcS9XT2h3S1g3cjA3UTlTcmJWWFBBQkdaTWdQZG1HbmZLRGFMTkZMVGhuTE16Y3U1bjFUUGJhV0srTHFDYUduSFRxdHc3R2VNQ2w5NlpHdndyZE1HZitnT1ZaeHVmQVlYVm9lN2NaKzVtRTZQUWxDeXg5N1o0UkFQRE1YdWgzNHBla0ZjMkR6cjRiZmRGSlZzU1dUd3l0WFN6dUtmZithTTRaaktEejV6SnppdmN4d2VDOS83UDRTZzBBYU1sUytsY2JlUVhhT3NYbDVta0puNUZuVUdoUVBycG51UXBUL1VYOEh3MTBEeFVxRzVnM25Pd0ZmVGJPY0RGeTJlUnE2STdaUCswZ0xKTXZnaXhmZFZKTlhNSmxab21Idz09", "Duration": 5062, "PreviewVideo": "https://muse.console.volcengine.com/api/storage/objects/media/7600358281369911336_transcode_video_mp4_480p_h264.mp4?infer_mime=ext&x-muse-token=ChYIARABGMDKys0GIMDtz80GKgQ3Mzk4EmgKBgjpBxDpBxIAGgIYAiIICgJobBICY24qBgjaNBCGAzIAQhQKEmljYXJjaC5pYW0uYXV0aHJwY0ouL2FwaS9zdG9yYWdlL29iamVjdHMvbWVkaWEvNzYwMDM1ODI4MTM2OTkxMTMzNhrYAklRZlhxTjhqNEdhdTlHL2RQeFBxSmdKWFpVRkdPSTEyWmxxcU5ZNzdtVnROUExCWHcwdWx1RUlrckNqckM5MDh0aTVzV1FPNkVseHlUOURYUjBlQnVzdGR6UDRkSCtQOFZFMEcrSlI3T1NTRzZhbjdBTWhRLytENmwxemlSNVFZVC8veUIvNDcxanJQQlVPZjZYc0VsR2hjTmVGT0wrOWlTYWVpcDY3OVRIWXdkNHJnMzlhSFpBazJ3bXVZcVNZMkFqMTBPUU9ONlFOQWhPZkxxWDlaUEJsSFp2YVZMK04vZzd2ODhnbFpaNmxCYyt3L2h0ZG83UnBFY25CeWpoN2JYMjkzQURreGE5OWlaaVJDVjNyVmlwTHdKMUZpU095cG8vRVkxd3FzaWZsd3ZXbWNyeXZPd1FYYlA4dGZkMzZBQU9XWDVFVlBJYWhLQVIxWVVQbDllUT09", "Tags": [], "ServiceId": "7809632936052886", "TemplateId": "2000615170", "ConsumeItems": [ { "Resolution": "480p", "Usage": 0.06 }, { "Resolution": "720p", "Usage": 0.11 }, { "Resolution": "1080p", "Usage": 0.24 } ] } ], "TotalCount": 19 } } ``` # 结果回调 * **当前AI特效模板消费结果支持HTTP回调，具体回调接入方式请参考：** [智能创作云-回调服务接入指引](https://www.volcengine.com/docs/6664/2193111?lang=zh) # 数据结构 ## 1. ResponseMetadata |参数 |类型 |描述 | |---|---|---| |RequestId |String |HTTP请求日志ID | |Action |String |请求接口标识 | |Version |String |请求接口版本 | |Service |String |请求接口服务 | |Region |String |请求接口服务地域 | |Code |Int |任务状态码详细见：[错误码](../6664/1984743?lang=zh#.6ZSZ6K-v56CB) | ## 2. AsyncTaskResult |参数 |类型 |描述 | |---|---|---| |TaskId |String |AI模板异步消费任务ID，用于结果查询 | ## 3. QueryTaskResult |**参数** |**类型** |**描述** | |---|---|---| |TaskId |String |任务ID | |Code |Int |任务状态码详细见：[错误码](https://www.volcengine.com/docs/6664/1984743?lang=zh#.6ZSZ6K-v56CB) | |Progress |Int |任务进度取值范围：0 \- 100 | |ResultUrl |String |模板结果媒资URL|\ | | |**ResultUrl链接的使用有效期仅为24小时，过期后ResultUrl将无法正常访问** | |Usage |Float |任务创点消耗量，**仅任务成功时返回实际消耗值，任务失败时为0** | |StartTime |String |任务开始时间 | |UpdateTime |String |任务结束时间 | ## 4.ListAiTemplateResult **Result** |**参数** |**类型** |**描述** | |---|---|---| |Medias |Array |模板数据数组，模板具体字段见Media | |TotalCount |Int |列表总数 | **Meida** |**参数** |**类型** |**描述** | |---|---|---| |MediaId |String |资源id | |Title |String |模板名称 | |Cover |String |模板封面 | |PreviewVideo |String |预览视频 | |Duration |Int |时长，单位ms | |Tags |Array |标签 | |ServiceId |String |服务id | |TemplateId |String |模板id | |ConsumeItems |Array |模板支持的分辨率及对应的创点消耗|\ | | |```Plain Text|\ | | |[|\ | | | {|\ | | | "Resolution": "480p",|\ | | | "Usage": 0.06|\ | | | },|\ | | | {|\ | | | "Resolution": "720p",|\ | | | "Usage": 0.11|\ | | | }|\ | | |]|\ | | |```|\ | | | | # 错误码 ```JSON { "ResponseMetadata": { "RequestId"："202511221602162C79BEBEFE54155839AF" "Action"："SubmitAiTemplateTaskAsync"， "Version"： "2025-11-25"， "Service"： "iccloud_muse"， "Region"： "cn-north-1"， "Code"：1402， // 错误码见下表 "Domain"："aigc_openapi"， "Message"： "domain:aigc_openapi code:1402" } } ``` |**Code** |**Name** |**Message** | |---|---|---| |0 |Success |任务执行成功 | |1000 |AsyncTaskRunning |异步任务已在运行中 | |1400 |ParamErr |参数错误 | |1401 |ConcurrentErr |并发数超过限额 | |1402 |InsufficientPoints |创点不足 | |1403 |QuotaErr |无OpenAPI权限 | |1410 |ServerIdNotExist |服务ID不存在 | |1411 |InputResolutionErr |输入分辨率错误 | |1412 |ImageFormatErr |图片格式错误 | |1413 |InvalidMediaUrlErr |无效的媒体URL错误 | |1414 |MediaSensitiveErr |输入或输出内容包含敏感信息错误 | |1500 |InternalErr |服务端内部错误 | |1600 |AsyncTaskNotExist |任务不存在 | |2000 |AsyncTaskFailed |任务执行失败 | # 其他报错说明 ## 使用子账号的AK/SK在调用AI特效模板接口时报错"Message": "User is not authorized to perform: 报错表现 ```json ｛ 'CodeN'：100013， "Code"："AccessDenied"， "Message"："User is not authorized to perform：iccloud_muse:SubmitAilemplateTaskAsync on resource： " } } ``` 解决办法 **需要主账户在https://console.volcengine.com/iam/policymanage里新建自定义参数配置。** **iam** **给子账号添加鉴权。** |步骤 |操作 |截图 | |---|---|---| |step1 |点击「新建自定义策略」 |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_344dcc0e23de85d9bd26d0ab2eb408b9.png) | |step2 |输入策略名，点击JSON编辑器填写Action，然后点击提交 |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6936746b0aa9216bdcb294e5f65e6be1.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9c34e6b765e1ee7167c2cf3a55cb9b28.png) |\ | | |```json|\ | | |{|\ | | | "Statement": [|\ | | | {|\ | | | "Effect": "Allow",|\ | | | "Action": [|\ | | | "iccloud_muse:SubmitAiTemplateTaskAsync",|\ | | | "iccloud_muse:QueryAiTemplateTaskResult"|\ | | | ],|\ | | | "Resource": [|\ | | | "*"|\ | | | ]|\ | | | }|\ | | | ]|\ | | |}|\ | | |```|\ | | | | |step3 |点击「添加权限」，用户找到对应的子账号勾选上，然后点击提交 |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_328b4c633c0b19efec85b3bf1c35a5f4.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9e9452c2ff10f47990dec09046cc785f.png) | **注意：自定义策略时，Action 可以直接填\*，不列明具体接口，这样可以兼容其他接口。** ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_7e615c82840727562adf5cfa7f10cd9b.png) ```json { "Statement": [ { "Effect": "Allow", "Action": [ "*" ], "Resource": [ "*" ] } ] } ```

创作Agent