描述

本接口用于云端进行显著性检测的请求，能够自动识别图像中的显著性目标区域。支持人像、商品、图形三种类型的显著性检测，并可返回检测结果图或 mask 图，支持边缘细节优化等高级功能。

版本

1.0

图片要求

图片格式JPG、PNG、HEIC
图片像素尺寸最小 224×224 像素，最大 3000×3000 像素
图片文件大小建议控制在3M 内

调用 URL

    正式环境：https://openapi.meitu.com
    任务提交接口：https://openapi.meitu.com/api/v1/sdk/sync/push
    任务名称(task)：/v1/photo_scissors/sod
    任务类型(task_type)：mtlab

调用方法

POST

Content-Type: application/json

权限

开放平台接口签名

请求参数

是否必选	参数名	类型	参数说明
必选	params	string	算法参数（JSON 字符串）
必选	init_images	object[]	多媒体文件列表
必选	task	string	固定 `/v1/photo_scissors/sod`
必选	task_type	string	固定 `mtlab`
可选	sync_timeout	int	默认 30，同步超时时间

init_images 多媒体文件参数，结构说明如下

是否必选	参数名	类型	参数说明
必选	url	string	多媒体的 url 地址，或者 base64
必选	profile	object	属性信息描述

profile 属性信息描述

是否必选	参数名	类型	参数说明
必选	media_profiles	object	媒体属性信息
必选	version	string	版本信息，固定 v1

media_profiles 媒体属性信息

是否必选	参数名	类型	参数说明
必选	media_data_type	string	媒体数据类型，"url": 表示 url，"jpg": 表示 base64

params 推理参数是 JSON 字符串，其结构说明如下

是否必选	字段	类型	说明
可选	rsp_media_type	string	默认 `url`；`jpg` 表示 base64
必选	parameter	object	算法核心参数对象

parameter 算法参数详情

是否必选	参数名	类型	说明
可选	nMask	bool	是否返回 mask 图，True 只返回 mask 图，False 返回结果图
可选	model_type	int	选择要使用的抠图模型 0：人像抠图 1：商品抠图 2：图形抠图若不传，模型内部会自动判断选择使用哪个模型
可选	userboxes	string	图标类型可以添加用户交互框参数，坐标应当使用相对坐标，务必按照左上角开始顺时针的顺序传入四个点的坐标（即左上、右上、右下、左下）。示例：`[[[0.01, 0.814], [0.12, 0.814], [0.12, 0.96], [0.01, 0.96]]]`
可选	blackwhite	bool	是否返回黑白图，True 只返回黑白 mask 图，False 返回四通道 Mask 图，默认为 False
可选	nbox	bool	是否返回目标位置，True 返回目标位置 top_x, top_y, bottom_x, bottom_y，默认为 False
可选	post_matting	bool	仅针对商品类别，是否使用边缘后处理算法，默认为 False。若设置为 True，会得到更精细的边缘细节，但是耗时会增加 0.2s~1s
可选	use_fe_rgba	bool	控制是否使用前景估计，默认为 False。如果图像抠图结果边缘存在白边或黑边等问题，则设置为 True，使用前景估计

输入值示例

{
  "task": "/v1/photo_scissors/sod",
  "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\":{\"nMask\":false,\"model_type\":0}}",
  "sync_timeout": 30
}

返回值说明

注意，生成的结果，会定期清理，请及时下载保存

字段	类型	说明
request_id	string	请求标识
trace_id	string	链路追踪标识
code	int	业务状态码，`0` 表示请求受理成功
error_code	int	错误码，成功时为 `0`
message	string	业务信息
tips	any	补充提示，可为 null
data	object	任务状态和算法结果

data 中单个元素的字段说明

字段	类型	说明
status	int	状态码：-1 未找到任务；0 创建成功；1 执行中；2 失败；9 超时，使用查询接口查询；10 成功
result	object	算法结果
progress	number	任务进度
predict_elapsed	int	预计耗时，毫秒
create_time	int64	创建时间戳，毫秒
task_id	string	任务 ID
custom_task_id	string	客户自定义任务 ID
trace_id	string	链路追踪标识
client_info	string	客户端信息
init_images	object[]/null	输入媒体回显

result 中单个元素的字段说明

