Object Removal

Description

This API processes passerby removal requests in the cloud. It uses AI algorithms to automatically identify and remove passersby from images, restoring a clean background.

Version

1.0

Image Requirements

Image formats: JPG, PNG

API URL

    Production environment: https://openapi.meitu.com
    Task submission endpoint: https://openapi.meitu.com/api/v1/sdk/sync/push
    Task name (task): /v1/Passersby_Elimination/453194
    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[]List of multimedia files
YestaskstringFixed value: /v1/Passersby_Elimination/453194
Yestask_typestringFixed value: formula
Nosync_timeoutintDefault: 30. Synchronous timeout in seconds; -1 means do not wait. If the API times out, status is 9; use the Query API to retrieve the result.

Structure of an init_images multimedia file item:

RequiredParameterTypeDescription
YesurlstringMultimedia URL or base64-encoded data
YesprofileobjectAttribute information

Structure of profile:

RequiredParameterTypeDescription
Yesmedia_profilesobjectMedia attribute information
Nomedia_extraobjectAdditional multimedia parameters
YesversionstringFixed value: v1

Structure of media_profiles:

RequiredParameterTypeDescription
Yesmedia_data_typestringurl indicates a URL; jpg indicates base64-encoded data

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

RequiredFieldTypeDescription
Norsp_media_typestringDefault: url; jpg indicates base64-encoded data
YesparameterobjectCore algorithm parameter object

Details of the algorithm parameters in parameter:

RequiredParameterTypeDescription
Noexpand_paramsstringAI removal parameters as a JSON string containing a parameter object; default: {"parameter":{"generate_num":1}}
Noresult_typestring0: return only the result image; 1: return both the mask and result images; default: 0

Details of the algorithm parameters in the decoded parameter object of expand_params:

RequiredParameterTypeDescription
Nogenerate_numintNumber of images to return; default: 4
NoseedintRandom seed in the range [-1, 65535]. -1 uses a random seed and produces a different result each time. If omitted, the default is 0; a fixed seed produces the same result each time. Callers are advised to generate a random value externally and pass it in so that problematic cases can be reproduced.
NoschedulerstringSampler type. Options: DDIM / DEIS-M / KDPM-2D / KDPM-2AD / Euler-AD / Euler-D / Heun-D / LMS-D / DPM-SM / PNDM / DPM-SS / UniPC-M. Default: DDIM
NostepintNumber of sampling steps; default: 25; range: 1–1000
Noexpand_ratiofloatParameter used by earlier removal algorithms to avoid black borders. Set it to 0 to avoid black borders (applicable to version 1.0.33 and earlier; it is not required in later versions). The value must not be negative.
Noauto_adjust_mask_edgeboolWhether to adaptively adjust the edges of the input mask before removal. Enabling this is recommended when the mask is generated by a segmentation algorithm or when there are obvious shadows around the subject. Default: true
Noreturn_modified_maskboolWhether to return the mask actually used for removal. When enabled, the API returns both RGB result images and single-channel mask images, for a total of generate_num×2 images. The mask image's media_profiles includes an additional is_mask=True flag. Default: false
Nohigh_quality_encodeboolWhether to encode result images using high-quality, low-compression settings. Image content is unchanged and quality is improved, but API processing time increases. Default: false

Request Example

{
  "task": "/v1/Passersby_Elimination/453194",
  "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\":{\"expand_params\":\"{\\\"parameter\\\":{\\\"step\\\":25,\\\"generate_num\\\":1,\\\"seed\\\":-1}}\",\"result_type\":\"0\"}}",
  "sync_timeout": 30
}

Response Fields

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 on success
messagestringBusiness message
tipsanyAdditional information; may be null
dataobjectTask status and algorithm result

Fields in the data object:

FieldTypeDescription
statusintStatus code: -1, task not found; 0, created successfully; 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 within data
client_infostringClient information
init_imagesobject[]/nullEcho of the input media

Fields in the result object:

FieldTypeDescription
idstringTask ID
urlsstring[]List of result image URLs. When result_type=1, both result images and mask images are returned, for a total of generate_num×2 images.

Response Examples

Successful Response Example

Response Status: 200

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

{
    "request_id": "req_abc123",
    "trace_id": "trace_abc123",
    "code": 0,
    "error_code": 0,
    "message": "success",
    "tips": null,
    "data": {
        "status": 10,
        "result": {
            "id": "t_mt1a3i5n7b7e45698e-7212-4bae-ac7e-9766498c71a5",
            "urls": [
                "https://obs-large.mtlab.meitu.com/mtopen/23e48d1b186e4d75b5769628d98e0496/MTcxODE3MjAwMA==/d4772377-35b3-474b-53b9-674f992d53b0.jpeg"
            ]
        },
        "progress": 1,
        "predict_elapsed": 3500,
        "create_time": 1759202368761,
        "task_id": "t_mt1a3i5n7b7e45698e-7212-4bae-ac7e-9766498c71a5",
        "custom_task_id": "",
        "trace_id": "9129a3a2-99c4-46ce-8731-0e100e2fbee7",
        "client_info": "",
        "init_images": null
    }
}

