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): formula

Method

POST

Content-Type: application/json

Authentication

Open Platform API Signature

Request Parameters

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

RequiredParameterTypeDescription
YesparamsstringInference parameters serialized as a JSON string
Yesinit_imagesobject[]List of image files
YestaskstringFixed value: /v1/Image_Upscaler/466663
Yestask_typestringFixed value: formula
Nosync_timeoutintDefault: 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

RequiredParameterTypeDescription
YesurlstringImage URL or base64 data
NoprofileobjectMultimedia parameters

profile multimedia parameters

RequiredParameterTypeDescription
Nomedia_extraobjectAdditional multimedia parameters; the source document does not define its internal fields further
Nomedia_profilesobjectMultimedia description
NoversionstringThe source request example uses v1

media_profiles multimedia description

RequiredParameterTypeDescription
Nomedia_data_typestringurl 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:

RequiredFieldTypeDescription
Norsp_media_typestringCommon response media type. Default: url; url returns the result image as a URL, while jpg returns it as JPG base64 data
YesparameterobjectLossless 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

RequiredParameterTypeDescription
Yesir_modeintEffect mode. Fixed value: 4
Nosave_photo_formatintSaved image format. Default: 1; 1 means JPG and 2 means PNG
Yessr_modeintUpscaling mode; 1 means 2×, 4×, or 8× upscaling, and 2 means custom-size upscaling
Nosr_numintUpscaling factor; 2, 4, and 8 mean 2×, 4×, and 8× upscaling, respectively
Nomax_widthintMaximum width of the returned image. Default: -1
Nomax_heightintMaximum height of the returned image. Default: -1
Nosr_size_wintCustom width after upscaling
Nosr_size_hintCustom 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

FieldTypeDescription
request_idstringRequest identifier
trace_idstringTrace identifier
codeintBusiness status code; 0 means the request was accepted successfully
error_codeintError code; 0 on success
messagestringBusiness information or error message
tipsanyAdditional tips; may be null
dataobjectTask status and algorithm result

data fields

FieldTypeDescription
statusint-1: task not found; 0: created successfully; 1: processing; 2: failed; 9: use the query API; 10: succeeded
msgstringTask status description
resultobjectAlgorithm result
progressnumberTask progress, such as 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 on success

FieldTypeDescription
idstringTask ID, which can be used to query task status
urlstringResult image URL; the legacy polling example in the source document reads the result from this field
parameterobjectResult information type indicator
media_info_listobject[]Multimedia result list; each item contains image data and its associated information

Returned parameter fields

FieldTypeDescription
rsp_media_typestringurl means media_data is an image URL; jpg means media_data is JPG base64 data

Fields of each media_info_list item

FieldTypeDescription
media_datastringResult image URL or base64-encoded image data, depending on rsp_media_type
media_profilesobjectMultimedia file properties

Returned media_profiles fields

FieldTypeDescription
media_data_typestringurl means media_data is an image URL; jpg means media_data is JPG base64 data

result fields on failure

FieldTypeDescription
ErrorCodeintAlgorithm error code
ErrorMsgstringAlgorithm error message
Datastring/nullDetailed 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

ErrorCodeError MessageDescription
20001PROCESS_ERRORProcessing error
20003DETECT_NOT_FACENo face detected
20004MORE_THAN_ONE_FACEMore than one face detected
20007MISSING_LANDMARK_ARGUMENTSFacial landmark points were not provided
20008UNSUITABLE_IMAGEThe photo does not meet the requirements
20009UNSUPPORT_TYPEUnsupported type
20010DETECT_NOT_FACENo face detected in the second image
20011UNSUITABLE_VERTICAL_IMAGEVertical height requirements are not met
20012UNSUITABLE_HORIZONTAL_IMAGEHorizontal width requirements are not met
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 head is tilted up or down too far
20022DETECT_FACE_YAWANGLE_BIGThe face is not frontal; the head is turned or rotated too far
20023DETECT_FACE_LOWAREAThe face occupies too little of the image or has too few pixels
21001LOAD_MODEL_ERRORFailed to load the model
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 area
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_LOSSSkeletal landmarks 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.

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));
    }
}