Meidede - Video Portrait Beautification
Description
This API beautifies portraits in videos. It supports effects such as skin smoothing, skin brightening, filters, and makeup, and returns the processed video.
Version
1.0
Media Requirements
The input is a video supplied by URL. The source example uses an MP4 video and the successful response returns an MP4 video. The source document does not specify file-size, resolution, or video-duration limits.
API URL
Production host: https://openapi.meitu.com
Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
Task name (task): /v1/video_portrait_beauty/491342
Task type (task_type): formulaMethod
POST
Content-Type: application/json
Authentication
Request Parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | params | string | Algorithm parameters as a JSON string |
| Yes | init_images | object[] | Input media list |
| Yes | task | string | Fixed value: /v1/video_portrait_beauty/491342 |
| Yes | task_type | string | Fixed value: formula |
| No | sync_timeout | int | Synchronous timeout in seconds; default: 30 |
The legacy source table and request example use sync_timeout: -1 for immediate asynchronous return. This unified-gateway example uses the standard default value of 30.
init_images item fields:
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Media URL; the source example uses an MP4 video URL |
| Yes | profile | object | Media profile |
profile fields:
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | media_profiles | object | Media attributes |
| Yes | version | string | Fixed value: v1 |
media_profiles fields:
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | media_data_type | string | url means that url contains a media URL |
params is a JSON string. After decoding, it has the following structure:
| Required | Field | Type | Description |
|---|---|---|---|
| No | rsp_media_type | string | Default: url; controls the result media representation |
| Yes | parameter | object | Algorithm-specific parameters |
parameter fields:
| Required | Field | Type | Description |
|---|---|---|---|
| Not specified | formula | object | Beautification formula configuration |
| Not specified | repost_url | string | Callback URL; an empty string disables callbacks |
formula fields:
| Required | Field | Type | Description |
|---|---|---|---|
| Not specified | app_version | string | App version, such as 2.10.6 |
| Not specified | client_id | string | Client ID |
| Not specified | effects | object | Beautification effect configuration |
| Not specified | minimum_supported_version | number | Minimum supported version number |
| Not specified | platform | string | Platform, such as PC, iOS, or Android |
| Not specified | sdk_version | string | SDK version |
| Not specified | version | number | Formula version number |
effects fields:
| Required | Field | Type | Description |
|---|---|---|---|
| Not specified | auto_beauty | object | Automatic beautification configuration |
auto_beauty fields:
| Required | Field | Type | Description |
|---|---|---|---|
| Not specified | face_alpha | number | Face beautification intensity; -999 selects the default value; range: 0 to 100 |
| Not specified | filter_alpha | number | Filter intensity; -999 selects the default value; range: 0 to 100 |
| Not specified | makeup_alpha | number | Makeup intensity; -999 selects the default value; range: 0 to 100 |
| Not specified | material_id | number | Material ID; for example, 615000003 selects a specific beautification material |
| Not specified | skin_alpha | number | Skin beautification intensity; -999 selects the default value; range: 0 to 100 |
Request Example
{
"task": "/v1/video_portrait_beauty/491342",
"task_type": "formula",
"init_images": [
{
"url": "https://vmake-neo.stariidata.com/roboneo/convert_save/C1D5EB65_ec03af2d-4ed4-45cd-44fe-4805d81b5bda.mp4?k=57ad4db79319604c95cdafa69e07dfbe&t=6a11ceff",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"formula\":{\"app_version\":\"2.10.6\",\"client_id\":\"1189857533\",\"effects\":{\"auto_beauty\":{\"face_alpha\":-999,\"filter_alpha\":-999,\"makeup_alpha\":-999,\"material_id\":615000003,\"skin_alpha\":-999}},\"minimum_supported_version\":247,\"platform\":\"PC\",\"sdk_version\":\"\",\"version\":247},\"repost_url\":\"\"}}",
"sync_timeout": 30
}Response Fields
Generated results are cleaned up periodically. Download and save them promptly.| Field | Type | Description |
|---|---|---|
| request_id | string | Request identifier |
| trace_id | string | Trace identifier |
| code | int | Business status code; 0 means the request was accepted |
| 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 |
data fields:
| Field | Type | Description |
|---|---|---|
| status | int | -1: task not found; 0: created; 1: running; 2: failed; 9: timed out and requires the query API; 10: succeeded |
| result | object | Algorithm result |
| progress | number | Task progress from 0 to 1; 1 means complete |
| 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-supplied custom task ID |
| trace_id | string | Trace identifier inside data |
| client_info | string | Client information |
| init_images | object[]/null | Echo of input media |
result fields:
| Field | Type | Description |
|---|---|---|
| id | string | Unique task identifier |
| urls | array | Output media URL list |
| images | array | Output media list; equivalent to urls in the source response |
| parameters | object | Algorithm parameter information |
| data | object | Detailed algorithm response |
| msg | string | Result message |
| msg_id | string | Message ID |
| mtlab_res | object | Underlying algorithm response |
| media_info_list | array | Output media information list |
result.data fields:
| Field | Type | Description |
|---|---|---|
| duration | object | Stage duration and timestamp statistics |
| error_code | number | Algorithm error code; 0 means success |
| error_msg | string | Algorithm error message |
| media_info_list | array | Media information list |
| msg_id | string | Message ID |
| parameter | object | Parameter echo |
duration fields:
| Field | Type | Description |
|---|---|---|
| alg_process_time | number | Algorithm processing time in milliseconds |
| created_timestamp | number | Task creation timestamp in seconds |
| pull_timestamp | number | Resource retrieval timestamp in seconds |
| repost_time | number | Retry duration |
| upload_time | number | Upload duration in milliseconds |
| waiting_time | number | Queue waiting time in milliseconds |
media_info_list item fields:
| Field | Type | Description |
|---|---|---|
| media_data | string | Media URL |
| media_extra | object | Additional media information |
| media_profiles | object | Media attributes |
media_profiles fields:
| Field | Type | Description |
|---|---|---|
| media_data_type | string | Media data type, such as MP4 or url |
parameter and parameters fields:
| Field | Type | Description |
|---|---|---|
| version | string | Version number |
mtlab_res fields:
| Field | Type | Description |
|---|---|---|
| ErrorCode | number | Underlying algorithm error code |
| ErrorMsg | string | Underlying algorithm error message |
| error_code | number | Compatibility error-code field |
| error_msg | string | Compatibility error-message field |
| media_info_list | array/null | Media information list |
| msg_id | string | Message ID |
| parameter | object/null | Parameter information |
API-specific errors:
| ErrorCode | Error | Description |
|---|---|---|
| 20001 | PROCESS_ERROR | Processing error |
Response Examples
Success
{
"request_id": "",
"trace_id": "",
"code": 0,
"error_code": 0,
"message": "success",
"tips": null,
"data": {
"status": 10,
"result": {
"id": "t_mt1a3i5n7bf6b1d56d-20b2-4c44-a586-b05c82f69d4c",
"urls": [
"https://obs-large.mtlab.meitu.com/mtopen/ff56d688358849259556be0f50065a60/0518d384-063e-47ec-68b8-245f53d90ae3.mp4"
],
"parameters": {
"version": "1.0.0"
},
"data": {
"duration": {
"alg_process_time": 50000,
"created_timestamp": 1779441396,
"pull_timestamp": 1779441396,
"repost_time": 0,
"upload_time": 0,
"waiting_time": 0
},
"error_code": 0,
"error_msg": "success",
"media_info_list": [
{
"media_data": "https://obs-large.mtlab.meitu.com/mtopen/ff56d688358849259556be0f50065a60/0518d384-063e-47ec-68b8-245f53d90ae3.mp4",
"media_extra": {},
"media_profiles": {
"media_data_type": "MP4"
}
}
],
"msg_id": "146696ed-ea26-4cdc-964f-242e468c3cb8",
"parameter": {
"version": "1.0.0"
}
},
"msg": "success",
"msg_id": "146696ed-ea26-4cdc-964f-242e468c3cb8",
"images": [
"https://obs-large.mtlab.meitu.com/mtopen/ff56d688358849259556be0f50065a60/0518d384-063e-47ec-68b8-245f53d90ae3.mp4"
],
"mtlab_res": {
"ErrorCode": 0,
"ErrorMsg": "",
"error_code": 0,
"error_msg": "",
"media_info_list": null,
"msg_id": "146696ed-ea26-4cdc-964f-242e468c3cb8",
"parameter": null
},
"media_info_list": [
{
"media_data": "https://obs-large.mtlab.meitu.com/mtopen/ff56d688358849259556be0f50065a60/0518d384-063e-47ec-68b8-245f53d90ae3.mp4",
"media_extra": {},
"media_profiles": {
"media_data_type": "MP4"
}
}
]
},
"progress": 1,
"predict_elapsed": 10000,
"create_time": 1779441395925,
"task_id": "t_mt1a3i5n7bf6b1d56d-20b2-4c44-a586-b05c82f69d4c",
"custom_task_id": "",
"trace_id": "",
"client_info": "",
"init_images": null
}
}Query Required
Use the query API to retrieve the task 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_mt1a3i5n7bf6b1d56d-20b2-4c44-a586-b05c82f69d4c"
},
"progress": 0,
"predict_elapsed": 10000,
"create_time": 1779441395925,
"task_id": "t_mt1a3i5n7bf6b1d56d-20b2-4c44-a586-b05c82f69d4c",
"custom_task_id": "",
"trace_id": "",
"client_info": "",
"init_images": null
}
}Failure
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": {
"id": "",
"data": {
"error_code": 20001,
"error_msg": "PROCESS_ERROR"
},
"msg": "PROCESS_ERROR",
"msg_id": ""
},
"progress": 0,
"predict_elapsed": 0,
"create_time": 0,
"task_id": "",
"custom_task_id": "",
"trace_id": "",
"client_info": "",
"init_images": null
}
}General Error Codes
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": {
"formula": {
"app_version": "2.10.6",
"client_id": "1189857533",
"effects": {
"auto_beauty": {
"face_alpha": -999,
"filter_alpha": -999,
"makeup_alpha": -999,
"material_id": 615000003,
"skin_alpha": -999,
}
},
"minimum_supported_version": 247,
"platform": "PC",
"sdk_version": "",
"version": 247,
},
"repost_url": "",
},
}
payload = {
"task": "/v1/video_portrait_beauty/491342",
"task_type": "formula",
"init_images": [
{
"url": "https://vmake-neo.stariidata.com/roboneo/convert_save/C1D5EB65_ec03af2d-4ed4-45cd-44fe-4805d81b5bda.mp4?k=57ad4db79319604c95cdafa69e07dfbe&t=6a11ceff",
"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/video_portrait_beauty/491342",
"task_type": "formula",
"init_images": [{
"url": "https://vmake-neo.stariidata.com/roboneo/convert_save/C1D5EB65_ec03af2d-4ed4-45cd-44fe-4805d81b5bda.mp4?k=57ad4db79319604c95cdafa69e07dfbe&t=6a11ceff",
"profile": {
"media_profiles": {"media_data_type": "url"},
"version": "v1"
}
}],
"params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"formula\":{\"app_version\":\"2.10.6\",\"client_id\":\"1189857533\",\"effects\":{\"auto_beauty\":{\"face_alpha\":-999,\"filter_alpha\":-999,\"makeup_alpha\":-999,\"material_id\":615000003,\"skin_alpha\":-999}},\"minimum_supported_version\":247,\"platform\":\"PC\",\"sdk_version\":\"\",\"version\":247},\"repost_url\":\"\"}}",
"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' => [
'formula' => [
'app_version' => '2.10.6',
'client_id' => '1189857533',
'effects' => [
'auto_beauty' => [
'face_alpha' => -999,
'filter_alpha' => -999,
'makeup_alpha' => -999,
'material_id' => 615000003,
'skin_alpha' => -999,
],
],
'minimum_supported_version' => 247,
'platform' => 'PC',
'sdk_version' => '',
'version' => 247,
],
'repost_url' => '',
],
]);
$body = json_encode([
'task' => '/v1/video_portrait_beauty/491342',
'task_type' => 'formula',
'init_images' => [
[
'url' => 'https://vmake-neo.stariidata.com/roboneo/convert_save/C1D5EB65_ec03af2d-4ed4-45cd-44fe-4805d81b5bda.mp4?k=57ad4db79319604c95cdafa69e07dfbe&t=6a11ceff',
'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/video_portrait_beauty/491342\",\n" +
" \"task_type\": \"formula\",\n" +
" \"init_images\": [{\n" +
" \"url\": \"https://vmake-neo.stariidata.com/roboneo/convert_save/C1D5EB65_ec03af2d-4ed4-45cd-44fe-4805d81b5bda.mp4?k=57ad4db79319604c95cdafa69e07dfbe&t=6a11ceff\",\n" +
" \"profile\": {\n" +
" \"media_profiles\": {\"media_data_type\": \"url\"},\n" +
" \"version\": \"v1\"\n" +
" }\n" +
" }],\n" +
" \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"formula\\\":{\\\"app_version\\\":\\\"2.10.6\\\",\\\"client_id\\\":\\\"1189857533\\\",\\\"effects\\\":{\\\"auto_beauty\\\":{\\\"face_alpha\\\":-999,\\\"filter_alpha\\\":-999,\\\"makeup_alpha\\\":-999,\\\"material_id\\\":615000003,\\\"skin_alpha\\\":-999}},\\\"minimum_supported_version\\\":247,\\\"platform\\\":\\\"PC\\\",\\\"sdk_version\\\":\\\"\\\",\\\"version\\\":247},\\\"repost_url\\\":\\\"\\\"}}\",\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);
}
}
}