Image Quality Restoration V2

Description

This API processes image quality restoration requests in the cloud.

Image Requirements

  • JPG and PNG formats are supported.
  • Image dimensions must be at least 48×48 pixels and at most 4096×4096 pixels.
  • The image file size must not exceed 2 MB.
  • The smallest face bounding box that the system can detect is a square whose side length is 1/48 of the image's shorter side, but no less than 48 pixels. For example, for a 4096×3200-pixel image, the minimum face size is 66×66 pixels.

API URL

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

Method

POST

Content-Type: application/json

Authentication

Open Platform API Signing

Request Parameters

The request body contains exactly the following five top-level fields:

RequiredParameterTypeDescription
YesparamsstringInference parameters. The value must be a serialized JSON string, not a JSON object.
Yesinit_imagesobject[]Image file list. Pass one source image to be restored.
YestaskstringFixed value: /v1/High_Definition_V2/466662
Yestask_typestringFixed value: formula
Nosync_timeoutintDefault: 30. -1 means do not wait. If synchronous waiting times out, status 9 is returned; use the query endpoint to retrieve the result.

init_images image parameters:

RequiredParameterTypeDescription
YesurlstringImage URL or base64 data
NoprofileobjectMedia parameters

profile media parameters:

RequiredParameterTypeDescription
Nomedia_extraobjectAdditional media parameters. The source document does not further define its fields.
Nomedia_profilesobjectMedia description
NoversionstringThe source request example uses v1.

media_profiles media description:

RequiredParameterTypeDescription
Nomedia_data_typestringurl transfers the media file as a URL; jpg transfers the media file as JPG base64 data.

params is a JSON string. Its deserialized structure is described below:

RequiredFieldTypeDescription
Norsp_media_typestringCommon response media type at the same level as parameter. Default: url. jpg returns the result image as base64 data; url returns the result image as a URL.
YesparameterobjectAlgorithm parameter object. The source document defines no other algorithm parameters for this API; pass an empty object, {}.

Request Example

{
  "task": "/v1/High_Definition_V2/466662",
  "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\":{}}",
  "sync_timeout": 30
}

Response Fields

The unified gateway response has the following structure:

FieldTypeDescription
request_idstringRequest identifier
trace_idstringTrace identifier
codeintBusiness status code. 0 indicates that the request was accepted successfully.
error_codeintError code. The value is 0 on success.
messagestringBusiness or error message
tipsanyAdditional information; may be null
dataobjectTask status and algorithm result

data fields:

FieldTypeDescription
statusint-1: task not found; 0: created; 1: processing; 2: failed; 9: use the query endpoint; 10: succeeded
resultobjectAlgorithm result
progressnumberTask progress, for example 0.1, 0.85, or 1
predict_elapsedintEstimated duration in milliseconds
create_timeint64Creation timestamp in milliseconds
task_idstringTask ID
custom_task_idstringCustom task ID supplied by the client
trace_idstringTrace identifier
client_infostringClient information
init_imagesobject[]/nullEcho of the input media

result fields:

FieldTypeDescription
idstringTask ID
urlsstring[]Result image list. When rsp_media_type=url, the values are image URLs; when rsp_media_type=jpg, the values are base64-encoded image data.

The source document also defines the following algorithm media result fields:

FieldTypeDescription
parameterobjectResponse media type identifier
media_info_listobject[]Media result list. Each item contains image data and its associated information.

parameter fields:

FieldTypeDescription
rsp_media_typestringjpg indicates that media_data is a base64-encoded image.

Fields in each media_info_list item:

FieldTypeDescription
media_datastringMedia file data. The success example in the source document uses a base64-encoded image.
media_profilesobjectMedia file attributes

media_profiles fields:

FieldTypeDescription
media_data_typestringjpg indicates that media_data is a base64-encoded image.

The source document defines the following algorithm failure fields. A unified gateway failure response also reports the error through the top-level code, error_code, and message fields and through data.result.

FieldTypeDescription
ErrorCodeintError code
ErrorMsgstringError message
Datastring/nullDetailed information

Response Examples

Successful Response

Response Status: 200

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

{
  "request_id": "req_1234567890",
  "trace_id": "trace_1234567890",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "tips": null,
  "data": {
    "status": 10,
    "result": {
      "id": "task_1234567890",
      "urls": ["https://example.com/result.jpg"]
    },
    "progress": 1,
    "predict_elapsed": 0,
    "create_time": 1718172000000,
    "task_id": "task_1234567890",
    "custom_task_id": "",
    "trace_id": "trace_1234567890",
    "client_info": "",
    "init_images": null
  }
}

Query-Required Response

When data.status is 9, use the query endpoint and the returned task ID to retrieve the result.

Response Status: 200

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

{
  "request_id": "req_1234567890",
  "trace_id": "trace_1234567890",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "tips": null,
  "data": {
    "status": 9,
    "result": {"id": "task_1234567890"},
    "progress": 0,
    "predict_elapsed": 10000,
    "create_time": 1718172000000,
    "task_id": "task_1234567890",
    "custom_task_id": "",
    "trace_id": "trace_1234567890",
    "client_info": "",
    "init_images": null
  }
}

Failed Response

Response Status: 400

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

