Description

This API processes portrait enhancement requests. See the details below for its capabilities and behavior.

Version

2.0

Media Requirements

Video formats: H.263, H.264, H.265, AV1, MPEG-4, VP8, and VP9.
Video dimensions: PVG does not support videos within 144 × 144; hardware codecs support a maximum long edge of 4096 pixels, and both width and height must be even numbers.

API URL

    Production environment: https://openapi.meitu.com
    Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
    Task name (task): /v1/portrait_enhancement_basic/488147
    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

Required	Parameter	Type	Description
Yes	params	string	Algorithm parameters (JSON string)
Yes	init_images	object[]	Media file list
Yes	task	string	Fixed value: `/v1/portrait_enhancement_basic/488147`
Yes	task_type	string	Fixed value: `formula`
No	sync_timeout	int	Defaults to `30`; synchronous timeout duration

The structure of each media item in init_images is as follows:

Required	Parameter	Type	Description
Yes	url	string	Video URL or base64 data
Yes	profile	object	Attribute information

profile attribute information:

Required	Parameter	Type	Description
Yes	media_profiles	object	Media attributes
Yes	version	string	Fixed value: `v1`

media_profiles media attributes:

Required	Parameter	Type	Description
Yes	media_data_type	string	`url` indicates a URL; the corresponding media type indicates base64 data

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

Required	Field	Type	Description
No	rsp_media_type	string	Defaults to `url`; `jpg` indicates base64 data
Yes	parameter	object	Core algorithm parameter object

parameter algorithm parameter details:

Required	Parameter	Type	Description
No	media_data_type	string	Image data type: `jpg` means `media_data` contains a base64-encoded image (default); `url` means `media_data` contains an image URL
No	open_degree	int	Openness setting: `1` enables openness; `0` disables it (default)
No	assign_degree	int	Portrait restoration intensity in the range `[0, 100]`; default: `80`
No	skip_frames	int[]	Frame-skipping settings: `[start, end]` specifies the number of frames to skip at the beginning and end; `[0, 0]` enables segmentation without skipping; `None` disables segmentation (default)
No	sharp_degree	int	Sharpening intensity in the range `[0, 10]`; default: `5`
No	save_rate	int	Maximum output-video bitrate multiplier relative to the input; `0` means unlimited (default)
No	sr_rate	float	Resolution scaling factor; default: `1`

Request Example

{
  "task": "/v1/portrait_enhancement_basic/488147",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTczOTUxNjQwMA==/5164853f-02af-4ce9-6c1d-fc5a68c247cd.mp4",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"media_data_type\":\"url\",\"open_degree\":0,\"assign_degree\":80,\"sharp_degree\":5,\"sr_rate\":1}}",
  "sync_timeout": 30
}

Response Fields

Generated results are periodically deleted. Download and save them promptly.

Field	Type	Description
request_id	string	Request identifier
trace_id	string	Trace identifier
code	int	Business status code; `0` indicates that the request was accepted successfully
error_code	int	Error code; `0` on success
message	string	Business message
tips	any	Additional information; may be null
data	object	Task status and algorithm result

Fields in data:

Field	Type	Description
status	int	Status code: -1 task not found; 0 created successfully; 1 processing; 2 failed; 9 timed out—use the Query API; 10 succeeded
result	object	Algorithm result
progress	number	Task progress
predict_elapsed	int	Estimated processing time in milliseconds
create_time	int64	Creation timestamp in milliseconds
task_id	string	Task ID
custom_task_id	string	Client-defined task ID
trace_id	string	Trace identifier
client_info	string	Client information
init_images	object[]/null	Echoed input media

Fields in result:

Field	Type	Description
id	String	Unique task identifier
urls	String[]	Output media URL list
images	String[]	Output media (compatibility field)
msg	String	Response message
msg_id	String	Message ID
parameters	Object	Output parameter information
data	Object	Detailed processing result
media_info_list	Array	Media information list
mtlab_res	Object	Underlying service response information

Fields in result.parameters:

Field	Type	Description
rsp_media_type	String	Response media type, such as `url`
version	String	Algorithm version information

Fields in result.data:

Field	Type	Description
duration	Object	Processing time for each stage
error_code	Number	Error code
error_msg	String	Error message
extra	Object	Additional information
media_info_list	Array	Media information list
msg_id	String	Message ID
parameter	Object	Parameter information (same as `parameters`)

