HomeDocsConsolePricing

Cosmetic Dentistry

This document provides guidance for integrating the Teeth Beautification service of the Meitu Cloud Retouch Intelligent API. API access permission must be obtained before the service can be integrated and used. The API is integrated through asynchronous HTTP calls. All services provided by the Meitu Cloud Retouch API are asynchronous APIs. Currently, results can be obtained in two ways: Message Notification Callback、Result Query

1. Common Parameters

Request Header

NameTypeRequiredfDescription
Content-TypestringYesFixed value: "application/json"

Request Method

POST

2. API List

1. Preset ID Integration

Request URL:https://api.yunxiu.meitu.com/openapi/aiteeth_async

Request Method:POST

Request Header:

NameTypeRequiredfDescription
Content-TypestringYesFixed value: "application/json"

Request Parameters (Query Parameters):

NameTypeRequiredDescriptionExample Value
api_keystringYesApplication KeyEtRGxLI8*******************aYUD2PUbMP
api_secretstringYesApplication SecretwkTD89j******************************WUo

Request Parameters (Body Parameters):

NameTypeRequiredDescriptionExample Value
media_codestringYesPreset ID (What is a Preset ID?)MTyunxiu163aa58942
media_datastringYesOriginal image URL(Base64 is not supported; only URLs are supported)https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg
repost_urlstringNoResult callback URL, provided by the integrating partyhttps://httpbin.org/

Request Example:

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/",
}'

Response Parameters:

NameTypeRequiredDescriptionExample Value
codeintYesBusiness status code0
datastructYesResult data{ "msg\_id": "8547e55f-9492-40a9-ba0d-7041b717ee5a" }
messagestringNoMessagesuccess
request_idstringYesRequest ID30c2194d-049b-4f69-95f8-0e9b440df2eb

Response Example:

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

2.2 Raw Parameter Integration

Request URL:https://api.yunxiu.meitu.com/openapi/aiteeth_async

Request Method:POST

Request Parameters (Query Parameters):

NameTypeRequiredDescriptionExample Value
api_keystringYesApplication KeyEtRGxLI8*******************aYUD2PUbMP
api_secretstringYesApplication SecretwkTD89j******************************WUo

Request Parameters (Body Parameters):

NameTypeRequiredDescriptionExample Value
parameterstructYesProcessing parametersView
media_info_listarrayYesOriginal image URLView
extrastructNoAdditional information{}
  • media_info_list parameter structure
