智能抠图 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 签名。

请求参数

是否必选参数名类型参数说明
是paramsstring算法参数(JSON 字符串)。
是init_imagesobject[]图片列表,传一项。
是taskstring/v1/Background_Removal_V2/497073
是task_typestringformula

init_images

是否必选参数名类型参数说明
是urlstring输入图片 URL;使用 Base64 时填写编码后的图片数据。
—profileobject示例中用于指定媒体类型。

profile

是否必选参数名类型参数说明
—media_profilesobject媒体属性。
—versionstring示例值:v1。

media_profiles

是否必选参数名类型参数说明
—media_data_typestringurl 表示图片 URL;Base64 输入填写对应格式。

params

算法参数以 JSON 字符串传入,解码后的字段如下。

是否必选参数名类型参数说明
是parameterobject算法参数对象。

parameter

是否必选参数名类型默认值参数说明
否nMaskbooleanfalsetrue:仅返回蒙版;false:返回带 Alpha 通道的抠图结果。
否blackwhitebooleanfalse仅 nMask=true 时生效。true 返回灰度 JPG 蒙版;false 返回带 Alpha 通道的 PNG 蒙版。
否nboxbooleanfalse开启时返回显著性目标的像素坐标 top_x、top_y、bottom_x、bottom_y。
否wbgbooleanfalse开启时将抠图结果合成到白色背景上,输出 JPG。
否inv_resbooleanfalse是否反转蒙版,仅在 nMask=true 时生效。
否use_fe_rgbabooleanfalse开启时,人像和商品类别可额外返回 RGBA PNG 前景估计图;图标或印章类别默认返回前景估计图。
否keep_resolutionbooleantrue输入长边超过 2496 像素时,true 将结果上采样到原分辨率;false 返回长边为 2496 像素的缩放结果。
否userboxesstringnull仅图标类别支持。传入编码成 JSON 字符串的三维坐标数组,坐标范围为 0~1。四点顺序为左上、右上、右下、左下。
否post_mattingbooleantrue仅商品类别生效。开启边缘后处理可得到更精细的边缘,额外耗时约 0.2~1 秒。
否model_typeintegernull指定模型: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

Python SDK

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

Go SDK

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 SDK

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

Java SDK

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();
        }
    }
}