该文档指引接入美图云修智能 API中的牙齿美化服务，需先申请接口权限后方可接入使用，接口的接入通过 HTTP 异步调用的形式接入。美图云修 API 提供的服务均为异步接口，目前提供了 2 种形式来获取结果：消息通知回调、结果查询

1. 公共参数

请求头

名称	类型	必填	f描述
Content-Type	string	是	固定值："application/json"

请求方法

POST

2. 接口列表

1. 预设 ID 接入

请求地址：https://api.yunxiu.meitu.com/openapi/aiteeth_async

请求方法：POST

请求头:

名称	类型	必填	f描述
Content-Type	string	是	固定值："application/json"

请求参数（Query参数）:

名称	类型	是否必填	描述	示例值
api_key	string	是	应用Key	EtRGxLI8*******************aYUD2PUbMP
api_secret	string	是	应用Secret	wkTD89j******************************WUo

请求参数（Body参数）：

名称	类型	是否必填	描述	示例值
media_code	string	是	预设 ID（什么是预设ID？）	MTyunxiu163aa58942
media_data	string	是	原图图片地址(不支持base64，只支持url)	https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg
repost_url	string	否	结果回调地址,接入侧提供	https://httpbin.org/

请求示例：

curl --location --request POST 'https://api.yunxiu.meitu.com/openapi/aiteeth_async?api_key=xxxx&api_secret=xxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "media_code": "MTyunxiu",
    "media_data": "https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg",
    "repost_url": "https://httpbin.org/",
}'

响应参数：

名称	类型	是否必填	描述	示例值
code	int	是	业务状态码	0
data	struct	是	结果数据	`{ "msg_id": "8547e55f-9492-40a9-ba0d-7041b717ee5a" }`
message	string	否	提示信息	success
request_id	string	是	请求ID	30c2194d-049b-4f69-95f8-0e9b440df2eb

响应示例：

{
    "code": 0,
    "data": {
        "msg_id": "8547e55f-9492-40a9-ba0d-7041b717ee5a"
    },
    "message": "",
    "request_id": "30c2194d-049b-4f69-95f8-0e9b440df2eb"
}

2.2 原始参数接入

请求地址：https://api.yunxiu.meitu.com/openapi/aiteeth_async

请求方法：POST

请求参数（Query参数）:

名称	类型	是否必填	描述	示例值
api_key	string	是	应用Key	EtRGxLI8*******************aYUD2PUbMP
api_secret	string	是	应用Secret	wkTD89j******************************WUo

请求参数（Body参数）:

名称	类型	是否必填	描述	示例值
parameter	struct	是	处理参数	查看
media_info_list	array	是	原图图片地址	查看
extra	struct	否	其他信息	`{}`

media_info_list 参数结构

名称	类型	是否必填	描述	示例值
media_data	string	是	原图图片地址(不支持base64，只支持url)	https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg
media_extra	struct	否	资源描述额外信息	`{}`
media_profiles	struct	是	图片地址的资源描述	固定值`{"media_data_type":"url","media_data_describe":"src"}`

[
    {
        "media_data": "https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg",
        "media_extra": {},
        "media_profiles": {
            "media_data_type": "url",
            "media_data_describe": "src"
        }
    }
]

parameter 参数结构：

名称	类型	是否必填	描述	示例值
all_params	struct	是	图片处理参数	查看下文
repost_url	string	否	结果回调地址,接入侧提供	https://httpbin.org/
rsp_mask_version	int	是	-	固定值500
preview_size	int	是	-	固定值3000
people_type	array	是	自定义年龄性别属性的数组顺序	查看下文
output	struct	是	输出结构	查看下文

filter 参数结构：

名称	类型	是否必填	描述	范围	示例值
filter_id	string	否	滤镜ID
filters_lut_alpha	int	否	程度值	0～100	默认值50
filter_is_black	int	否

blush、eyesocket等数组中对象结构：

名称	类型	是否必填	描述	示例值
id	string	是	效果名称，默认值空	"luozhuang"
color	string	是	颜色值，rgba格式，默认值 0;0;0;0	""
alpha	int	是	效果程度，默认值 0	50

people_type 参数结构：

该字段用来定义图片中人物性别和年龄的对应关系，目前支持设置 5 种类型的人物性别。

