Skip to main content
QwenCloud home page
Docs
Image editing

Person instance segmentation

Detect each person in an image and generate a pixel-level mask for each instance

image-instance-segmentation detects each person in an image and generates a pixel-level mask for each instance. It works with complex backgrounds and returns both a mask image and a visualization image. Quick links: API reference: Create a task, Query the result Supported regions: China North 2 (Beijing) only. Use an API key created in that region and the https://cn-beijing.maas.qwencloudapi.com endpoint. See Regions and endpoints.
The model is available for free trial only. After the free quota is used, calls are no longer possible.

Use cases

  • Portrait matting: Separate the subject from the background, then blur the background for a shallow depth of field effect.
  • ID photo creation: Segment each person in a group photo, then combine the mask with Image erase completion to keep a single person.
  • Marketing assets: Separate a product or a person from a scene and remove unwanted foreground or background elements.

Image requirements

  • Format: JPEG, PNG, JPG, BMP, or WEBP.
  • Resolution: width and height between 512 and 4,096 pixels.
  • File size: up to 10 MB.
  • The URL must be publicly accessible over HTTP or HTTPS and must not contain Chinese characters.

Output

FieldDescription
output.output_image_urlMask image. Each person instance has a different grayscale value (1, 2, 3, ...); the background is 0.
output.output_vis_image_urlVisualization image. Each instance is overlaid on the original image in a different color.
Both URLs are valid for 24 hours.

Request example

import os
import time
import requests

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
BASE_URL = "https://cn-beijing.maas.qwencloudapi.com/api/v1"
headers = {
  "Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}",
  "Content-Type": "application/json",
  "X-DashScope-Async": "enable",
}

response = requests.post(
  f"{BASE_URL}/services/aigc/image2image/image-synthesis",
  headers=headers,
  json={
    "model": "image-instance-segmentation",
    "input": {"image_url": "https://example.com/image.png"},
    "parameters": {}
  },
)
task_id = response.json()["output"]["task_id"]

while True:
  result = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=headers).json()
  status = result["output"]["task_status"]
  if status in ("SUCCEEDED", "FAILED"):
    break
  time.sleep(5)

print(result)

Remove people with the mask

  1. Run segmentation and download output_image_url.
  2. Pass that image as mask_url in an Image erase completion request.
  3. Set dilate_flag to true so that the mask is expanded slightly and edges are fully removed.

FAQ

Why does the task fail with InvalidParameter.ImageFormat? The input image does not meet the format or resolution requirements. Check the file type, size, and pixel dimensions. Can the output mask be used as a foreground mask? Yes. Pass it as foreground_url in Image erase completion to protect the selected people instead of erasing them.