Micro-level facial analysis

Description

The caller provides an image file or image URL for face detection and facial feature analysis.

Version

1.0

Image Requirements

  • Image formats: JPG (JPEG), PNG.
  • Image dimensions: minimum 48 × 48 pixels, maximum 4096 × 4096 pixels.
  • Image file size: no more than 10 MB.
  • Minimum face size in pixels: the face bounding box that the system can detect is square. Its minimum side length is 1/48 of the shorter side of the image and no less than 48 pixels. For example, for an image of 4096 × 3200 pixels, the minimum face size is 66 × 66 pixels.

Request URL

    Production environment: https://openapi.meitu.com
    Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
    Task name (task): /v1/micro_face_analysis/488097
    Task type (task_type): formula

Request Method

POST

Content-Type: application/json

Authorization

Open Platform API Signature

Request Parameters

RequiredParameterTypeDescription
RequiredparamsstringAlgorithm parameters (JSON string)
Requiredinit_imagesobject[]Image file list
RequiredtaskstringFixed value: /v1/micro_face_analysis/488097
Requiredtask_typestringFixed value: formula
Optionalsync_timeoutintDefault: 30; synchronous timeout duration

The structure of the init_images multimedia file parameter is as follows:

RequiredParameterTypeDescription
RequiredurlstringImage URL or base64 data; the content must match media_data_type
RequiredprofileobjectImage attribute information

profile attribute information

RequiredParameterTypeDescription
Requiredmedia_profilesobjectMedia attribute information
RequiredversionstringFixed value: v1

media_profiles media attribute information

RequiredParameterTypeDescription
Requiredmedia_data_typestringurl indicates an image URL; jpg indicates base64-encoded image data. Default: jpg

The params inference parameter is a JSON string with the following structure:

RequiredFieldTypeDescription
Optionalrsp_media_typestringDefault: url; jpg indicates base64
RequiredparameterobjectCore algorithm parameter object

parameter algorithm parameter details

RequiredParameterTypeDescription
Optionalreturn_attributesstringWhether to detect and return attributes such as facial feature shapes determined from facial characteristics. Pass facial_analysis when requesting facial feature analysis; separate multiple attributes with English commas and no spaces. If the field is absent or its value is empty, no attributes are detected
OptionalversionstringAlgorithm version, e.g. 1.0.0 or 2.0.0. Default: 1.0.0

Input Example

{
  "task": "/v1/micro_face_analysis/488097",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://example.com/input.jpg",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"return_attributes\":\"facial_analysis\",\"version\":\"1.0.0\"}}",
  "sync_timeout": 30
}

Response Description

Note: Generated results are periodically cleaned up. Please download and save them promptly.
FieldTypeDescription
request_idstringRequest identifier
trace_idstringTrace identifier
codeintBusiness status code; 0 indicates that the request was accepted successfully
error_codeintError code; 0 on success
messagestringBusiness message
tipsanyAdditional tips; may be null
dataobjectTask status and algorithm result

Field descriptions for a single element in data

FieldTypeDescription
statusintStatus code: -1 task not found; 0 created successfully; 1 running; 2 failed; 9 timed out, use the query endpoint to query; 10 succeeded
resultobjectMicro face analysis result; contains algorithm error information on failure
progressnumberTask progress
predict_elapsedintEstimated duration, in milliseconds
create_timeint64Creation timestamp, in milliseconds
task_idstringTask ID
custom_task_idstringCustomer-defined task ID
trace_idstringTrace identifier
client_infostringClient information
init_imagesobject[]/nullEcho of input media

Field descriptions in result

FieldTypeDescription
parameterobjectDescription of returned information, such as the algorithm version
media_info_listobject[]Each element contains the face analysis result for one image
ErrorCodeintAlgorithm error code returned on failure
ErrorMsgstringAlgorithm error message returned on failure
DatastringDetailed information returned on failure

Field descriptions in result.parameter

FieldTypeDescription
versionstringAlgorithm version

Field descriptions for a single element in result.media_info_list

FieldTypeDescription
media_extraobjectImage analysis result containing the faces field

