智能美化特效
智能美化特效
智能美化特效
文档指南
请输入
购买指南
Sample文件结构
接口说明-算法
接口说明-算法-Linux
相关示例参考
素材包和key说明
- 文档首页
智能美化特效AI 美颜 API 接入指南AI美颜-Live OpenAPI接口说明
复制全文
下载 pdfAI美颜-Live OpenAPI接口说明
文档反馈
问问助手创建任务
接口说明
请求
URL | | | | |
Method | POST | | | |
Body | 参数名 | 含义 | 格式 | 生成规则 |
| key | 客户的AccessKey | String | 联系售前申请 |
| nonce | 随机数字串 | Int | rand() |
| timestamp | 时间戳，单位秒 | Int | 当前秒级时间戳 |
| payload | 有效请求信息 | String | 见参数详细生成规则 |
| digest | 签名 | String | 见参数详细生成规则 |
举例
{
"key": "biz_license_tool_test_key3c878d7f63664669936515200ec14d2e",
"nonce": 309089552,
"timestamp": 1776065436,
"payload": "{\"serverId\":2456212295650178,\"payloadJson\":\"{\\\"extra\\\":{\\\"beautyToolConfigKey\\\": \\\"beautyLive_481\\\"},\\\"resource_list\\\":[\\\"https://cvsdk.tos-cn-beijing.volces.com/resource/drill/pics/20260318-141133.jpeg\\\"],\\\"template_id\\\":\\\"beautyLive\\\"}\"}",
"digest": "92E044B3977060BB8463B9B69B077DFD9A4139493466545614FA6C05D42A3A83"
}
返回值
字段名 | 含义 | 补充 |
code | 状态码 |
|
data | 返回的数据内容 | 包含创建的任务ID |
message | 状态信息 | 见下方示例 |
举例
{
"code": 0,
"data": {
"taskId": "202604131839033A5ED192A9B250B4A68D&qA2iUvREAJOqtGjvqGISZ"
},
"message": "success"
}
参数详细生成规则
payload
描述
如下 json 的序列化字符串。resource_list中包含需要处理的图片uri，其余均为固定值
图片的 uri 支持远端 url 和图片的 datauri 两种格式。url 对应的图片大小要求 < 8M，datauri 对应的图片大小要求 < 4M
{
"serverId": 190300418,
"payloadJson": "{\"extra\":{\"beautyToolConfigKey\": \"beautyLive_481\"},\"resource_list\":[\"https://cvsdk.tos-cn-beijing.volces.com/resource/drill/pics/20260318-141133.jpeg\"],\"template_id\":\"beautyLive\"}"
}
示例代码
# 示例代码
import json
def build_payload(uri: str) -> str:
payload = {
"serverId": 190300418,
"payloadJson": json.dumps({
"extra": {
"beautyToolConfigKey": "beautyLive_481",
},
"resource_list": [uri],
"template_id": "beautyLive"
}, ensure_ascii=False)
}
return json.dumps(payload, ensure_ascii=False)
digest
描述
通过 hmac_sha256 算法，以 secret 为 key 对 sha256({key}-{nonce}-{timestamp}-{playload}) 进行摘要，最后转大写
示例代码
# 示例代码
import hmac
import hashlib
def HMAC_SHA256(key, msg):
return hmac.new(bytes(key,'utf-8'), msg=msg, digestmod=hashlib.sha256).hexdigest().upper()
def sha256_encrypt(text: str) -> str:
hash_obj = hashlib.sha256(text.encode('utf-8'))
return hash_obj.hexdigest()
secret_key = 'your_secret'
key = 'your_key'
nonce = 309089552
timestamp = 1776065436
payload = "{\"serverId\":190300418,\"payloadJson\":\"{\\\"extra\\\":{\\\"beautyToolConfigKey\\\": \\\"beautyLive_481\\\"},\\\"resource_list\\\":[\\\"https://cvsdk.tos-cn-beijing.volces.com/resource/drill/pics/20260318-141133.jpeg\\\"],\\\"template_id\\\":\\\"beautyLive\\\"}\"}"
digest = HMAC_SHA256(secret_key, sha256_encrypt(key + '-' + str(nonce) + '-' + str(timestamp) + '-' + payload).encode('utf8'))
完整示例代码
import requests
import json
import time
import random
import hmac
import hashlib
def HMAC_SHA256(key, msg):
return hmac.new(bytes(key,'utf-8'), msg=msg, digestmod=hashlib.sha256).hexdigest().upper()
def sha256_encrypt(text: str) -> str:
hash_obj = hashlib.sha256(text.encode('utf-8'))
return hash_obj.hexdigest()
def build_payload(uri: str, server_id: int) -> str:
payload = {
"serverId": server_id,
"payloadJson": json.dumps({
"extra": {
"beautyToolConfigKey": "beautyLive_481"
},
"resource_list": [uri],
"template_id": "beautyLive"
}, ensure_ascii=False)
}
return json.dumps(payload, ensure_ascii=False)
def send_beauty_analysis(
secret_key: str,
key: str,
nonce: int,
timestamp: int,
server_id: int,
resource_url: str
):
"""
发送 beautyAgentLiveAnalysis POST 请求
:param key: 密钥
:param nonce: 随机数
:param timestamp: 时间戳
:param server_id: 服务器ID
:param resource_url: resource_list 里的图片URL
:return: requests 响应对象
"""
payload = build_payload(resource_url, server_id)
digest = HMAC_SHA256(secret_key, sha256_encrypt(key + '-' + str(nonce) + '-' + str(timestamp) + '-' + payload).encode('utf8'))
request_body = {
"key": key,
"nonce": nonce,
"timestamp": timestamp,
"payload": payload,
"digest": digest
}
print(f'request body: {request_body}')
url = "https://cv.iccvlog.com/api/v1/license/beautyAgentLiveAnalysis"
headers = {
"Content-Type": "application/json",
"X-Tt-Env": "ppe_new_river",
"X-Use-Ppe": "1"
}
response = requests.post(url, json=request_body, headers=headers)
return response
key = "your_access_key"
secret = "your_secret_key"
nonce = random.randint(0, 999999999)
timestamp = timestamp = int(time.time())
server_id = 190300418
resource_url = "https://cvsdk.tos-cn-beijing.volces.com/resource/drill/pics/20260318-141133.jpeg"
# 发送请求
resp = send_beauty_analysis(
secret_key=secret,
key=key,
nonce=nonce,
timestamp=timestamp,
server_id=server_id,
resource_url=resource_url
)
print(resp.json())
task_id = resp.json()["data"]["taskId"]
查询任务状态
接口说明
请求
URL | | | | |
Method | POST | | | |
Body | 参数名 | 含义 | 格式 | 生成规则 |
| key | 客户的AccessKey | String | 联系售前申请 |
| nonce | 随机数字串 | Int | rand() |
| timestamp | 时间戳，单位秒 | Int | 当前秒级时间戳 |
| payload | 有效请求信息 | String | 见参数详细生成规则 |
| digest | 签名 | String | 见参数详细生成规则 |
返回值
字段名 | | 含义 | 补充 |
code | | 状态码 |
|
message | | 状态详细描述 | 见下方示例 |
result | data | 执行结果数据 | 未执行完成时，无该字段 |
| progressValue | 执行进度 | Float 类型，0~1 |
| status | 状态信息 | 其中之一：pending, executing, succeeded, failed |
| queueInfo | 队列信息 | { "queuePosition": 0, "executionStartTime": 1776076743971 // 开始执行时间戳 } |
举例（正在执行）
{
"code": 0,
"message": "success",
"result": {
"progress": {
"finishedNodes": {},
"executingNodes": {}
},
"status": "executing",
"progressValue": 0.8819444444444444,
"queueInfo": {
"queuePosition": 0,
"executionStartTime": 1776078558721
}
}
}
举例（执行成功）
{
"code": 0,
"message": "success",
"result": {
"data": {
"payloadJSON": "{\"result_url\":\"https://cvsdk.tos-cn-beijing.volces.com/resource/drill/pics/20260318-141133.jpeg\",\"result_extra\":\"{\\\"beauty\\\":{\\\"smooth\\\":50,\\\"whiten_ziran\\\":30},\\\"reshape\\\":{\\\"face_shrinkhead\\\":40,\\\"slimface_boy\\\":30,\\\"eye\\\":5,\\\"nose\\\":15},\\\"extra\\\":{\\\"multi_people\\\":false}}\"}",
"metrics": {
"nodesExecutionTime": {
"13": 0.7116759419441223,
"18": 0.37724995613098145
}
}
},
"status": "succeeded",
"queueInfo": {
"queuePosition": 0,
"executionStartTime": 1776076743971
}
}
}
参数详细生成规则
payload
描述
如下 json 的序列化字符串。其中，taskId为创建任务接口返回的taskId
{
"serverId": 190300418,
"taskId": "taskId"
}
示例代码
# 示例代码
import json
def build_query_payload(taskId: str) -> str:
payload = {
"serverId": 190300418,
"taskId": taskId
}
return json.dumps(payload, ensure_ascii=False)
digest
- 同「创建任务」接口
返回数据详细说明
result
- 关注 result["data"]["payloadJSON"]，序列化成字典后，包含需要施加的功能小项
完整示例代码
import requests
import json
import time
import random
import hmac
import hashlib
def HMAC_SHA256(key, msg):
return hmac.new(bytes(key,'utf-8'), msg=msg, digestmod=hashlib.sha256).hexdigest().upper()
def sha256_encrypt(text: str) -> str:
hash_obj = hashlib.sha256(text.encode('utf-8'))
return hash_obj.hexdigest()
def sha256(text: str) -> str:
hash_obj = hashlib.sha256(text.encode('utf-8'))
return hash_obj.hexdigest()
def build_query_payload(taskId: str, server_id: int) -> str:
payload = {
"serverId": server_id,
"taskId": taskId
}
return json.dumps(payload, ensure_ascii=False)
def send_beauty_query(
secret_key: str,
key: str,
nonce: int,
timestamp: int,
server_id: int,
task_id: str
):
"""
发送 beautyAgentLiveAnalysis POST 请求
:param key: 密钥
:param nonce: 随机数
:param timestamp: 时间戳
:param server_id: 服务器ID
:param resource_url: resource_list 里的图片URL
:return: requests 响应对象
"""
payload = build_query_payload(task_id, server_id)
digest = HMAC_SHA256(secret_key, sha256_encrypt(key + '-' + str(nonce) + '-' + str(timestamp) + '-' + payload).encode('utf8'))
request_body = {
"key": key,
"nonce": nonce,
"timestamp": timestamp,
"payload": payload,
"digest": digest
}
url = "https://cv.iccvlog.com/api/v1/license/beautyAgentLiveResult"
headers = {
"Content-Type": "application/json",
"X-Tt-Env": "ppe_new_river",
"X-Use-Ppe": "1"
}
response = requests.post(url, json=request_body, headers=headers)
return response
key = "your_access_key"
secret = "your_secret_key"
nonce = random.randint(0, 999999999)
timestamp = timestamp = int(time.time())
server_id = 190300418
task_id = '202604131839033A5ED192A9B250B4A68D&qA2iUvREAJOqtGjvqGISZ'
# 发送请求
resp = send_beauty_query(
secret_key=secret,
key=key,
nonce=nonce,
timestamp=timestamp,
server_id=server_id,
task_id=task_id
)
print(json.dumps(resp.json(), indent=4, ensure_ascii=False))
最近更新时间：2026.05.15 17:27:19
这个页面对您有帮助吗？
有用
有用
无用
无用