HomeDocsConsolePricing

Backlit Hair Light

Description

This API submits a backlit hair light task. After submission, the system executes the editing algorithm asynchronously. You can retrieve the result through the query API, or configure a timeout in the request to wait for the result.

Version

1.0

Image Requirements

  • JPG, PNG

API URL

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

Method

POST
Content-Type: application/json

Authentication

Open Platform API Signature

Credits cannot be used to pay for API calls. Please visit the MV console to activate this API and purchase or manage resource packages.

Request Parameters

RequiredParameterTypeDescription
YesparamsstringInference parameters as a JSON string
Yesinit_imagesobject[]Media files (input images)
YestaskstringFixed value: /v1/ai_hairlight/485032
Yestask_typestringFixed value: formula
Nosync_timeoutintDefault: 30; synchronous timeout duration

The init_images media file parameters are structured as follows:

RequiredParameterTypeDescription
YesurlstringMedia URL or base64 data
YesprofileobjectMedia metadata

The profile metadata is structured as follows:

RequiredParameterTypeDescription
Yesmedia_profilesobjectMedia properties
YesversionstringFixed value: v1

The media_profiles media properties are structured as follows:

RequiredParameterTypeDescription
Yesmedia_data_typestringurl indicates URL input; jpg indicates base64-encoded input

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

RequiredParameterTypeDescription
Norsp_media_typestringDefault: url; jpg indicates base64 output
YesparameterobjectCore algorithm parameter object

Algorithm parameters in parameter:

RequiredParameterTypeDescription
NoalphaintIntensity. Default: 100; valid range: 0-100
NostylestringEffect style. Default: hair glow (hair_light); change to sunny sky: sky_swap_0610_6000
Noresize_flagintWhether the output uses the original image dimensions. Default: 0, which preserves the original dimensions; 1 returns non-original dimensions

Request Example

{
    "init_images": [
        {
            "url": "https://example.com/input.jpg",
            "profile": {
                "media_profiles": {
                    "media_data_type": "url"
                },
                "version": "v1"
            }
        }
    ],
    "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"alpha\":100,\"style\":\"hair_light\",\"resize_flag\":0}}",
    "task": "/v1/ai_hairlight/485032",
    "task_type": "formula",
    "sync_timeout": 30
}

Response Fields

Generated results are periodically deleted. Download and save them promptly.
FieldTypeDescription
request_idstringRequest ID
trace_idstringTrace ID
codeintBusiness status code: 0 indicates success; nonzero indicates failure
error_codeintDetailed error code
messagestringStatus message
tipsanyAdditional information; may be null
dataobjectBusiness data

Fields in data:

FieldTypeDescription
statusintStatus code: -1 task not found; 0 created; 1 processing; 2 failed; 9 timed out—use the query API; 10 succeeded
resultobjectTask result information
progressnumberTask progress
predict_elapsedintEstimated processing time in milliseconds
create_timeint64Creation timestamp in milliseconds
task_idstringSystem task ID
custom_task_idstringCustom task ID
trace_idstringTrace ID
client_infostringClient information
init_imagesobject[]/nullInput media echoed by the service

Fields in result:

FieldTypeDescription
idstringTask ID
codeintAlgorithm error code
urlsstring[]Result image URL list
parametersobjectResult parameters
dataobjectAlgorithm processing data
msgstringProcessing message
msg_idstringMessage ID
imagesstring[]Result image URL list
mtlab_resobjectUnderlying algorithm response
media_info_listobject[]Media information list

Response Examples

Successful Response Example

