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): formulaMethod
POST
Content-Type: application/json
Authentication
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
The request body contains exactly the following five top-level fields:
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | params | string | Inference parameters. The value must be a serialized JSON string, not a JSON object. |
| Yes | init_images | object[] | Image file list. Pass one source image to be restored. |
| Yes | task | string | Fixed value: /v1/High_Definition_V2/466662 |
| Yes | task_type | string | Fixed value: formula |
| No | sync_timeout | int | Default: 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:
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Image URL or base64 data |
| No | profile | object | Media parameters |
profile media parameters:
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | media_extra | object | Additional media parameters. The source document does not further define its fields. |
| No | media_profiles | object | Media description |
| No | version | string | The source request example uses v1. |
media_profiles media description:
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | media_data_type | string | url 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:
| Required | Field | Type | Description |
|---|---|---|---|
| No | rsp_media_type | string | Common 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. |
| Yes | parameter | object | Algorithm 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:
| 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. The value is 0 on success. |
| message | string | Business or error 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: processing; 2: failed; 9: use the query endpoint; 10: succeeded |
| result | object | Algorithm result |
| progress | number | Task progress, for example 0.1, 0.85, or 1 |
| predict_elapsed | int | Estimated duration in milliseconds |
| create_time | int64 | Creation timestamp in milliseconds |
| task_id | string | Task ID |
| custom_task_id | string | Custom task ID supplied by the client |
| trace_id | string | Trace identifier |
| client_info | string | Client information |
| init_images | object[]/null | Echo of the input media |
result fields:
| Field | Type | Description |
|---|---|---|
| id | string | Task ID |
| urls | string[] | 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:
| Field | Type | Description |
|---|---|---|
| parameter | object | Response media type identifier |
| media_info_list | object[] | Media result list. Each item contains image data and its associated information. |
parameter fields:
| Field | Type | Description |
|---|---|---|
| rsp_media_type | string | jpg indicates that media_data is a base64-encoded image. |
Fields in each media_info_list item:
| Field | Type | Description |
|---|---|---|
| media_data | string | Media file data. The success example in the source document uses a base64-encoded image. |
| media_profiles | object | Media file attributes |
media_profiles fields:
| Field | Type | Description |
|---|---|---|
| media_data_type | string | jpg 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.
| Field | Type | Description |
|---|---|---|
| ErrorCode | int | Error code |
| ErrorMsg | string | Error message |
| Data | string/null | Detailed 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
| ErrorCode | Error Message | Description |
|---|---|---|
| 20001 | PROCESS_ERROR | Processing error |
| 20003 | DETECT_NOT_FACE | No face detected |
| 20004 | MORE_THAN_ONE_FACE | More than one face detected |
| 20007 | MISSING_LANDMARK_ARGUMENTS | Facial landmark arguments were not provided |
| 20008 | UNSUITABLE_IMAGE | The image does not meet the requirements |
| 20009 | UNSUPPORT_TYPE | Unsupported type |
| 20010 | DETECT_NOT_FACE | No face detected in the second image |
| 20011 | UNSUITABLE_VERTICAL_IMAGE | Vertical height does not meet the requirements |
| 20012 | UNSUITABLE_HORIZONTAL_IMAGE | Horizontal width does not meet the requirements |
| 20013 | RESOLUTION_TOO_LARGE_ERROR | Resolution is too large |
| 20014 | NOT_FOUND | Image not found |
| 20015 | PICTURE_OVERRUN_ERROR | Image exceeds the limit |
| 20020 | DETECT_FACE_OUTOFIMAGE | Facial features are missing |
| 20021 | DETECT_FACE_PITCHANGLE_BIG | The face is not frontal; the nod or pitch angle is too large |
| 20022 | DETECT_FACE_YAWANGLE_BIG | The face is not frontal; the yaw or rotation angle is too large |
| 20023 | DETECT_FACE_LOWAREA | The face occupies too little of the image or has too few pixels |
| 21001 | LOAD_MODEL_ERROR | Model loading failed |
| 21002 | HAIR_MASK_LOSS | Hair mask is missing |
| 21003 | FACE_NUM_ERROR | Invalid number of faces |
| 21004 | AR_PARSE_FAULT | Failed to parse the plist in AR data |
| 21005 | AR_EEEOR_COUNT | AR face error |
| 21006 | AR_FACE_OUT | AR exceeds the face region |
| 21007 | JSON_ERROR | Invalid JSON content |
| 21008 | BACKGROUND_IMAGE_LOSS | Background image is missing |
| 21009 | BODY_MASK_LOSS | Body mask is missing |
| 21010 | FACE_ANGLE_ERROR | Invalid face angle |
| 21011 | SKIN_MASK_LOSS | Skin mask is missing |
| 21012 | BODY_INFO_LOSS | Skeleton points or outer contour points are missing |
| 21013 | RECT_OUT_IMAGE | Rectangle exceeds the image bounds |
| 30001 | GEN_ERROR | Generation 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);
}
}
}