# 1.概述本文档为AI美颜Pro OpenAPI 的官方接入指引。旨在帮助开发者通过 API 接口，快速、高效地集成和使用平台提供的 AI美颜Pro 能力 # 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_074ea752ec5b57c229789c13e4fb4562.png =520x) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6667c12d619e7e3f14ae20dea602ff9a.png =732x) 1. 在左侧菜单中选择 **「API Key」** 模块，然后点击 **「+New」** 按钮。 2. 输入 API Key 名称后，点击 **「Create」** 按钮完成创建。 3. 创建成功后，您将获得一个 API Key。请妥善保管此密钥，它将作为您调用所有接口的唯一凭证。 :::tip **权限说明**：在调用接口前，请确保您的账户已开通相关服务的访问权限。若在调用过程中遇到权限问题，请联系您的企业管理员或火山引擎商务代表。 ::: ## 4.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.接口说明 ## 5.1 提交异步任务该接口用于提交一个 AI美颜Pro的异步处理任务。调用成功后，会立即返回一个任务 ID (`task_id`)，您可以使用此 ID 来查询任务的执行状态和最终结果。 * **请求方法**：POST * **请求路径**：`/openapi/ai_effect/submit` ### 请求参数 |**字段名** |**类型** |**必填** |**示例** |**描述** | |---|---|---|---|---| |template_id |string |是 |"245621001"|AI 美颜Pro 固定的模板 ID 为`“245621001”` |\ | | | | | | |payload |json|是 |参考下方示例| JSON Object，用于传递模板渲染所需的具体参数。其内部结构见下文。 |\ | | | | | | |callback_url|string|否 |任务结果公网回调地址。|当任务完成（无论成功或失败）时，系统会向此 URL 发送一个 `POST` 请求，通知您结果。|\ | | | | |回调结果就是查询的响应参数 | #### payload 结构 |**字段名** |**类型** |**必填** |**描述** | |---|---|---|---| |resource_list |array|是 |需要处理的原始媒资 URL 列表。支持公网可访问的图片 URL 或图片的 Base64 Data URI。为保证请求的稳定性和速度，强烈建议使用 **Data URI** 格式。 |\ | | | | | |extra|json|是 |美颜配置参数，目前固定值如下：|\ | | | |```Plain Text|\ | | | |{|\ | | | | "beautyToolConfigKey": "beautyPro_481"|\ | | | |}|\ | | | |```|\ | | | | | ### 响应参数 |**字段名** |**类型** |**描述** | |---|---|---| |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": "245621001", "callback_url": "https://muse.console.volcengine.com/api/muse/product/13477/callback", "payload": { "resource_list": [ "https://lf-iccloud-muse.volcmusecdn.com/obj/labcv-tob/gmy_test/AI.jpg" ] "extra": { "beautyToolConfigKey": "beautyPro_481" } } }' ``` ### 响应示例（成功） ```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" } ``` --- ## 5.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/wiki/ZwwawNbAkiqfdPkGaSbcAD5yn5d#share-MGlwdSSDjoAjYqx6rsIcOgZynEe) |包含任务详细信息的对象，见下文 QueryData 结构。 | #### queryData |**字段名** |**类型** |**描述** | |---|---|---| |task_id |string |任务的唯一 ID | |usage |double |本次任务消耗的创点数量，仅在任务成功时有效 | |payload |[payload](https://bytedance.larkoffice.com/wiki/ZwwawNbAkiqfdPkGaSbcAD5yn5d#share-HRP0dUptGoQyDXx7FgxcmKXunIc) |任务详情 | #### payload 任务结果详情，不同类型任务的结果字段可能存在差异，以下字段为结果公共字段。 |**字段名** |**类型** |**描述** | |---|---|---| |result_url |string |任务结果地址 | |result_extra |json |美颜小项的参数 | :::tip **关于 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", "result_extra": { "beauty": { "smooth": 80, "whiten_ziran": 30, "unify_skin_color": 80, "neck_wrinkles": 80, "face_plump": 60 }, "reshape": { "slimface_nature": 40, "face_jawbone": 15, "face_forehead": -30, "eye": 15, "nose": 15, "face_smilesfolds": 40, "eye_pouch": 70 }, "makeup": { "lipstick_liangze": 30, "blusher_mitao": 20, "contour_ziran": 30 }, "extra": { "multi_people": false } "produce_id": "06fc1bda-e077-4ed9-9fbc-8ff137e5d03e", "any_key": "value1" }, "task_id": "7617833350455099399", "usage": 0.01 }, "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" } ``` --- ## 5.3 代码示例 |python |Java |golang | |---|---|---| | | | |\ |api_sample_beauty_pro.py|ApiSampleBeautyPro.java|api_sample_beauty_pro.go|\ ||||\ | | | | ## 5.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 无效或对应的模板未上线。请检查模板 ID 是否正确 |\ | | | | |1412|ImageFormatErr|**图片格式错误**：输入的图片格式不受支持或文件已损坏。建议使用常见的 JPEG 或 PNG 格式。 |\ | | | | |1413 |InvalidMediaUrlErr|**媒体 URL 无效**：ResourceList 中的 URL 无法访问。请确保 URL 是公网可达的，且未过期。 |\ | | | | |1414 |MediaSensitiveErr|**内容安全问题**：输入内容触发了平台的安全审核策略。请更换内容后重试。 |\ | | | | |1600 |AsyncTaskNotExist |**任务不存在**：查询的 task_id 无效。请检查 task_id 是否为 AITemplateAsyncTaskSubmit 接口成功返回的值。 | |1601 |AsyncTaskTimeoutErr |**任务超时**：任务执行超过了系统设定的最长处理时间（当前为 1 小时）。 | |2000 |AsyncTaskFailed |**任务失败**：任务在执行过程中发生未能归类的失败。 | |3000 |TaskCallbackFailed |**回调失败**：向您配置的回调地址发送结果时失败。 | |5000 |RiverWorkflowFailed |**工作流失败**：底层 AI 工作流执行失败，通常为更具体的错误（如 1412\-1414）的兜底。 | ---

智能美化特效