Fields in duration:

Field	Type	Description
alg_process_time	Number	Algorithm processing time in milliseconds
created_timestamp	Number	Creation time as a timestamp in seconds
pull_timestamp	Number	Pull timestamp
repost_time	Number	Retry duration
upload_time	Number	Upload duration
waiting_time	Number	Queueing duration

Fields in extra:

Field	Type	Description
algo_msg	Object	Internal algorithm information
sale_path	String	API path
trans_meta	Object	Transcoding information

Fields in algo_msg:

Field	Type	Description
alg_time	Float	Algorithm execution time in seconds

Fields in trans_meta:

req_meta (input information):

Field	Type	Description
duration	Float	Input media duration
media_type	String	Media type

rsp_meta (output information):

Field	Type	Description
data_rate	Float	Bitrate
duration	Number	Duration
frame_num	Number	Frame count
frame_rate	Number	Frame rate
height	Number	Height
width	Number	Width
resolution	String	Resolution (for example, 480P)
size	Number	File size in bytes
media_type	String	Media type

Fields in media_info_list:

Field	Type	Description
media_data	String	Media URL
media_extra	Object	Additional information
media_profiles	Object	Media attributes

Fields in media_profiles:

Field	Type	Description
media_data_fps	Number	Frame rate
media_data_height	Number	Height
media_data_width	Number	Width
media_data_size	Number	File size
media_data_type	String	Media type (for example, `url`)

Fields in mtlab_res:

Field	Type	Description
ErrorCode	Number	Error code
ErrorMsg	String	Error message
error_code	Number	Error code (compatibility field)
error_msg	String	Error message (compatibility field)
media_info_list	Array	Media information
msg_id	String	Message ID
parameter	Object	Parameter information

Response Examples

Successful Response Example

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": 10,
    "result": {
      "id": "t_mt1a3i5n7b3567e106-xxxx-428a-9fce-3b91591f3b8d",
      "urls": [
        "https://obs-large.mtlab.meitu.com/mtopen/4e200dc6bf574fee899cf9e0dabe27e6/b4960953-0cd6-4188-7949-f334bbcc98d7.mp4"
      ],
      "parameters": {
        "rsp_media_type": "url",
        "version": "HDVideo version: 2.9.1 - 更新parsing trt加速"
      },
      "data": {
        "duration": {
          "alg_process_time": 2756,
          "created_timestamp": 1773739299,
          "pull_timestamp": 1773739300,
          "repost_time": 0,
          "upload_time": 72,
          "waiting_time": 1289
        },
        "error_code": 0,
        "error_msg": "success",
        "extra": {
          "algo_msg": {
            "alg_time": 2.53835129737854
          },
          "sale_path": "/v2/hdvideo_async",
          "trans_meta": {
            "req_meta": [
              {
                "duration": 2222.222,
                "media_type": "video"
              }
            ],
            "rsp_meta": [
              {
                "data_rate": 3448.156568771866,
                "duration": 2222,
                "frame_num": 40,
                "frame_rate": 18,
                "height": 512,
                "media_type": "video",
                "resolution": "480P",
                "size": 996492,
                "width": 512
              }
            ]
          }
        },
        "media_info_list": [
          {
            "media_data": "https://obs-large.mtlab.meitu.com/mtopen/4e200dc6bf574fee899cf9e0dabe27e6/b4960953-0cd6-4188-7949-f334bbcc98d7.mp4",
            "media_extra": null,
            "media_profiles": {
              "media_data_fps": 18,
              "media_data_height": 512,
              "media_data_size": 996492,
              "media_data_type": "url",
              "media_data_width": 512
            }
          }
        ],
        "msg_id": "b764d092-xxxx-40d0-4128-r0094612aa68",
        "parameter": {
          "rsp_media_type": "url",
          "version": "HDVideo version: 2.9.1 - 更新parsing trt加速"
        }
      },
      "msg": "success",
      "msg_id": "b764d092-xxxx-40d0-4128-r0094612aa68",
      "images": [
        "https://obs-large.mtlab.meitu.com/mtopen/4e200dc6bf574fee899cf9e0dabe27e6/b4960953-0cd6-4188-7949-f334bbcc98d7.mp4"
      ],
      "mtlab_res": {
        "ErrorCode": 0,
        "ErrorMsg": "",
        "error_code": 0,
        "error_msg": "",
        "media_info_list": null,
        "msg_id": "b764d092-xxxx-40d0-4128-r0094612aa68",
        "parameter": null
      },
      "media_info_list": [
        {
          "media_data": "https://obs-large.mtlab.meitu.com/mtopen/4e200dc6bf574fee899cf9e0dabe27e6/b4960953-0cd6-4188-7949-f334bbcc98d7.mp4",
          "media_extra": null,
          "media_profiles": {
            "media_data_fps": 18,
            "media_data_height": 512,
            "media_data_size": 996492,
            "media_data_type": "url",
            "media_data_width": 512
          }
        }
      ]
    },
    "progress": 1,
    "predict_elapsed": 10000,
    "create_time": 1773739299799,
    "task_id": "t_mt1a3i5n7b3567e106-xxxx-428a-9fce-3b91591f3b8d",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

