Lossless Upscaling
Description
This API submits a lossless upscaling task and supports 2×, 4×, 8×, and custom-size upscaling. The algorithm begins asynchronous execution after the task is submitted successfully. You can actively query the algorithm result through the query API or receive it at the callback URL supplied in the request.
Image Requirements
Supported formats: JPG, JPEG, and BMP.
API URL
Production environment: https://openapi.meitu.com
Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
Task name (task): /v1/Image_Upscaler/466663
Task type (task_type): formulaMethod
POST
Content-Type: application/json
Authentication
Request Parameters
The request body contains exactly the following five top-level fields:
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | params | string | Inference parameters serialized as a JSON string |
| Yes | init_images | object[] | List of image files |
| Yes | task | string | Fixed value: /v1/Image_Upscaler/466663 |
| 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 API to obtain the result |
init_images image parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Image URL or base64 data |
| No | profile | object | Multimedia parameters |
profile multimedia parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | media_extra | object | Additional multimedia parameters; the source document does not define its internal fields further |
| No | media_profiles | object | Multimedia description |
| No | version | string | The source request example uses v1 |
media_profiles multimedia description
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | media_data_type | string | url passes an image by URL; jpg passes the base64 data of a JPG image |
params is a JSON string. Its deserialized structure is as follows:
| Required | Field | Type | Description |
|---|---|---|---|
| No | rsp_media_type | string | Common response media type. Default: url; url returns the result image as a URL, while jpg returns it as JPG base64 data |
| Yes | parameter | object | Lossless upscaling algorithm parameter object |
rsp_media_type is a sibling of parameter, and all algorithm fields appear only inside parameter. The source document's top-level parameter table listed rsp_media_type as a top-level request-body field, while its parameter table and request example placed it inside parameter; one location also used the value name base64. The same source document provides complete jpg/url mappings for input media, response media, and returned fields. This document normalizes it as a common field under the unified gateway structure and uses the fully mapped jpg/url values.
parameter algorithm details
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | ir_mode | int | Effect mode. Fixed value: 4 |
| No | save_photo_format | int | Saved image format. Default: 1; 1 means JPG and 2 means PNG |
| Yes | sr_mode | int | Upscaling mode; 1 means 2×, 4×, or 8× upscaling, and 2 means custom-size upscaling |
| No | sr_num | int | Upscaling factor; 2, 4, and 8 mean 2×, 4×, and 8× upscaling, respectively |
| No | max_width | int | Maximum width of the returned image. Default: -1 |
| No | max_height | int | Maximum height of the returned image. Default: -1 |
| No | sr_size_w | int | Custom width after upscaling |
| No | sr_size_h | int | Custom height after upscaling |
Request Example
{
"task": "/v1/Image_Upscaler/466663",
"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\":{\"sr_mode\":1,\"ir_mode\":4,\"save_photo_format\":1,\"max_width\":8000,\"max_height\":8000,\"sr_num\":2}}",
"sync_timeout": 30
}Response Fields
| Field | Type | Description |
|---|---|---|
| request_id | string | Request identifier |
| trace_id | string | Trace identifier |
| code | int | Business status code; 0 means the request was accepted successfully |
| error_code | int | Error code; 0 on success |
| message | string | Business information or error message |
| tips | any | Additional tips; may be null |
| data | object | Task status and algorithm result |
data fields
| Field | Type | Description |
|---|---|---|
| status | int | -1: task not found; 0: created successfully; 1: processing; 2: failed; 9: use the query API; 10: succeeded |
| msg | string | Task status description |
| result | object | Algorithm result |
| progress | number | Task progress, such as 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 on success
| Field | Type | Description |
|---|---|---|
| id | string | Task ID, which can be used to query task status |
| url | string | Result image URL; the legacy polling example in the source document reads the result from this field |
| parameter | object | Result information type indicator |
| media_info_list | object[] | Multimedia result list; each item contains image data and its associated information |
Returned parameter fields
| Field | Type | Description |
|---|---|---|
| rsp_media_type | string | url means media_data is an image URL; jpg means media_data is JPG base64 data |
Fields of each media_info_list item
| Field | Type | Description |
|---|---|---|
| media_data | string | Result image URL or base64-encoded image data, depending on rsp_media_type |
| media_profiles | object | Multimedia file properties |
Returned media_profiles fields
| Field | Type | Description |
|---|---|---|
| media_data_type | string | url means media_data is an image URL; jpg means media_data is JPG base64 data |
result fields on failure
| Field | Type | Description |
|---|---|---|
| ErrorCode | int | Algorithm error code |
| ErrorMsg | string | Algorithm error message |
| Data | string/null | Detailed error information; null when no data is available |
The legacy polling code in the source document also treats status 20 as a failure together with status 2, but the source document does not provide a name or definition for status 20. During integration, rely on the data.status value actually returned by the unified gateway.
Response Examples
Successful Response (status=10)
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,
"msg": "success",
"result": {
"id": "task_1234567890",
"url": "https://example.com/result.jpg",
"parameter": {"rsp_media_type": "url"},
"media_info_list": [{
"media_data": "https://example.com/result.jpg",
"media_profiles": {"media_data_type": "url"}
}]
},
"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 (status=9)
Use the query API and the returned task ID to query 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,
"msg": "processing",
"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 (status=2)
Response Status: 400
content-type: application/json; charset=utf-8
{
"request_id": "req_1234567890",
"trace_id": "trace_1234567890",
"code": 20001,
"error_code": 20001,
"message": "PROCESS_ERROR",
"tips": null,
"data": {
"status": 2,
"msg": "PROCESS_ERROR",
"result": {
"id": "task_1234567890",
"ErrorCode": 20001,
"ErrorMsg": "PROCESS_ERROR",
"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 points were not provided |
| 20008 | UNSUITABLE_IMAGE | The photo 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 requirements are not met |
| 20012 | UNSUITABLE_HORIZONTAL_IMAGE | Horizontal width requirements are not met |
| 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 head is tilted up or down too far |
| 20022 | DETECT_FACE_YAWANGLE_BIG | The face is not frontal; the head is turned or rotated too far |
| 20023 | DETECT_FACE_LOWAREA | The face occupies too little of the image or has too few pixels |
| 21001 | LOAD_MODEL_ERROR | Failed to load the model |
| 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 area |
| 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 | Skeletal landmarks 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.
Reference Parameters
Each example below is the complete object obtained after deserializing the params string.
2× Upscaling
{"rsp_media_type":"url","parameter":{"sr_mode":1,"ir_mode":4,"save_photo_format":1,"max_width":8000,"max_height":8000,"sr_num":2}}4× Upscaling
{"rsp_media_type":"url","parameter":{"sr_mode":1,"ir_mode":4,"save_photo_format":1,"max_width":8000,"max_height":8000,"sr_num":4}}8× Upscaling
{"rsp_media_type":"url","parameter":{"sr_mode":1,"ir_mode":4,"save_photo_format":1,"max_width":8000,"max_height":8000,"sr_num":8}}Custom Width and Height (Proportional Scaling)
{"rsp_media_type":"url","parameter":{"sr_mode":2,"ir_mode":4,"save_photo_format":1,"max_width":8000,"max_height":8000,"sr_size_w":1920,"sr_size_h":1080}}SDK Examples
Each example signs the complete JSON body that is actually sent. The body contains exactly five top-level fields: task, task_type, init_images, params, and sync_timeout.
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"
method = "POST"
headers = {"Content-Type": "application/json", sign.HeaderHost: "openapi.meitu.com"}
inner_params = {
"rsp_media_type": "url",
"parameter": {"sr_mode": 1, "ir_mode": 4, "save_photo_format": 1,
"max_width": 8000, "max_height": 8000, "sr_num": 2},
}
payload = {
"task": "/v1/Image_Upscaler/466663",
"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, method, 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/Image_Upscaler/466663",
"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\":{\"sr_mode\":1,\"ir_mode\":4,\"save_photo_format\":1,\"max_width\":8000,\"max_height\":8000,\"sr_num\":2}}",
"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';
$method = 'POST';
$headers = ['Content-Type' => 'application/json'];
$innerParams = json_encode([
'rsp_media_type' => 'url',
'parameter' => [
'sr_mode' => 1, 'ir_mode' => 4, 'save_photo_format' => 1,
'max_width' => 8000, 'max_height' => 8000, 'sr_num' => 2,
],
]);
$body = json_encode([
'task' => '/v1/Image_Upscaler/466663',
'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);
echo "Status: {$status}\nResponse: {$response}\n";
curl_close($curl);
?>Java
package com.meitu.openai.common;
import java.io.InputStream;
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/Image_Upscaler/466663\",\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\\\":{\\\"sr_mode\\\":1,\\\"ir_mode\\\":4,\\\"save_photo_format\\\":1,\\\"max_width\\\":8000,\\\"max_height\\\":8000,\\\"sr_num\\\":2}}\",\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();
System.out.println("Response: " + status + " " + new String(stream.readAllBytes(), StandardCharsets.UTF_8));
}
}