Field descriptions in media_extra

FieldTypeDescription
facesobject[]Array of detected faces; an empty array if no face is detected

Field descriptions for a single element in faces

FieldTypeDescription
face_rectangleobjectPosition of the face bounding rectangle
face_attributesobjectFacial attribute features

Field descriptions in face_rectangle

FieldTypeDescription
leftfloatX-coordinate of the top-left corner of the face bounding box, as a proportion of the image width
topfloatY-coordinate of the top-left corner of the face bounding box, as a proportion of the image height
widthfloatWidth of the face bounding box, as a proportion of the image width
heightfloatHeight of the face bounding box, as a proportion of the image height

Field descriptions in face_attributes

FieldTypeDescription
eyebrow_shapeobjectEyebrow shape analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
eyebrow_concentrationobjectEyebrow density analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
eyebrow_concentration_distributionobjectEyebrow density distribution analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
eye_distanceobjectInter-eye distance result, containing value and confidence; see the facial feature analysis code description for the meaning of value
eyebrow_distanceobjectEyebrow distance result, containing value and confidence; see the facial feature analysis code description for the meaning of value
eye_shapeobjectEye shape analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
nose_shapeobjectNose shape analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
mouth_thicknessobjectLip thickness analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
lip_peakobjectLip peak analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
cheek_shapeobjectCheekbone shape analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
jaw_shapeobjectChin shape analysis result, containing value and confidence; see the facial feature analysis code description for the meaning of value
eyebags_yesobjectProbability of having eye bags, containing value and confidence
eyebags_noobjectProbability of not having eye bags, containing value and confidence
facetype_circularobjectProbability of a round face, containing value and confidence
facetype_ellipticobjectProbability of an oval face, containing value and confidence
facetype_longobjectProbability of a long face, containing value and confidence
facetype_prismobjectProbability of a diamond-shaped face, containing value and confidence
facetype_triangleobjectProbability of an inverted-triangle face, containing value and confidence
facetype_squareobjectProbability of a square face, containing value and confidence
risorius_yesobjectProbability of having prominent apple cheeks, containing value and confidence
risorius_noobjectProbability of not having prominent apple cheeks, containing value and confidence
temple_fullobjectProbability of full temples, containing value and confidence
temple_segobjectProbability of sunken temples, containing value and confidence
confidencefloatConfidence score, ranging from 0.0 to 1.0

Each object in face_attributes contains the following fields

FieldTypeDescription
valuestringAttribute code or probability value
confidencefloatConfidence score, ranging from 0.0 to 1.0

Error codes and messages specific to the current API

ErrorCodeErrorMsgDescription
20001PROCESS_ERRORProcessing error
20003DETECT_NOT_FACEFace missing

Response Examples

Successful Request Response Example

{
  "request_id": "req_202608100001",
  "trace_id": "trace_202608100001",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "tips": null,
  "data": {
    "status": 10,
    "result": {
      "parameter": {
        "version": "1.0.0"
      },
      "media_info_list": [
        {
          "media_extra": {
            "faces": [
              {
                "face_attributes": {
                  "cheek_shape": {"value": "ea02", "confidence": 1},
                  "eye_distance": {"value": "ad03", "confidence": 1},
                  "eye_shape": {"value": "ba01", "confidence": 1},
                  "eyebags_no": {"value": "0.999904", "confidence": 0.999904},
                  "eyebags_yes": {"value": "0.000096", "confidence": 0.000096},
                  "eyebrow_concentration": {"value": "ab02", "confidence": 1},
                  "eyebrow_concentration_distribution": {"value": "ac02", "confidence": 1},
                  "eyebrow_distance": {"value": "ae03", "confidence": 1},
                  "eyebrow_shape": {"value": "aa12", "confidence": 1},
                  "facetype_circular": {"value": "0.756924", "confidence": 0.756924},
                  "facetype_elliptic": {"value": "0.002978", "confidence": 0.002978},
                  "facetype_long": {"value": "0.060150", "confidence": 0.06015},
                  "facetype_prism": {"value": "0.000285", "confidence": 0.000285},
                  "facetype_square": {"value": "0.142799", "confidence": 0.142799},
                  "facetype_triangle": {"value": "0.036865", "confidence": 0.036865},
                  "jaw_shape": {"value": "fa03", "confidence": 1},
                  "lip_peak": {"value": "db03", "confidence": 1},
                  "mouth_thickness": {"value": "da01", "confidence": 1},
                  "nose_shape": {"value": "ca02", "confidence": 1},
                  "risorius_no": {"value": "0.025860", "confidence": 0.02586},
                  "risorius_yes": {"value": "0.974139", "confidence": 0.974139},
                  "temple_full": {"value": "0.999975", "confidence": 0.999975},
                  "temple_seg": {"value": "0.000025", "confidence": 0.000025}
                },
                "face_rectangle": {
                  "height": 0.108008,
                  "left": 0.425701,
                  "top": 0.106996,
                  "width": 0.162012
                }
              }
            ]
          }
        }
      ]
    },
    "progress": 100,
    "predict_elapsed": 120,
    "create_time": 1786320000000,
    "task_id": "task_202608100001",
    "custom_task_id": "",
    "trace_id": "trace_202608100001",
    "client_info": "",
    "init_images": null
  }
}