字段	类型	说明
parameter	object	算法参数信息
media_info_list	array	媒体文件列表
msg	string	状态消息
msg_id	string	消息ID
code	int	算法状态码
error_code	int	错误代码
error_msg	string	错误信息
data	object	算法返回数据

返回值示例

请求成功返回示例

Response Status：200

content-type 为 application/json; charset=utf-8

{
  "request_id": "req_123456789",
  "trace_id": "trace_987654321",
  "code": 0,
  "error_code": 0,
  "message": "success",
  "tips": null,
  "data": {
    "status": 10,
    "result": {
      "parameter": {
        "version": "1.0",
        "exist_salient": true,
        "Kind": 0
      },
      "media_info_list": [
        {
          "media_data": "https://example.com/result.jpg",
          "media_profiles": {
            "media_data_type": "url"
          }
        }
      ],
      "msg": "success",
      "msg_id": "msg_123456",
      "code": 0,
      "error_code": 0,
      "error_msg": ""
    },
    "progress": 100,
    "predict_elapsed": 5000,
    "create_time": 1640995200000,
    "task_id": "task_1234567890",
    "custom_task_id": "",
    "trace_id": "trace_987654321",
    "client_info": "",
    "init_images": null
  }
}

需要查询返回示例

使用查询接口接口查询

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
  }
}

请求失败返回示例

Response Status：400

content-type 为 application/json; charset=utf-8

{
  "request_id": "req_error_123456",
  "trace_id": "trace_error_789012",
  "code": 20003,
  "error_code": 20003,
  "message": "ALGO_ERROR",
  "tips": null,
  "data": {
    "status": 2,
    "result": {
      "id": "t_mt1a3i5n7be8d575cc-2ffb-4e0c-85a8-1824110e31b8",
      "code": 20003,
      "data": {
        "duration": {
          "alg_process_time": 0,
          "created_timestamp": 1759201989,
          "pull_timestamp": 1759201989,
          "repost_time": 0,
          "upload_time": 0,
          "waiting_time": 0
        },
        "error_code": 20003,
        "error_msg": "DETECT_NOT_FACE",
        "extra": {},
        "media_info_list": [],
        "msg_id": "c1b09cb2-6e05-4d21-55ab-r007b1f21bec",
        "parameter": null
      },
      "msg": "DETECT_NOT_FACE",
      "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
  }
}

通用的错误代码与信息

详见 API 错误码

SDK 调用示例

Python

import requests
import json
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,
        },
    }
    payload_dict = {
        "task": "/v1/photo_scissors/sod",
        "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_dict, 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__":
    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/photo_scissors/sod",
    "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\":{\"nMask\":false,\"model_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'
];

$innerParams = json_encode([
  "rsp_media_type" => "url",
  "parameter" => [
    "nMask" => false,
    "model_type" => 0
  ]
]);

$body = json_encode([
  "task" => "/v1/photo_scissors/sod",
  "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;
}
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/photo_scissors/sod\",\n" +
                "  \"task_type\": \"mtlab\",\n" +
                "  \"init_images\": [\n" +
                "    {\n" +
                "      \"url\": \"https://example.com/image.jpg\",\n" +
                "      \"profile\": {\n" +
                "        \"media_profiles\": {\n" +
                "          \"media_data_type\": \"url\"\n" +
                "        },\n" +
                "        \"version\": \"v1\"\n" +
                "      }\n" +
                "    }\n" +
                "  ],\n" +
                "  \"params\": \"{\\\"rsp_media_type\\\":\\\"url\\\",\\\"parameter\\\":{\\\"nMask\\\":false,\\\"model_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);
            if (body!=null){
                connection.getOutputStream().write(body.getBytes(StandardCharsets.UTF_8));
            }
            int status = connection.getResponseCode();
            System.out.println(status);

            InputStream inputStream;
            if (status >= 400) {
                inputStream = connection.getErrorStream();
            } else {
                inputStream = 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();
        }
    }
}

智能抠图

描述

版本

图片要求

调用 URL

调用方法

权限

请求参数

输入值示例

返回值说明

返回值示例

请求成功返回示例

需要查询返回示例

请求失败返回示例

通用的错误代码与信息

SDK 调用示例

Python

Go

PHP

Java