智能抠图 V2
描述
自动识别图片中的显著性主体,返回抠图结果或蒙版。适用于人像、商品、图标和印章等主体。图片中存在多个显著性相近的对象时,自动选择的主体可能与预期不同。
版本
1.8.1
图片要求
每次传一张图片。URL 须能被服务访问。支持 jpg、jpeg、png、bmp、webp、jfif、heic、avif 的 Base64 编码输入;使用 Base64 时,将媒体类型设为对应格式。以下示例使用 URL。
调用 URL
正式环境:https://openapi.meitu.com
任务提交接口:https://openapi.meitu.com/api/v1/sdk/sync/push
任务名称(task):/v1/Background_Removal_V2/497073
任务类型(task_type):formula调用方法
POST
Content-Type: application/json
权限
使用 AK/SK 签名。
请求参数
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| 是 | params | string | 算法参数(JSON 字符串)。 |
| 是 | init_images | object[] | 图片列表,传一项。 |
| 是 | task | string | /v1/Background_Removal_V2/497073 |
| 是 | task_type | string | formula |
init_images
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| 是 | url | string | 输入图片 URL;使用 Base64 时填写编码后的图片数据。 |
| — | profile | object | 示例中用于指定媒体类型。 |
profile
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| — | media_profiles | object | 媒体属性。 |
| — | version | string | 示例值:v1。 |
media_profiles
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| — | media_data_type | string | url 表示图片 URL;Base64 输入填写对应格式。 |
params
算法参数以 JSON 字符串传入,解码后的字段如下。
| 是否必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| 是 | parameter | object | 算法参数对象。 |
parameter
| 是否必选 | 参数名 | 类型 | 默认值 | 参数说明 |
|---|---|---|---|---|
| 否 | nMask | boolean | false | true:仅返回蒙版;false:返回带 Alpha 通道的抠图结果。 |
| 否 | blackwhite | boolean | false | 仅 nMask=true 时生效。true 返回灰度 JPG 蒙版;false 返回带 Alpha 通道的 PNG 蒙版。 |
| 否 | nbox | boolean | false | 开启时返回显著性目标的像素坐标 top_x、top_y、bottom_x、bottom_y。 |
| 否 | wbg | boolean | false | 开启时将抠图结果合成到白色背景上,输出 JPG。 |
| 否 | inv_res | boolean | false | 是否反转蒙版,仅在 nMask=true 时生效。 |
| 否 | use_fe_rgba | boolean | false | 开启时,人像和商品类别可额外返回 RGBA PNG 前景估计图;图标或印章类别默认返回前景估计图。 |
| 否 | keep_resolution | boolean | true | 输入长边超过 2496 像素时,true 将结果上采样到原分辨率;false 返回长边为 2496 像素的缩放结果。 |
| 否 | userboxes | string | null | 仅图标类别支持。传入编码成 JSON 字符串的三维坐标数组,坐标范围为 0~1。四点顺序为左上、右上、右下、左下。 |
| 否 | post_matting | boolean | true | 仅商品类别生效。开启边缘后处理可得到更精细的边缘,额外耗时约 0.2~1 秒。 |
| 否 | model_type | integer | null | 指定模型:0 人像、1 商品、2 图标或印章。省略时自动判断。 |
输入值示例
返回带透明通道的主抠图结果,并请求目标边界框。
{
"task": "/v1/Background_Removal_V2/497073",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"nMask\":false,\"nbox\":true}}"
}返回值说明
如果提交返回待查询状态,使用网关的 data.task_id 通过 任务查询 获取结果,不使用算法的 msg_id。
算法结果字段
| 字段 | 说明 |
|---|---|
media_info_list[0].media_data | 主结果。按实际响应媒体类型返回图片 URL 或 Base64。 |
media_info_list[1].media_data | 额外的前景估计图,仅在 parameter.return_fe=true 时存在。 |
parameter.exist_salient | 是否检测到显著性目标。 |
parameter.Kind | 检测到的类别:0 人像、1 商品、2 图标或印章。 |
parameter.rsp_media_type | 实际响应媒体类型。 |
parameter.return_fe | 是否返回第二张前景估计图。 |
parameter.use_fe_rgba | 是否启用了人像或商品的 RGBA 前景估计模式。 |
parameter.top_x / top_y / bottom_x / bottom_y | 目标边界框的左上角和右下角像素坐标,仅在 nbox=true 时返回有效值。 |
parameter.seal_bbox | 印章边界框坐标列表,其他类别为空列表。 |
parameter.version / pull_time / process_time | 算法版本、输入图片下载耗时及处理耗时;耗时单位为毫秒。 |
parameter.use_fe | 已废弃,仅用于兼容。 |
通用的错误代码与信息
网关错误见 API 错误码。
SDK 调用示例
使用前填写 AK/SK 和图片 URL。
Python
import requests
from sign_sdk import sign
url = "https://openapi.meitu.com/api/v1/sdk/sync/push"
body = r'''{
"task": "/v1/Background_Removal_V2/497073",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"nMask\":false,\"nbox\":true}}"
}'''
headers = {"Content-Type": "application/json", sign.HeaderHost: "openapi.meitu.com"}
signer = sign.Signer("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")
request = signer.sign(url, "POST", headers, body)
with requests.Session() as session:
response = session.send(request, timeout=(10, 60), allow_redirects=False)
print(response.status_code, response.text)Go
package main
import (
"fmt"
"io"
"log"
"net/http"
"time"
"github.com/mtlab/api/signer"
)
func main() {
url := "https://openapi.meitu.com/api/v1/sdk/sync/push"
body := `{
"task": "/v1/Background_Removal_V2/497073",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"nMask\":false,\"nbox\":true}}"
}`
headers := make(http.Header)
headers.Set(signer.HeaderHost, "openapi.meitu.com")
headers.Set("Content-Type", "application/json")
s := signer.NewSigner("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY")
req, err := s.Sign(url, http.MethodPost, headers, body)
if err != nil {
log.Fatal(err)
}
client := &http.Client{
Timeout: 60 * time.Second,
CheckRedirect: func(*http.Request, []*http.Request) error {
return http.ErrUseLastResponse
},
}
res, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
result, err := io.ReadAll(res.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(res.StatusCode, string(result))
}PHP
<?php
require_once __DIR__ . '/signer.php';
$url = 'https://openapi.meitu.com/api/v1/sdk/sync/push';
$body = <<<'JSON'
{
"task": "/v1/Background_Removal_V2/497073",
"task_type": "formula",
"init_images": [
{
"url": "https://example.com/input.jpg",
"profile": {
"media_profiles": {
"media_data_type": "url"
},
"version": "v1"
}
}
],
"params": "{\"parameter\":{\"nMask\":false,\"nbox\":true}}"
}
JSON;
$headers = ['Host' => 'openapi.meitu.com', 'Content-Type' => 'application/json'];
$signer = new Signer('YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY');
$curl = $signer->sign($url, 'POST', $headers, $body);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => false,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 60,
]);
$result = curl_exec($curl);
if ($result === false) {
$error = curl_error($curl);
curl_close($curl);
throw new RuntimeException($error);
}
echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $result, PHP_EOL;
curl_close($curl);Java
package com.meitu.openai.common;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) throws Exception {
String url = "https://openapi.meitu.com/api/v1/sdk/sync/push";
String body = "{\n" +
" \"task\": \"/v1/Background_Removal_V2/497073\",\n" +
" \"task_type\": \"formula\",\n" +
" \"init_images\": [\n" +
" {\n" +
" \"url\": \"https://example.com/input.jpg\",\n" +
" \"profile\": {\n" +
" \"media_profiles\": {\n" +
" \"media_data_type\": \"url\"\n" +
" },\n" +
" \"version\": \"v1\"\n" +
" }\n" +
" }\n" +
" ],\n" +
" \"params\": \"{\\\"parameter\\\":{\\\"nMask\\\":false,\\\"nbox\\\":true}}\"\n" +
"}";
Map<String, String> headers = new HashMap<>();
headers.put("Content-Type", "application/json");
headers.put(Signer.HeaderHost, "openapi.meitu.com");
Signer signer = new Signer("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY");
Map<String, String> signed = signer.sign(url, "POST", headers, body);
HttpURLConnection connection = (HttpURLConnection) URI.create(url).toURL().openConnection();
try {
connection.setRequestMethod("POST");
connection.setConnectTimeout(10000);
connection.setReadTimeout(60000);
connection.setInstanceFollowRedirects(false);
signed.forEach(connection::setRequestProperty);
connection.setDoOutput(true);
try (OutputStream out = connection.getOutputStream()) {
out.write(body.getBytes(StandardCharsets.UTF_8));
}
int status = connection.getResponseCode();
try (InputStream in = status >= 400 ? connection.getErrorStream() : connection.getInputStream()) {
String result = in == null ? "" : new String(in.readAllBytes(), StandardCharsets.UTF_8);
System.out.println(status + " " + result);
}
} finally {
connection.disconnect();
}
}
}