Response Example Requiring a Query

Use the query endpoint to query.

Response Status: 200

content-type is application/json; charset=utf-8

{
  "request_id": "req_202608100002",
  "trace_id": "trace_202608100002",
  "code": 0,
  "error_code": 0,
  "message": "processing",
  "tips": null,
  "data": {
    "status": 9,
    "result": {},
    "progress": 80,
    "predict_elapsed": 500,
    "create_time": 1786320000000,
    "task_id": "task_202608100002",
    "custom_task_id": "",
    "trace_id": "trace_202608100002",
    "client_info": "",
    "init_images": null
  }
}

Failed Request Response Example

Response Status: 400

content-type is application/json; charset=utf-8

{
  "request_id": "req_202608100003",
  "trace_id": "trace_202608100003",
  "code": 20003,
  "error_code": 20003,
  "message": "DETECT_NOT_FACE",
  "tips": null,
  "data": {
    "status": 2,
    "result": {
      "ErrorCode": 20003,
      "ErrorMsg": "DETECT_NOT_FACE",
      "Data": "Face missing"
    },
    "progress": 0,
    "predict_elapsed": 0,
    "create_time": 1786320000000,
    "task_id": "task_202608100003",
    "custom_task_id": "",
    "trace_id": "trace_202608100003",
    "client_info": "",
    "init_images": null
  }
}

General Error Codes and Messages

For details, see API Error Codes.

SDK Call Examples

Python

import json

import requests
from sign_sdk import sign

def api_call_example():
    key = "your_api_key"
    secret = "your_api_secret"
    url = "https://openapi.meitu.com/api/v1/sdk/sync/push"
    method = "POST"

    headers = {
        "Content-Type": "application/json",
        sign.HeaderHost: "openapi.meitu.com",
    }
    inner_params = {
        "rsp_media_type": "url",
        "parameter": {
            "return_attributes": "facial_analysis",
            "version": "1.0.0",
        },
    }
    payload = {
        "task": "/v1/micro_face_analysis/488097",
        "task_type": "formula",
        "init_images": [
            {
                "url": "https://example.com/input.jpg",
                "profile": {
                    "media_profiles": {"media_data_type": "url"},
                    "version": "v1",
                },
            }
        ],
        "params": json.dumps(inner_params, ensure_ascii=False),
        "sync_timeout": 30,
    }
    body = json.dumps(payload, ensure_ascii=False)

    signer = sign.Signer(key, secret)
    signed_request = signer.sign(url, method, headers, body)
    response = requests.Session().send(signed_request)
    print(f"Status: {response.status_code}")
    print(f"Response: {response.text}")

if __name__ == "__main__":
    api_call_example()

Go

package main

import (
	"fmt"
	"io"
	"net/http"

	"github.com/mtlab/api/signer"
)