{
  "request_id": "req_1234567890",
  "trace_id": "trace_1234567890",
  "code": 20003,
  "error_code": 20003,
  "message": "DETECT_NOT_FACE",
  "tips": null,
  "data": {
    "status": 2,
    "result": {
      "id": "task_1234567890",
      "ErrorCode": 20003,
      "ErrorMsg": "detect no face",
      "Data": null
    },
    "progress": 1,
    "predict_elapsed": 0,
    "create_time": 1718172000000,
    "task_id": "task_1234567890",
    "custom_task_id": "",
    "trace_id": "trace_1234567890",
    "client_info": "",
    "init_images": null
  }
}

API-Specific Error Codes and Messages

ErrorCodeError MessageDescription
20001PROCESS_ERRORProcessing error
20003DETECT_NOT_FACENo face detected
20004MORE_THAN_ONE_FACEMore than one face detected
20007MISSING_LANDMARK_ARGUMENTSFacial landmark arguments were not provided
20008UNSUITABLE_IMAGEThe image does not meet the requirements
20009UNSUPPORT_TYPEUnsupported type
20010DETECT_NOT_FACENo face detected in the second image
20011UNSUITABLE_VERTICAL_IMAGEVertical height does not meet the requirements
20012UNSUITABLE_HORIZONTAL_IMAGEHorizontal width does not meet the requirements
20013RESOLUTION_TOO_LARGE_ERRORResolution is too large
20014NOT_FOUNDImage not found
20015PICTURE_OVERRUN_ERRORImage exceeds the limit
20020DETECT_FACE_OUTOFIMAGEFacial features are missing
20021DETECT_FACE_PITCHANGLE_BIGThe face is not frontal; the nod or pitch angle is too large
20022DETECT_FACE_YAWANGLE_BIGThe face is not frontal; the yaw or rotation angle is too large
20023DETECT_FACE_LOWAREAThe face occupies too little of the image or has too few pixels
21001LOAD_MODEL_ERRORModel loading failed
21002HAIR_MASK_LOSSHair mask is missing
21003FACE_NUM_ERRORInvalid number of faces
21004AR_PARSE_FAULTFailed to parse the plist in AR data
21005AR_EEEOR_COUNTAR face error
21006AR_FACE_OUTAR exceeds the face region
21007JSON_ERRORInvalid JSON content
21008BACKGROUND_IMAGE_LOSSBackground image is missing
21009BODY_MASK_LOSSBody mask is missing
21010FACE_ANGLE_ERRORInvalid face angle
21011SKIN_MASK_LOSSSkin mask is missing
21012BODY_INFO_LOSSSkeleton points or outer contour points are missing
21013RECT_OUT_IMAGERectangle exceeds the image bounds
30001GEN_ERRORGeneration error

Common Error Codes and Messages

See API Error Codes.

SDK Examples

Each example signs the complete final JSON body that is actually sent.

Python

import json
import requests
from sign_sdk import sign

key = "your_api_key"
secret = "your_api_secret"
url = "https://openapi.meitu.com/api/v1/sdk/sync/push"
headers = {"Content-Type": "application/json", sign.HeaderHost: "openapi.meitu.com"}
inner_params = {"rsp_media_type": "url", "parameter": {}}
payload = {
    "task": "/v1/High_Definition_V2/466662",
    "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)
signed_request = sign.Signer(key, secret).sign(url, "POST", headers, body)
response = requests.Session().send(signed_request)
print(response.status_code, response.text)

Go

package main

import (
	"fmt"
	"io"
	"net/http"
	"github.com/mtlab/api/signer"
)

func main() {
	signObj := signer.NewSigner("your_api_key", "your_api_secret")
	url := "https://openapi.meitu.com/api/v1/sdk/sync/push"
	headers := make(http.Header)
	headers.Set(signer.HeaderHost, "openapi.meitu.com")
	headers.Set("Content-Type", "application/json")
	body := `{
  "task":"/v1/High_Definition_V2/466662",
  "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\":{}}",
  "sync_timeout":30
}`
	req, err := signObj.Sign(url, http.MethodPost, headers, body)
	if err != nil { panic(err) }
	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	responseBody, err := io.ReadAll(resp.Body)
	if err != nil { panic(err) }
	fmt.Println(resp.StatusCode, string(responseBody))
}

PHP

<?php
require 'signer.php';

$signer = new Signer('your_api_key', 'your_api_secret');
$url = 'https://openapi.meitu.com/api/v1/sdk/sync/push';
$headers = ['Content-Type' => 'application/json'];
$innerParams = json_encode([
    'rsp_media_type' => 'url',
    'parameter' => (object) [],
]);
$body = json_encode([
    'task' => '/v1/High_Definition_V2/466662',
    '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, 'POST', $headers, $body);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
echo "Status: {$status}\nResponse: {$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";
        Map<String, String> headers = new HashMap<>();
        headers.put("Content-Type", "application/json");
        headers.put(Signer.HeaderHost, "openapi.meitu.com");
        String body = "{\n" +
                "  \"task\":\"/v1/High_Definition_V2/466662\",\n" +
                "  \"task_type\":\"formula\",\n" +
                "  \"init_images\":[{\"url\":\"https://example.com/input.jpg\",\"profile\":{\"media_profiles\":{\"media_data_type\":\"url\"},\"version\":\"v1\"}}],\n" +
                "  \"params\":\"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{}}\",\n" +
                "  \"sync_timeout\":30\n" +
                "}";
        Map<String, String> signedHeaders = signer.sign(url, "POST", headers, body);
        HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
        connection.setRequestMethod("POST");
        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);
        }
    }
}