AI Super Resolution V1

Description

This API processes image super-resolution requests in the cloud.

Image Requirements

JPG, JPEG, and BMP formats are supported.

API URL

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

Method

POST

Content-Type: application/json

Authentication

Open Platform API Signature

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:

RequiredParameterTypeDescription
YesparamsstringInference parameters as a JSON string
Yesinit_imagesobject[]Image file list
YestaskstringFixed value: /v1/Ultra_High_Definition/466657
Yestask_typestringFixed value: formula
Nosync_timeoutintDefault: 30. Set to -1 to return immediately without waiting. If the synchronous wait times out, status 9 is returned; use the status API to retrieve the result

init_images image parameter structure

RequiredParameterTypeDescription
YesurlstringImage URL or base64 data
NoprofileobjectMedia parameters

profile media parameter structure

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

media_profiles media description structure

RequiredParameterTypeDescription
Nomedia_data_typestringDefault: url. url passes the image by URL; jpg passes JPG base64 data

params is a JSON string whose deserialized structure is described below

RequiredFieldTypeDescription
Norsp_media_typestringDefault: url. url returns the result image as a URL; jpg returns it as JPG base64 data
YesparameterobjectSuper-resolution algorithm parameter object

parameter algorithm parameters

RequiredParameterTypeDescription
Yesstyle_idintAdaptive style ID. Obtain it from the adaptive style enumeration API
Nosr_numintImage scaling factor. Only 2 and 4 are supported; default: 2. At 2x, the maximum supported source-image size is 2560 x 2560; at 4x, it is 1280 x 1280
Nocreate_valueintCreativity value in the range 0 to 100. If omitted, the default configured for the adaptive style is used
Nohdr_valueintHDR enhancement value in the range 0 to 100. If omitted, the default configured for the adaptive style is used
Noresemblance_valueintResemblance value in the range 0 to 100. If omitted, the default configured for the adaptive style is used
Nosave_photo_formatintDefault: 1, for JPG encoding. 2 selects PNG encoding

Request Example

The following example preserves the algorithm parameter values from the source document. The source example passes -1 for create_value, hdr_value, and resemblance_value, while the parameter table declares a range of 0 to 100. For integration, follow the current adaptive style configuration and server-side validation rules. To use the default configuration, these three optional fields may also be omitted.

{
  "task": "/v1/Ultra_High_Definition/466657",
  "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_num\":2,\"style_id\":26,\"create_value\":-1,\"hdr_value\":-1,\"resemblance_value\":-1}}",
  "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 or error message
tipsanyAdditional information; may be null
dataobjectTask status and algorithm result

data field structure

FieldTypeDescription
statusintStatus code: -1 task not found; 0 task created; 1 processing; 2 failed; 9 requires a query through the status API; 10 succeeded
msgstringTask status description
resultobjectAlgorithm result
progressnumberTask progress, for example 0.1, 0.85, or 1
predict_elapsedintEstimated time in milliseconds
create_timeint64Creation timestamp in milliseconds
task_idstringTask ID
custom_task_idstringClient-defined task ID
trace_idstringTrace identifier
client_infostringClient information
init_imagesobject[]/nullEchoed input media

result field structure

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 JPG base64 data
parameterobjectAlgorithm result media-type indicator. The source document defines its rsp_media_type field
media_info_listobject[]Algorithm media result list. Each item contains image data and its corresponding information

parameter response fields

FieldTypeDescription
rsp_media_typestringResult media type. url means media_data is an image URL; jpg means media_data is JPG base64 data

Fields in each media_info_list item

FieldTypeDescription
media_datastringResult image URL or base64-encoded media file data, depending on rsp_media_type
media_profilesobjectMedia file attribute information

media_profiles response fields

FieldTypeDescription
media_data_typestringResult media data type. url means a URL; jpg means JPG base64 data

When a task fails, result may also contain the following fields defined in the source document:

FieldTypeDescription
ErrorCodeintError code
ErrorMsgstringError message
Datastring/nullDetailed information

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",
      "urls": [
        "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 Response (status=9)

When data.status is 9, retrieve the result from the status API using the returned task ID.

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_FACEFace missing
20004MORE_THAN_ONE_FACEMore than one face detected
20007MISSING_LANDMARK_ARGUMENTSFacial landmarks 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 requirement not met
20012UNSUITABLE_HORIZONTAL_IMAGEHorizontal width requirement not met
20013RESOLUTION_TOO_LARGE_ERRORResolution too large
20014NOT_FOUNDImage not found
20015PICTURE_OVERRUN_ERRORImage limit exceeded
20020DETECT_FACE_OUTOFIMAGEFacial features missing
20021DETECT_FACE_PITCHANGLE_BIGNon-frontal face; pitch angle too large
20022DETECT_FACE_YAWANGLE_BIGNon-frontal face; yaw or rotation angle too large
20023DETECT_FACE_LOWAREAFace occupies too little of the image or has too few pixels
21001LOAD_MODEL_ERRORModel loading failed
21002HAIR_MASK_LOSSHair mask missing
21003FACE_NUM_ERRORInvalid number of faces
21004AR_PARSE_FAULTFailed to parse the plist in AR
21005AR_EEEOR_COUNTAR face error
21006AR_FACE_OUTAR exceeds the face range
21007JSON_ERRORInvalid JSON content
21008BACKGROUND_IMAGE_LOSSBackground image missing
21009BODY_MASK_LOSSBody mask missing
21010FACE_ANGLE_ERRORInvalid face angle
21011SKIN_MASK_LOSSSkin mask missing
21012BODY_INFO_LOSSSkeletal points or outer contour points missing
21013RECT_OUT_IMAGERectangle exceeds the image bounds
30001GEN_ERRORGeneration error

General Error Codes and Messages

See API Error Codes.

SDK Examples

Each example signs the complete final JSON body that is sent. The body has only five top-level fields: task, task_type, init_images, params, and sync_timeout.

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": {
            "style_id": 26,
            "sr_num": 2,
        },
    }
    payload = {
        "task": "/v1/Ultra_High_Definition/466657",
        "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)

    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/Ultra_High_Definition/466657",
  "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\":{\"style_id\":26,\"sr_num\":2}}",
  "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' => [
        'style_id' => 26,
        'sr_num' => 2,
    ],
]);
$body = json_encode([
    'task' => '/v1/Ultra_High_Definition/466657',
    '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);
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/Ultra_High_Definition/466657\",\n" +
                "  \"task_type\": \"formula\",\n" +
                "  \"init_images\": [{\n" +
                "    \"url\": \"https://example.com/input.jpg\",\n" +
                "    \"profile\": {\n" +
                "      \"media_profiles\": {\"media_data_type\": \"url\"},\n" +
                "      \"version\": \"v1\"\n" +
                "    }\n" +
                "  }],\n" +
                "  \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"style_id\\\":26,\\\"sr_num\\\":2}}\",\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);
        }
    }
}