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

Request Parameters

Required	Parameter	Type	Description
Yes	params	string	Algorithm parameters (JSON string)
Yes	init_images	object[]	List of multimedia files
Yes	task	string	Fixed value: `/v1/Passersby_Elimination/453194`
Yes	task_type	string	Fixed value: `formula`
No	sync_timeout	int	Default: 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:

Required	Parameter	Type	Description
Yes	url	string	Multimedia URL or base64-encoded data
Yes	profile	object	Attribute information

Structure of profile:

Required	Parameter	Type	Description
Yes	media_profiles	object	Media attribute information
No	media_extra	object	Additional multimedia parameters
Yes	version	string	Fixed value: `v1`

Structure of media_profiles:

Required	Parameter	Type	Description
Yes	media_data_type	string	`url` indicates a URL; `jpg` indicates base64-encoded data

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

Required	Field	Type	Description
No	rsp_media_type	string	Default: `url`; `jpg` indicates base64-encoded data
Yes	parameter	object	Core algorithm parameter object

Details of the algorithm parameters in parameter:

Required	Parameter	Type	Description
No	expand_params	string	AI removal parameters as a JSON string containing a `parameter` object; default: `{"parameter":{"generate_num":1}}`
No	result_type	string	`0`: 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:

Required	Parameter	Type	Description
No	generate_num	int	Number of images to return; default: 4
No	seed	int	Random 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.
No	scheduler	string	Sampler 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
No	step	int	Number of sampling steps; default: 25; range: 1–1000
No	expand_ratio	float	Parameter 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.
No	auto_adjust_mask_edge	bool	Whether 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`
No	return_modified_mask	bool	Whether 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`
No	high_quality_encode	bool	Whether 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.

Field	Type	Description
request_id	string	Request identifier
trace_id	string	Trace identifier
code	int	Business status code; `0` indicates that the request was accepted successfully
error_code	int	Error code; `0` on success
message	string	Business message
tips	any	Additional information; may be null
data	object	Task status and algorithm result

Fields in the data object:

Field	Type	Description
status	int	Status code: `-1`, task not found; `0`, created successfully; `1`, processing; `2`, failed; `9`, timed out—use the Query API; `10`, succeeded
result	object	Algorithm result
progress	number	Task progress
predict_elapsed	int	Estimated processing time in milliseconds
create_time	int64	Creation timestamp in milliseconds
task_id	string	Task ID
custom_task_id	string	Client-defined task ID
trace_id	string	Trace identifier within `data`
client_info	string	Client information
init_images	object[]/null	Echo of the input media

Fields in the result object:

Field	Type	Description
id	string	Task ID
urls	string[]	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();
        }
    }
}

Object Removal

Description

Version

Image Requirements

API URL

Method

Authentication

Request Parameters

Request Example

Response Fields

Response Examples

Successful Response Example

Pending Response Example

Failed Response Example

General Error Codes and Messages

SDK Examples

Python

Go

PHP

Java