文档中心

智能美化特效

AI 美颜 API 接入指南

AI美颜-Pro OpenAPI接口说明（APIKey 版）

1.概述

本文档为AI美颜Pro OpenAPI 的官方接入指引。旨在帮助开发者通过 API 接口，快速、高效地集成和使用平台提供的 AI美颜Pro 能力

2.快速开始

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

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

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

3.对外域名

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

4.APIKey 申请

请通过主账号登录创作Agent首页。

导航至 kickart-apikey申请页面。

在左侧菜单中选择「API Key」模块，然后点击「+New」按钮。

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

创建成功后，您将获得一个 API Key。请妥善保管此密钥，它将作为您调用所有接口的唯一凭证。

权限说明：在调用接口前，请确保您的账户已开通相关服务的访问权限。若在调用过程中遇到权限问题，请联系您的企业管理员或火山引擎商务代表。

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<string>	是	需要处理的原始媒资 URL 列表。支持公网可访问的图片 URL 或图片的 Base64 Data URI。为保证请求的稳定性和速度，强烈建议使用 Data URI 格式。
extra	json	是	美颜配置参数，目前固定值如下： { "beautyToolConfigKey": "beautyPro_481" }

响应参数

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

cURL 请求示例

响应示例（成功）

响应示例（失败）

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	包含任务详细信息的对象，见下文 QueryData 结构。

queryData

字段名	类型	描述
task_id	string	任务的唯一 ID
usage	double	本次任务消耗的创点数量，仅在任务成功时有效
payload	payload	任务详情

payload

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

字段名	类型	描述
result_url	string	任务结果地址
result_extra	json	美颜小项的参数

关于 result_url 的有效期

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

cURL 请求示例

响应示例（任务成功）

响应示例（任务进行中）

响应示例（任务失败）

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）的兜底。

最近更新时间：2026.05.15 17:27:26

这个页面对您有帮助吗？

有用

无用