NameTypeRequiredDescriptionExample Value
media_datastringYesOriginal image URL(Base64 is not supported; only URLs are supported)https://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg
media_extrastructNoAdditional resource description information{}
media_profilesstructYesResource description for the image URLFixed value: {"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 parameter structure:
NameTypeRequiredDescriptionExample Value
all_paramsstructYesImage processing parametersSee below
repost_urlstringNoResult callback URL, provided by the integrating partyhttps://httpbin.org/
rsp_mask_versionintYes-Fixed value: 500
preview_sizeintYes-Fixed value: 3000
people_typearrayYesArray order for custom age and gender attributesSee below
outputstructYesOutput structureSee below
  • filter parameter structure:
NameTypeRequiredDescriptionRangeExample Value
filter_idstringNoFilter ID
filters_lut_alphaintNoIntensity value0–100Default: 50
filter_is_blackintNo
  • Object structure within arrays such as blush and eyesocket:
NameTypeRequiredDescriptionExample Value
idstringYesEffect name; default value is empty"luozhuang"
colorstringYesColor value in RGBA format; default value: 0;0;0;0""
alphaintYesEffect intensity; default value: 050
  • people_type parameter structure:

This field defines the mapping between the gender and age of persons in the image. Five types of gender settings are currently supported.

NameTypeRequiredDescriptionExample Value
agelistYesAge range for the defined attribute[50, 100]
genderintYesGender: 1 = male, 0 = female
keystringYesGender attributeoldman
namestringNoGender attribute nameOld

For parameters that support gender and age attributes, the data structure is an array containing five elements, corresponding respectively to the five gender/age definitions in people_type. For example:

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

The definition order of people_type is as follows (Note: each element in the people_type array is an object. Strings are used here only for readability. Refer to the recommended configuration for the actual data structure):

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

Accordingly, beauty_belly_alpha takes effect as follows:

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

Recommended configuration parameters:

[
    {
        "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 parameter structure:
NameTypeRequiredDescriptionExample Value
formatstringYesOutput format; supports JPG and PNGjpg
preview_sizestringYesOriginal image segmentation size; recommended value: 30003000
qualityKeyintYesOutput image quality, range 1–13. A larger value indicates higher image quality; the default value is 12, corresponding to quality 9912
resize_heightintYesOutput image size (height). 0 indicates output at the original image size; default: 0. Reserved field; configuration is not currently supported0
resize_widthintYesOutput image size (width). 0 indicates output at the original image size; default: 0. Reserved field; configuration is not currently supported0
water_markintYesWhether to add a watermark: 0 = no watermark, 1 = watermark0
file_size_limitarrayNoOutput image size range. Based on the example value, the minimum does not exceed 0.8 times the original image size, and the maximum does not exceed 1.3 times the original image size[0.8, 1.3]
  • all_params parameter structure:
Client ModuleClient Parameter NameAlgorithm ParameterTypeRequiredRangeExample Value
Teeth BeautificationTeeth Whiteningwhite_teetharrayYes0–100Default: 0
Teeth BeautificationTeeth Restorationteeth_beautyarrayYes0, 1Default: 0

Request Example:

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. Result Query

1. Message Notification Callback

After an asynchronous task has been processed, a callback notification is sent to the repost_url specified in the business-side request. Upon receipt and processing of the callback, the business side must return an HTTP response with status code 200. No specific response body is required.

Note 1: The callback request is sent only once. The business side must ensure service availability. If the callback request is not received, the result can be obtained through an active query.

Note 2: The same notification may be delivered to the business side multiple times. The business-side system must be able to correctly handle duplicate notifications.

Note 3: When processing a callback, always verify that the callback content is correct before executing subsequent business logic to avoid potential losses.

Notification URL: the repost_url parameter provided by the business side

Notification Request Method:POST

Request Header:Content-Type: application/json

Request Parameters (Body Parameters):

NameTypeRequiredDescriptionExample Value
codeintYesBusiness status code0
datastructYesResult dataView
messagestringNoMessagesuccess
  • data field structure:
NameTypeRequiredDescriptionExample Value
msg_idstringYesAsynchronous task ID838b1d4a-ba79-44bd-b496-8a5a3b14097e
media_datastringYesURL of the processed output imagehttps://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg

Request Example:

{
    "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 Polling Query

Note: Results of asynchronous tasks are retained for only 12 hours. Query and save the processed image promptly. After expiration, the result can no longer be retrieved using the asynchronous task ID. After submitting the request, be sure to parse the response body to determine the result.

Request URL:https://api.yunxiu.meitu.com/openapi/query

Request Method:POST

Request Parameters (Body Parameters):

NameTypeRequiredDescriptionExample Value
msg_idstringYesAsynchronous task ID6aca960e-6669-4f39-805e-9bc69705b82d

Request Example:

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"
}'

Response Parameters:

NameTypeRequiredDescriptionExample Value
codeintYesBusiness status code0
datastructYesResult dataSee the example below
messagestringNoMessagesuccess
request_idstringYesRequest ID838b1d4a-ba79-44bd-b496-8a5a3b14097e

data field structure:

NameTypeRequiredDescriptionExample Value
msg_idstringYesAsynchronous task ID838b1d4a-ba79-44bd-b496-8a5a3b14097e
media_datastringYesURL of the processed output imagehttps://beauty-public.zone1.meitudata.com/Marvel/1680141903114.jpg

Response Example:

{
    "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. Error Codes

Error CodeError MessageDescription
0SUCCESSRequest successful
29901NOT_RESULTThe image is still being processed; the result is not yet available
29902RECORD_NOT_FOUNDThe asynchronous task ID has expired
90002GATEWAY_AUTHORIZED_ERRORAPI not authorized / invalid key
11201UNKNOW ERRORFailed to download the user image URL
20001UNKNOW ERRORImage processing failed