{
    "request_id": "",
    "trace_id": "",
    "code": 0,
    "error_code": 0,
    "message": "success",
    "tips": null,
    "data": {
        "status": 10,
        "result": {
            "id": "t_mt1a3i5n7bb0eeb195-dd29-41ed-a630-6d224240325e",
            "urls": [
                "https://obs-large.mtlab.meitu.com/mtopen/4e200dc6bf574fee899cf9e0dabe27e6/64a3e21c-64f6-461f-5f22-29896334d7d0.jpeg"
            ],
            "parameters": {
                "down_mode": "0",
                "rsp_media_type": "url",
                "version": "1.0.8-1"
            },
            "data": {
                "duration": {
                    "alg_process_time": 3504,
                    "created_timestamp": 1765187278,
                    "pull_timestamp": 1765187278,
                    "repost_time": 0,
                    "upload_time": 59,
                    "waiting_time": 190
                },
                "error_code": 0,
                "error_msg": "success",
                "extra": {
                    "trans_meta": {
                        "req_meta": [
                            {
                                "media_type": "image"
                            }
                        ],
                        "rsp_meta": [
                            {
                                "height": 2227,
                                "media_type": "image",
                                "size": 883,
                                "width": 1655
                            }
                        ]
                    }
                },
                "media_info_list": [
                    {
                        "media_data": "https://obs-large.mtlab.meitu.com/mtopen/4e200dc6bf574fee899cf9e0dabe27e6/64a3e21c-64f6-461f-5f22-29896334d7d0.jpeg",
                        "media_extra": null,
                        "media_profiles": {
                            "media_data_height": 2227,
                            "media_data_size": 904652,
                            "media_data_type": "url",
                            "media_data_width": 1655
                        }
                    }
                ],
                "msg_id": "71fbda46-6f04-4b32-4a6c-r00913ffde3e",
                "parameter": {
                    "down_mode": "0",
                    "rsp_media_type": "url",
                    "version": "1.0.8-1"
                }
            },
            "msg": "success",
            "msg_id": "71fbda46-6f04-4b32-4a6c-r00913ffde3e",
            "images": [
                "https://obs-large.mtlab.meitu.com/mtopen/4e200dc6bf574fee899cf9e0dabe27e6/64a3e21c-64f6-461f-5f22-29896334d7d0.jpeg"
            ],
            "mtlab_res": {
                "ErrorCode": 0,
                "ErrorMsg": "",
                "error_code": 0,
                "error_msg": "",
                "media_info_list": null,
                "msg_id": "71fbda46-6f04-4b32-4a6c-r00913ffde3e",
                "parameter": null
            },
            "media_info_list": [
                {
                    "media_data": "https://obs-large.mtlab.meitu.com/mtopen/4e200dc6bf574fee899cf9e0dabe27e6/64a3e21c-64f6-461f-5f22-29896334d7d0.jpeg",
                    "media_extra": null,
                    "media_profiles": {
                        "media_data_height": 2227,
                        "media_data_size": 904652,
                        "media_data_type": "url",
                        "media_data_width": 1655
                    }
                }
            ]
        },
        "progress": 1,
        "predict_elapsed": 10000,
        "create_time": 1765187278660,
        "task_id": "t_mt1a3i5n7bb0eeb195-dd29-41ed-a630-6d224240325e",
        "custom_task_id": "",
        "trace_id": "e4eb8feb-528f-43a4-8052-69e08cb223e1",
        "client_info": "",
        "init_images": null
    }
}

Pending Response Example

Use the query API to retrieve the result. Response Status: 200

Content-Type: application/json; charset=utf-8

{
    "request_id": "",
    "trace_id": "",
    "code": 0,
    "error_code": 0,
    "message": "success",
    "tips": null,
    "data": {
        "status": 9,
        "result": {
            "id": "t_mt1a3i5n7b3da6d589-46b5-4f66-a0bb-8dd22f2a172e"
        },
        "progress": 0,
        "predict_elapsed": 10000,
        "create_time": 1759202368761,
        "task_id": "t_mt1a3i5n7b3da6d589-46b5-4f66-a0bb-8dd22f2a172e",
        "custom_task_id": "",
        "trace_id": "9129a3a2-99c4-46ce-8731-0e100e2fbee7",
        "client_info": "",
        "init_images": null
    }
}

Failed Response Example

Response Status: 400

Content-Type: application/json; charset=utf-8

{
    "request_id": "",
    "trace_id": "",
    "code": 20001,
    "error_code": 20001,
    "message": "ALGO_MODEL_CRASH",
    "tips": null,
    "data": {
        "status": 2,
        "result": {
            "id": "t_mt1a3i5n7be8d575cc-2ffb-4e0c-85a8-1824110e31b8",
            "code": 20001,
            "data": {
                "duration": {
                    "alg_process_time": 0,
                    "created_timestamp": 1759201989,
                    "pull_timestamp": 1759201989,
                    "repost_time": 0,
                    "upload_time": 0,
                    "waiting_time": 0
                },
                "error_code": 20001,
                "error_msg": "ALGO_MODEL_CRASH",
                "extra": {

                },
                "media_info_list": [

                ],
                "msg_id": "c1b09cb2-6e05-4d21-55ab-r007b1f21bec",
                "parameter": null
            },
            "msg": "ALGO_MODEL_CRASH",
            "msg_id": "c1b09cb2-6e05-4d21-55ab-r007b1f21bec"
        },
        "progress": 1,
        "predict_elapsed": 10000,
        "create_time": 1759201989444,
        "task_id": "t_mt1a3i5n7be8d575cc-2ffb-4e0c-85a8-1824110e31b8",
        "custom_task_id": "",
        "trace_id": "",
        "client_info": "",
        "init_images": null
    }
}

General Error Codes and Messages

Error codes and messages specific to this API:

ErrorCode Status CodeError MessageDescription
20001PROCESS_ERRORProcessing error

See API Error Codes for details.

SDK 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": {
            "alpha": 100,
            "style": "hair_light",
            "resize_flag": 0,
        },
    }
    payload = {
        "task": "/v1/ai_hairlight/485032",
        "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/ai_hairlight/485032",
  "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\":{\"alpha\":100,\"style\":\"hair_light\",\"resize_flag\":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' => [
        'alpha' => 100,
        'style' => 'hair_light',
        'resize_flag' => 0,
    ],
]);

$body = json_encode([
    'task' => '/v1/ai_hairlight/485032',
    '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/ai_hairlight/485032\",\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\\\":{\\\"alpha\\\":100,\\\"style\\\":\\\"hair_light\\\",\\\"resize_flag\\\":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);
        }
    }
}