func main() {
	key := "your_api_key"
	secret := "your_api_secret"
	signObj := signer.NewSigner(key, secret)

	url := "https://openapi.meitu.com/api/v1/sdk/sync/push"
	method := http.MethodPost
	headers := make(http.Header)
	headers.Set(signer.HeaderHost, "openapi.meitu.com")
	headers.Set("Content-Type", "application/json")

	body := `{
  "task": "/v1/micro_face_analysis/488097",
  "task_type": "formula",
  "init_images": [{
    "url": "https://example.com/input.jpg",
    "profile": {
      "media_profiles": {"media_data_type": "url"},
      "version": "v1"
    }
  }],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"return_attributes\":\"facial_analysis\",\"version\":\"1.0.0\"}}",
  "sync_timeout": 30
}`

	req, err := signObj.Sign(url, method, headers, body)
	if err != nil {
		fmt.Println("Failed to sign request:", err)
		return
	}

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Println("Failed to send request:", err)
		return
	}
	defer resp.Body.Close()

	responseBody, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("Read response failed:", err)
		return
	}
	fmt.Println("Response:", resp.StatusCode, string(responseBody))
}

PHP

<?php
require 'signer.php';

$key = 'your_api_key';
$secret = 'your_api_secret';
$signer = new Signer($key, $secret);

$url = 'https://openapi.meitu.com/api/v1/sdk/sync/push';
$method = 'POST';
$headers = ['Content-Type' => 'application/json'];

$innerParams = json_encode([
    'rsp_media_type' => 'url',
    'parameter' => [
        'return_attributes' => 'facial_analysis',
        'version' => '1.0.0',
    ],
]);

$body = json_encode([
    'task' => '/v1/micro_face_analysis/488097',
    'task_type' => 'formula',
    'init_images' => [
        [
            'url' => 'https://example.com/input.jpg',
            'profile' => [
                'media_profiles' => ['media_data_type' => 'url'],
                'version' => 'v1',
            ],
        ],
    ],
    'params' => $innerParams,
    'sync_timeout' => 30,
]);

$curl = $signer->sign($url, $method, $headers, $body);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);

if ($status === 0) {
    echo 'Error: ' . curl_error($curl);
} else {
    echo "Status: {$status}\n";
    echo "Response: {$response}\n";
}
curl_close($curl);
?>

Java

package com.meitu.openai.common;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws Exception {
        Signer signer = new Signer("your_api_key", "your_api_secret");
        String url = "https://openapi.meitu.com/api/v1/sdk/sync/push";
        String method = "POST";

        Map<String, String> headers = new HashMap<>();
        headers.put("Content-Type", "application/json");
        headers.put(Signer.HeaderHost, "openapi.meitu.com");

        String body = "{\n" +
                "  \"task\": \"/v1/micro_face_analysis/488097\",\n" +
                "  \"task_type\": \"formula\",\n" +
                "  \"init_images\": [{\n" +
                "    \"url\": \"https://example.com/input.jpg\",\n" +
                "    \"profile\": {\n" +
                "      \"media_profiles\": {\"media_data_type\": \"url\"},\n" +
                "      \"version\": \"v1\"\n" +
                "    }\n" +
                "  }],\n" +
                "  \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"return_attributes\\\":\\\"facial_analysis\\\",\\\"version\\\":\\\"1.0.0\\\"}}\",\n" +
                "  \"sync_timeout\": 30\n" +
                "}";

        Map<String, String> signedHeaders = signer.sign(url, method, headers, body);
        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        connection.setRequestMethod(method);
        for (Map.Entry<String, String> entry : signedHeaders.entrySet()) {
            connection.setRequestProperty(entry.getKey(), entry.getValue());
        }
        connection.setDoOutput(true);
        connection.getOutputStream().write(body.getBytes(StandardCharsets.UTF_8));

        int status = connection.getResponseCode();
        InputStream stream = status >= 400
                ? connection.getErrorStream()
                : connection.getInputStream();
        try (BufferedReader reader = new BufferedReader(new InputStreamReader(stream))) {
            StringBuilder response = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                response.append(line);
            }
            System.out.println("Response: " + status + " " + response);
        }
    }
}