Pedestrian Recognition
Description
This API identifies passersby in an image and can return a passerby mask, instance masks, and portrait bounding boxes. It intelligently distinguishes the main subject from background passersby, making it suitable for portrait photography, smart photo albums, and similar scenarios.
Version
1.0
Image Requirements
- Image formats: JPG, PNG
- Recommended image resolution: At least 512 x 512 pixels
- Image size: No more than 10 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/Passersby_Segment/483257
Task type (task_type): mtlabMethod
POST
Content-Type: application/json
Authentication
Request Parameters
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | params | string | Algorithm parameters (JSON string) |
| Yes | init_images | object[] | Media file list |
| Yes | task | string | Fixed value: /v1/Passersby_Segment/483257 |
| Yes | task_type | string | Fixed value: mtlab |
| No | sync_timeout | int | Default: 30; synchronous timeout duration |
The init_images media file parameters are described below.
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | url | string | Image URL or base64-encoded data |
| Yes | profile | object | Attribute information |
The profile attribute information is described below.
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | media_profiles | object | Media attributes |
| Yes | version | string | Fixed value: v1 |
The media_profiles media attributes are described below.
| Required | Parameter | Type | Description |
|---|---|---|---|
| Yes | media_data_type | string | url indicates a URL; jpg indicates base64-encoded data |
The params inference parameters are supplied as 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 |
The algorithm parameters in parameter are described below.
| Required | Parameter | Type | Description |
|---|---|---|---|
| No | production_line | string | ins: Returns portrait out_boxes and instance masks; urls[0] is the instance mask. passerby: Returns the passerby mask and portrait out_boxes; urls[0] is the passerby mask. ins_passerby: Returns the passerby mask, instance masks, and portrait out_boxes; urls[0] is the passerby mask and urls[1] is the instance mask. If omitted, the API returns out_boxes and instance masks by default, with urls[0] containing the instance mask. |
Request Example
{
"task": "/v1/Passersby_Segment/483257",
"task_type": "mtlab",
"init_images": [
{
"url": "https://example.com/image.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"production_line\":\"passerby\"}}",
"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 |
| error_code | int | Error code |
| message | string | Business message |
| tips | any | Additional information |
| data | object | Task status and algorithm result |
The fields in data are described below.
| 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 duration 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 |
| client_info | string | Client information |
| init_images | object[]/null | Echo of input media |
The fields in result are described below.
| Field | Type | Description |
|---|---|---|
| id | string | Task ID |
| urls | string[] | Image URL list; the order is determined by production_line |
| parameters | object | Returned metadata |
The fields in parameters are described below.
| Field | Type | Description |
|---|---|---|
| out_boxes | List | Portrait bounding-box coordinates in the format [x1, y1, x2, y2, label], where label is the bounding-box label |
| rsp_media_type | string | Returned media type: url or jpg |
| version | string | Algorithm version number |
| inpainting | int | Optional; 0 indicates that no passerby is present, and 1 indicates that a passerby is present. This field is not returned when production_line is set. |
| target_id | int | Optional; indicates which pixel values represent the main subject |
Response Examples
Successful Response Example
{
"request_id": "",
"trace_id": "",
"code": 0,
"error_code": 0,
"message": "success",
"tips": null,
"data": {
"status": 10,
"result": {
"id": "t_mt1a3i5n7b9de93110-f707-41a1-83d5-d69c60f3bbad",
"urls": [
"https://obs.mtlab.meitu.com/mtopen/rF5GIhp5ReLKgLV91CKj5BO1q2FTLMmc/MTY5Mjg1MzIwMA==/1c39ef92-04f1-40b4-5b7e-8fcfca0c11ea.png"
],
"parameters": {
"out_boxes": [
[1044, 1437, 1306, 2060, -1],
[2576, 1421, 2666, 1662, -1],
[1175, 1331, 1282, 1601, -1],
[393, 1286, 557, 1527, 1],
[2654, 1400, 2818, 1687, 2],
[1130, 1306, 1527, 2072, 3],
[1048, 1441, 1298, 1830, 4],
[1466, 1306, 1564, 1597, 5],
[1318, 634, 2674, 3366, 6],
[307, 1314, 417, 1531, 7],
[749, 1363, 1097, 2068, 8],
[1536, 1298, 1626, 1556, 9],
[2805, 1314, 3067, 2064, 10]
],
"rsp_media_type": "url",
"version": "1.0.9"
}
},
"progress": 1,
"predict_elapsed": 10000,
"create_time": 1759202368761,
"task_id": "t_mt1a3i5n7b9de93110-f707-41a1-83d5-d69c60f3bbad",
"custom_task_id": "",
"trace_id": "",
"client_info": "",
"init_images": null
}
}Pending Query 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 Information
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": {"production_line": "passerby"},
}
payload = {
"task": "/v1/Passersby_Segment/483257",
"task_type": "mtlab",
"init_images": [
{
"url": "https://example.com/image.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 := "POST"
headers := make(http.Header)
headers.Set(signer.HeaderHost, "openapi.meitu.com")
headers.Set("Content-Type", "application/json")
body := `{
"task": "/v1/Passersby_Segment/483257",
"task_type": "mtlab",
"init_images": [{
"url": "https://example.com/image.jpg",
"profile": {
"media_profiles": {"media_data_type": "url"},
"version": "v1"
}
}],
"params": "{\"rsp_media_type\":\"url\",\"parameter\":{\"production_line\":\"passerby\"}}",
"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()
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'];
$innerParams = json_encode([
'rsp_media_type' => 'url',
'parameter' => ['production_line' => 'passerby'],
]);
$body = json_encode([
'task' => '/v1/Passersby_Segment/483257',
'task_type' => 'mtlab',
'init_images' => [
[
'url' => 'https://example.com/image.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/Passersby_Segment/483257\",\n" +
" \"task_type\": \"mtlab\",\n" +
" \"init_images\": [{\n" +
" \"url\": \"https://example.com/image.jpg\",\n" +
" \"profile\": {\n" +
" \"media_profiles\": {\"media_data_type\": \"url\"},\n" +
" \"version\": \"v1\"\n" +
" }\n" +
" }],\n" +
" \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"production_line\\\":\\\"passerby\\\"}}\",\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))) {
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = reader.readLine()) != null) {
response.append(inputLine);
}
System.out.println("Response: " + status + " " + response);
}
}
}