HomeDocsConsolePricing

Intelligent Background Removal- Overseas

Description

This API performs cloud-based saliency detection and background removal, automatically separating foreground subjects from images. For better processing speed and results, keeping the original image within 3 MB is recommended.

Version

1.0

Image Requirements

  • Image formats: JPG, PNG
  • Image size: No larger than 3 MB

API URL

    Production environment: https://openapi.meitu.com
    Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
    Task name (task): /v1/photo_scissors_oversea/8000555
    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

RequiredParameterTypeDescription
YesparamsstringAlgorithm parameters (JSON string)
Yesinit_imagesobject[]Image list
YestaskstringFixed value: /v1/photo_scissors_oversea/8000555
Yestask_typestringFixed value: formula
Nosync_timeoutintDefault: 30. Synchronous timeout duration

Structure of each multimedia file in init_images:

RequiredParameterTypeDescription
YesurlstringImage URL or Base64-encoded data
YesprofileobjectImage attribute information

Structure of profile:

RequiredParameterTypeDescription
Yesmedia_profilesobjectMedia attribute information
YesversionstringFixed value: v1

Structure of media_profiles:

RequiredParameterTypeDescription
Yesmedia_data_typestringurl indicates a URL; jpg indicates Base64-encoded image data

The params inference parameter is a JSON string with the following structure:

RequiredFieldTypeDescription
Norsp_media_typestringDefault: url, which returns the background-removal result as a temporary URL; jpg indicates Base64 data
YesparameterobjectCore algorithm parameter object

Details of the algorithm parameters in parameter:

RequiredParameterTypeDescription
NonMaskboolWhether to return a mask image; true returns only the mask image, while false returns the result image
Nomodel_typeintBackground-removal model type: 0 for portraits, 1 for products, and 2 for graphics; when omitted, the model selects the type automatically
NouserboxesstringAdds user interaction boxes to the image using relative coordinates; example: [[[0.01, 0.814], [0.12, 0.814], [0.12, 0.96], [0.01, 0.96]]]
NoblackwhiteboolWhether to return a black-and-white image; true returns only a black-and-white mask, while false returns a four-channel mask image (default)
NonboxboolWhether to return the target position fields top_x, top_y, bottom_x, and bottom_y; default: false

Request Example

{
  "task": "/v1/photo_scissors_oversea/8000555",
  "task_type": "formula",
  "init_images": [
    {
      "url": "https://my-material.obs.cn-north-4.myhuaweicloud.com/material-pre/m7eha8y5-rgrrak1.jpg",
      "profile": {
        "media_profiles": {
          "media_data_type": "url"
        },
        "version": "v1"
      }
    }
  ],
  "params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"nMask\":false,\"model_type\":0,\"userboxes\":\"[[[0.01, 0.814], [0.12, 0.814], [0.12, 0.96], [0.01, 0.96]]]\",\"blackwhite\":false,\"nbox\":false}}",
  "sync_timeout": 30
}

Response Fields

Note: Generated results are periodically deleted. Download and save them promptly.
FieldTypeDescription
request_idstringRequest identifier
trace_idstringTrace identifier
codeintBusiness status code; 0 indicates that the request was accepted successfully
error_codeintError code; 0 indicates success
messagestringBusiness message
tipsanyAdditional information; may be null
dataobjectTask status and algorithm result

Fields in data:

FieldTypeDescription
statusintStatus code: -1 task not found; 0 created; 1 processing; 2 failed; 9 timed out—use the Query API; 10 succeeded
resultobjectAlgorithm result
progressnumberTask progress
predict_elapsedintEstimated processing 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

Fields in result:

FieldTypeDescription
idstringTask ID
urlsstring[]List of background-removal result image URLs
parametersobjectAdditional returned parameters

Fields in parameters:

FieldTypeDescription
bottom_xstringX coordinate of the bottom-right corner
bottom_ystringY coordinate of the bottom-right corner
exist_salientboolWhether a salient object exists
KindintBackground-removal type: 0 for portrait, 1 for product, and 2 for graphic
process_timenumberAlgorithm processing time
pull_timenumberInput retrieval time
rsp_media_typestringReturned media type; jpg indicates that media_data contains a Base64-encoded image
top_xstringX coordinate of the top-left corner
top_ystringY coordinate of the top-left corner
use_feboolWhether foreground estimation was used
versionstringAlgorithm version

Response Examples

Successful Response Example

{
  "request_id": "",
  "trace_id": "",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "tips": null,
  "data": {
    "status": 10,
    "result": {
      "id": "task_id",
      "urls": [
        "https://example.com/output.png"
      ],
      "parameters": {
        "Kind": 0,
        "bottom_x": "None",
        "bottom_y": "None",
        "exist_salient": true,
        "process_time": 2596.703290939331,
        "pull_time": 933.626651763916,
        "rsp_media_type": "url",
        "top_x": "None",
        "top_y": "None",
        "use_fe": true,
        "version": "2.9.4"
      }
    },
    "progress": 1,
    "predict_elapsed": 30000,
    "create_time": 1762337530390,
    "task_id": "task_id",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

Response Example Requiring a Query

Use the Query API to retrieve the result.

Response Status: 200

Content-Type: application/json; charset=utf-8

{
  "request_id": "",
  "trace_id": "",
  "code": 0,
  "error_code": 0,
  "message": "sync timeout",
  "tips": null,
  "data": {
    "status": 9,
    "result": {},
    "progress": 0.5,
    "predict_elapsed": 30000,
    "create_time": 1762337530390,
    "task_id": "task_id",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

Failed Response Example

Response Status: 400

Content-Type: application/json; charset=utf-8

{
  "request_id": "",
  "trace_id": "",
  "code": 20001,
  "error_code": 20001,
  "message": "PROCESS_ERROR",
  "tips": null,
  "data": {
    "status": 2,
    "result": {
      "error_code": 20001,
      "error_msg": "PROCESS_ERROR"
    },
    "progress": 0,
    "predict_elapsed": 0,
    "create_time": 1762337530390,
    "task_id": "task_id",
    "custom_task_id": "",
    "trace_id": "",
    "client_info": "",
    "init_images": null
  }
}

General Error Codes and Messages

API-specific error:

Error CodeError MessageDescription
20001PROCESS_ERRORProcessing error

For other errors, see API Error Codes.

SDK Examples

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": {
            "nMask": False,
            "model_type": 0,
            "userboxes": "[[[0.01, 0.814], [0.12, 0.814], [0.12, 0.96], [0.01, 0.96]]]",
            "blackwhite": False,
            "nbox": False,
        },
    }
    payload = {
        "task": "/v1/photo_scissors_oversea/8000555",
        "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/photo_scissors_oversea/8000555",
  "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\":{\"nMask\":false,\"model_type\":0,\"userboxes\":\"[[[0.01, 0.814], [0.12, 0.814], [0.12, 0.96], [0.01, 0.96]]]\",\"blackwhite\":false,\"nbox\":false}}",
  "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' => [
        'nMask' => false,
        'model_type' => 0,
        'userboxes' => '[[[0.01, 0.814], [0.12, 0.814], [0.12, 0.96], [0.01, 0.96]]]',
        'blackwhite' => false,
        'nbox' => false,
    ],
]);

$body = json_encode([
    'task' => '/v1/photo_scissors_oversea/8000555',
    '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/photo_scissors_oversea/8000555\",\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\\\":{\\\"nMask\\\":false,\\\"model_type\\\":0,\\\"userboxes\\\":\\\"[[[0.01, 0.814], [0.12, 0.814], [0.12, 0.96], [0.01, 0.96]]]\\\",\\\"blackwhite\\\":false,\\\"nbox\\\":false}}\",\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);
        }
    }
}