名称	类型	是否必填	描述	示例值
age	list	是	定义该属性的年龄范围	[50, 100]
gender	int	是	性别:1男 0女
key	string	是	性别属性	oldman
name	string	否	性别属性名称	老

对于参数支持性别和年龄属性的，那么他的数据结构是一个 array，这个 array 总共有 5 个元素，分别对应 people_type 中的 5 种性别/年龄的定义，比如参数值：

beauty_belly_alpha: [10, 20, 30, 40, 50]

然后 people_type 的定义顺序为(注：people_type数组每一个元素的结构是一个对象，这里用字符串是为了方便阅读，具体的数据结构参考推荐配置)：

["man", "woman", "child", "oldwoman", "oldman"]

那么表示 beauty_belly_alpha 对应会生效为：

{
    "man": 10,
    "woman": 20,
    "child": 30,
    "oldwoman": 40,
    "oldman": 50
}

推荐配置参数：

[
    {
        "age":[
            15,
            49
        ],
        "gender":1,
        "key":"man",
        "name":"男"
    },
    {
        "age":[
            15,
            49
        ],
        "gender":0,
        "key":"woman",
        "name":"女"
    },
    {
        "age":[
            0,
            14
        ],
        "gender":0,
        "key":"child",
        "name":"儿童"
    },
    {
        "age":[
            50,
            100
        ],
        "gender":0,
        "key":"oldwoman",
        "name":"老年女"
    },
    {
        "age":[
            50,
            100
        ],
        "gender":1,
        "key":"oldman",
        "name":"老年男"
    }
]

output 参数结构：

名称	类型	是否必填	描述	示例值
format	string	是	输出格式，支持jpg和png	jpg
preview_size	string	是	原图分割尺寸，推荐3000	3000
qualityKey	int	是	输出图质量，范围1～13，数值越大对应的画质越高；默认值12，对应画质99	12
resize_height	int	是	输出图尺寸（高），0表示原图输出，默认0，保留字段暂不支持配置	0
resize_width	int	是	输出图尺寸（宽），0表示原图输出，默认0，保留字段暂不支持配置	0
water_mark	int	是	是否水印，0无水印 1有水印	0
file_size_limit	array	否	输出图片大小范围，以示例值来说最小不超过原图的0.8，最大不超过原图的1.3	[0.8, 1.3]

all_params 参数结构：

客户端模块	客户端参数名	算法参数	类型	是否必填	范围	示例值
牙齿美化	牙齿美白	white_teeth	array	是	0～100	默认值 0
牙齿美化	牙齿修复	teeth_beauty	array	是	0、1	默认值 0

请求实例：

curl --location --request POST 'https://api.yunxiu.meitu.com/openapi/aiteeth_async?api_key=xxxx&api_secret=xxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "parameter": {
        "repost_url": "https://httpbin.org/",
        "all_params": {
            "white_teeth": [
                30,
                30,
                30,
                30,
                30
            ],
            "teeth_beauty": [
                1,
                1,
                1,
                1,
                1
            ]
        },
        "preview_size": 3000,
        "req_mask_version": 0,
        "people_type": [
            {
                "key": "man",
                "gender": 1,
                "name": "男",
                "age": [
                    15,
                    49
                ]
            },
            {
                "key": "woman",
                "gender": 0,
                "name": "女",
                "age": [
                    15,
                    49
                ]
            },
            {
                "key": "child",
                "gender": 0,
                "name": "儿童",
                "age": [
                    0,
                    14
                ]
            },
            {
                "key": "oldwoman",
                "gender": 0,
                "name": "老",
                "age": [
                    50,
                    100
                ]
            },
            {
                "key": "oldman",
                "gender": 1,
                "name": "老",
                "age": [
                    50,
                    100
                ]
            }
        ],
        "output": {
            "file_prefix": "",
            "file_start_no": 0,
            "format": "jpg",
            "preview_size": 3000,
            "quality": 0,
            "qualityKey": 12,
            "resize_height": 0,
            "resize_width": 0,
            "water_mark": 0,
            "file_size_limit": [
                0,
                0
            ]
        }
    },
    "media_info_list": [
        {
            "media_data": "https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg",
            "media_extra": {},
            "media_profiles": {
                "media_data_type": "url",
                "media_data_describe": "src"
            }
        }
    ]
}'