Query-Required 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_mt1a3i5n7b3567e106-xxxx-428a-9fce-3b91591f3b8d"
    },
    "progress": 0,
    "predict_elapsed": 10000,
    "create_time": 1773739299799,
    "task_id": "t_mt1a3i5n7b3567e106-xxxx-428a-9fce-3b91591f3b8d",
    "custom_task_id": "",
    "trace_id": "9c2d79a5-xxxx-47db-8f2c-a77a91112006",
    "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": "PROCESS_ERROR",
  "tips": null,
  "data": {
    "status": 2,
    "result": {
      "error_code": 20001,
      "error_msg": "PROCESS_ERROR"
    },
    "progress": 0,
    "predict_elapsed": 0,
    "create_time": 0,
    "task_id": "",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

General Error Codes

For details, see API Error Codes.

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": {
            "media_data_type": "url",
            "open_degree": 0,
            "assign_degree": 80,
            "sharp_degree": 5,
            "sr_rate": 1,
        },
    }
    payload = {
        "task": "/v1/portrait_enhancement_basic/488147",
        "task_type": "formula",
        "init_images": [
            {
                "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTczOTUxNjQwMA==/5164853f-02af-4ce9-6c1d-fc5a68c247cd.mp4",
                "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/portrait_enhancement_basic/488147",
  "task_type": "formula",
  "init_images": [{
    "url": "https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTczOTUxNjQwMA==/5164853f-02af-4ce9-6c1d-fc5a68c247cd.mp4",
    "profile": {
      "media_profiles": {"media_data_type": "url"},
      "version": "v1"
    }
  }],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"media_data_type\":\"url\",\"open_degree\":0,\"assign_degree\":80,\"sharp_degree\":5,\"sr_rate\":1}}",
  "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' => [
        'media_data_type' => 'url',
        'open_degree' => 0,
        'assign_degree' => 80,
        'sharp_degree' => 5,
        'sr_rate' => 1,
    ],
]);

$body = json_encode([
    'task' => '/v1/portrait_enhancement_basic/488147',
    'task_type' => 'formula',
    'init_images' => [
        [
            'url' => 'https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTczOTUxNjQwMA==/5164853f-02af-4ce9-6c1d-fc5a68c247cd.mp4',
            '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/portrait_enhancement_basic/488147\",\n" +
                "  \"task_type\": \"formula\",\n" +
                "  \"init_images\": [{\n" +
                "    \"url\": \"https://obs.mtlab.meitu.com/public/EtRGxLI8ulQ43pGhuZfym9aYUD2PUbMP/MTczOTUxNjQwMA==/5164853f-02af-4ce9-6c1d-fc5a68c247cd.mp4\",\n" +
                "    \"profile\": {\n" +
                "      \"media_profiles\": {\"media_data_type\": \"url\"},\n" +
                "      \"version\": \"v1\"\n" +
                "    }\n" +
                "  }],\n" +
                "  \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"media_data_type\\\":\\\"url\\\",\\\"open_degree\\\":0,\\\"assign_degree\\\":80,\\\"sharp_degree\\\":5,\\\"sr_rate\\\":1}}\",\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);
        }
    }
}

Portrait Enhancement (Basic)

Description

Version

Media Requirements

API URL

Method

Authentication

Request Parameters

Request Example

Response Fields

Response Examples

Successful Response Example

Query-Required Response Example

Failed Response Example

General Error Codes

SDK Examples

Python

Go

PHP

Java