Pending Response Example

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": "success",
    "tips": null,
    "data": {
        "status": 9,
        "result": {
            "id": "t_mt1a3i5n7b3da6d589-46b5-4f66-a0bb-8dd22f2a172e"
        },
        "progress": 0,
        "predict_elapsed": 10000,
        "create_time": 1759202368761,
        "task_id": "t_mt1a3i5n7b3da6d589-46b5-4f66-a0bb-8dd22f2a172e",
        "custom_task_id": "",
        "trace_id": "9129a3a2-99c4-46ce-8731-0e100e2fbee7",
        "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": "ALGO_MODEL_CRASH",
    "tips": null,
    "data": {
        "status": 2,
        "result": {
            "id": "t_mt1a3i5n7be8d575cc-2ffb-4e0c-85a8-1824110e31b8",
            "code": 20001,
            "data": {
                "duration": {
                    "alg_process_time": 0,
                    "created_timestamp": 1759201989,
                    "pull_timestamp": 1759201989,
                    "repost_time": 0,
                    "upload_time": 0,
                    "waiting_time": 0
                },
                "error_code": 20001,
                "error_msg": "ALGO_MODEL_CRASH",
                "extra": {},
                "media_info_list": [],
                "msg_id": "c1b09cb2-6e05-4d21-55ab-r007b1f21bec",
                "parameter": null
            },
            "msg": "ALGO_MODEL_CRASH",
            "msg_id": "c1b09cb2-6e05-4d21-55ab-r007b1f21bec"
        },
        "progress": 1,
        "predict_elapsed": 10000,
        "create_time": 1759201989444,
        "task_id": "t_mt1a3i5n7be8d575cc-2ffb-4e0c-85a8-1824110e31b8",
        "custom_task_id": "",
        "trace_id": "",
        "client_info": "",
        "init_images": null
    }
}

General Error Codes and Messages

See API Error Codes.

SDK Examples

Python

import requests
import json
from sign_sdk import sign

def passerby_removal_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": {
            "expand_params": json.dumps({
                "parameter": {
                    "generate_num": 1,
                    "step": 25,
                    "seed": -1,
                }
            }, ensure_ascii=False),
            "result_type": "0",
        },
    }
    payload = {
        "task": "/v1/Passersby_Elimination/453194",
        "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)

    try:
        signer = sign.Signer(key, secret)
        signed_request = signer.sign(url, method, headers, body)

        session = requests.Session()
        response = session.send(signed_request)

        print(f"Status: {response.status_code}")
        print(f"Response: {response.text}")

    except Exception as e:
        print(f"Error: {str(e)}")

if __name__ == "__main__":
    passerby_removal_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 := "POST"

    headers := make(http.Header)
    headers.Set(signer.HeaderHost, "openapi.meitu.com")
    headers.Set("Content-Type", "application/json")

    body := `{
  "task": "/v1/Passersby_Elimination/453194",
  "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\":{\"expand_params\":\"{\\\"parameter\\\":{\\\"generate_num\\\":1,\\\"step\\\":25,\\\"seed\\\":-1}}\",\"result_type\":\"0\"}}",
  "sync_timeout": 30
}`

    req, err := signObj.Sign(url, method, headers, body)
    if err != nil {
        fmt.Println("Failed to sign request:", err)
        return
    }

    client := http.DefaultClient
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Failed to send request:", err)
        return
    }
    defer resp.Body.Close()

    bodyBytes, err := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Read response failed:", err)
        return
    }
    fmt.Println("Response:", resp.StatusCode, string(bodyBytes))
}

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'
];

$expandParams = json_encode([
    "parameter" => [
        "generate_num" => 1,
        "step" => 25,
        "seed" => -1
    ]
]);

$innerParams = json_encode([
    "rsp_media_type" => "url",
    "parameter" => [
        "expand_params" => $expandParams,
        "result_type" => "0"
    ]
]);

$body = json_encode([
    "task" => "/v1/Passersby_Elimination/453194",
    "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;
}
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.MalformedURLException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import com.meitu.openai.common.Signer;

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/Passersby_Elimination/453194\",\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\\\":{\\\"expand_params\\\":\\\"{\\\\\\\"parameter\\\\\\\":{\\\\\\\"generate_num\\\\\\\":1,\\\\\\\"step\\\\\\\":25,\\\\\\\"seed\\\\\\\":-1}}\\\",\\\"result_type\\\":\\\"0\\\"}}\",\n" +
                "  \"sync_timeout\": 30\n" +
                "}";

        Map<String, String> signedHeaders = signer.sign(url, method, headers, body);
        System.out.println("signedHeader: " + signedHeaders);

        try {
            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();
            System.out.println(status);

            InputStream inputStream = status >= 400
                    ? connection.getErrorStream()
                    : connection.getInputStream();

            BufferedReader in = new BufferedReader(new InputStreamReader(inputStream));
            String inputLine;
            StringBuilder response = new StringBuilder();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();
            System.out.println("======");
            System.out.println(response.toString());
            System.out.println("======");
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
    }
}