3. 结果查询

1. 消息通知回调

当异步的任务处理完成后，会通过业务侧请求中的 repost_url 参数来回调通知。业务侧在处理完成后，需响应一个状态码为 200 的响应，响应体不做要求。

注意1：回调请求只会回调一次，业务方需做好服务保障，如没有接收到回调请求，可以通过主动查询来获取结果。

注意2：同样的通知可能会多次回调给业务方，业务方的系统必须能够正确处理重复的通知。

注意3：处理回调的时候切记要判断回调内容是否正确后，再进行后续的业务逻辑处理，避免损失。

通知地址：业务方提供的 repost_url 参数

通知请求方法：POST

请求头：Content-Type：application/json

请求参数（Body参数）：

名称	类型	是否必填	描述	示例值
code	int	是	业务状态码	0
data	struct	是	结果数据	查看
message	string	否	提示信息	success

data 字段结构：

名称	类型	是否必填	描述	示例值
msg_id	string	是	异步任务ID	838b1d4a-ba79-44bd-b496-8a5a3b14097e
media_data	string	是	处理好的效果图地址	https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg

请求示例：

{
    "code": 0,
    "data": {
        "msg_id": "8547e55f-9492-40a9-ba0d-7041b717ee5a",
        "media_data": "https://obs-open-platform-photo.obs.cn-north-4.myhuaweicloud.com/mtopen/KxZo7A5mPWTP3FVhVThFu9VlA0s6p59c/MTY5MzE5MTYwMA==/c69a44d6-bace-446e-51e1-2dcd91a606ed.jpeg"
    },
    "message": "success",
    "request_id": "838b1d4a-ba79-44bd-b496-8a5a3b14097e"
}

3.2 轮训请求查询

注意：异步任务的结果只保存 12 个小时，请及时查询并转存效果图图片，过期后该异步任务 ID 将无法查询到结果。请求之后切记要解析响应的 Body 来做结果判断。

请求地址：https://api.yunxiu.meitu.com/openapi/query

请求方法：POST

请求参数（Body参数）：

名称	类型	是否必填	描述	示例值
msg_id	string	是	异步任务ID	6aca960e-6669-4f39-805e-9bc69705b82d

请求示例：

curl --location 'https://api.yunxiu.meitu.com/openapi/query' \
--header 'Content-Type: application/json' \
--data '{
    "api_key": "EtRGxLI8*******************aYUD2PUbMP",
    "api_secret": "wkTD89j******************************WUo",
    "msg_id": "6aca960e-6669-4f39-805e-9bc69705b82d"
}'

响应参数：

名称	类型	是否必填	描述	示例值
code	int	是	业务状态码	0
data	struct	是	结果数据	参考下文示例
message	string	否	提示信息	success
request_id	string	是	请求ID	838b1d4a-ba79-44bd-b496-8a5a3b14097e

data 字段结构：

名称	类型	是否必填	描述	示例值
msg_id	string	是	异步任务ID	838b1d4a-ba79-44bd-b496-8a5a3b14097e
media_data	string	是	处理好的效果图地址	https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg

响应示例：

{
    "code": 0,
    "data": {
        "msg_id": "8547e55f-9492-40a9-ba0d-7041b717ee5a",
        "media_data": "https://obs-open-platform-photo.obs.cn-north-4.myhuaweicloud.com/mtopen/KxZo7A5mPWTP3FVhVThFu9VlA0s6p59c/MTY5MzE5MTYwMA==/c69a44d6-bace-446e-51e1-2dcd91a606ed.jpeg"
    },
    "message": "success",
    "request_id": "838b1d4a-ba79-44bd-b496-8a5a3b14097e"
}

4. 错误码

错误码	错误信息	描述
0	SUCCESS	请求成功
29901	NOT_RESULT	图片还在处理中，结果还没出来
29902	RECORD_NOT_FOUND	异步任务 ID 已过期
90002	GATEWAY_AUTHORIZED_ERROR	接口未授权/密钥错误
11201	UNKNOW ERROR	用户图片地址下载失败
20001	UNKNOW ERROR	图片处理失败