Face Cutout API

Try on PicWish

AI detects the face or head area in an image, removes the background, and outputs a clean transparent cutout. It is suitable for portrait head cutouts, pet cutouts, cartoon characters, stickers, and event props, with async and sync request modes.

The result image URL is valid for 1 hour. Please download and store it promptly.

Authentication

Every API request must include your API Key in the X-API-KEY request header. Send it with each request exactly as shown in the examples and parameter descriptions.

X-API-KEY: YOUR_API_KEY

Create a face cutout task

POST /api/tasks/visual/self-face-cutout

Body Parameters

image_url string optional

Source image URL. Use either image_url or image_file. If this parameter is present, the other image source parameters must be empty.

one required

image_file file optional

Source image file as binary data. Use either image_file or image_url. If this parameter is present, the other image source parameters must be empty.

For image upload requirements, see Guidelines and Limits #2.

sync string | number optional

Whether to wait for the result and return it immediately. Use 0 to return a task_id asynchronously, then fetch the result later with the task_id. Use 1 to wait and return the result synchronously. Results are kept for up to 1 hour.

crop number optional

Whether to crop to the target edge. 0 keeps the original image size (default); 1 crops to the target edge.

output_format string optional

Result image format. png returns a transparent image (default); jpg returns a JPG image.

Return Parameters

status number

HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.

message string

API response message. Usually success for a successful request.

data.task_id string

Async face cutout task ID returned after the task is created. Use it to query the result later.

status number

HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.

message string

API response message. Usually success for a successful request.

data.task_id string

Face cutout task ID.

data.created_at string

Task creation time as a Unix timestamp string.

data.processed_at string

Task processing start time as a Unix timestamp string.

data.completed_at string

Task completion time as a Unix timestamp string.

data.image string

Face cutout result image URL. The URL is valid for 1 hour.

data.mask string

Mask image URL. The URL is valid for 1 hour.

data.output_type number

Returned image type.

data.progress number

Task progress. 100 means processing is complete.

data.state number

Task status code. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.

Query face cutout result

GET /api/tasks/visual/self-face-cutout/{task_id}

Path Parameters

task_id string required

Face cutout task ID returned after creating an async task. Use it to query the processing result.

Return Parameters

status number

HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.

message string

API response message. Usually success for a successful request.

data.task_id string

Face cutout task ID.

data.created_at string

Task creation time as a Unix timestamp string.

data.processed_at string

Task processing start time as a Unix timestamp string.

data.completed_at string

Task completion time as a Unix timestamp string.

data.image string

Face cutout result image URL. The URL is valid for 1 hour.

data.mask string

Mask image URL. The URL is valid for 1 hour.

data.progress number

Task progress. 100 means processing is complete.

data.state number

Task status code. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.

Guidelines and Limits

The result image URL is valid for 1 hour. Please download and store it promptly.
Uploaded images must meet the following format, resolution, and file size limits.

Format Resolution Size

jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw Up to 4096 x 4096 Up to 20MB

Format	Resolution	Size
jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw	Up to 4096 x 4096	Up to 20MB

Response

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // Only present in async polling results.
    "processed_at": "1634884056", // Only present in async polling results.
    "completed_at": "1634884056", // Only present in async polling results.
    "image": "https://wxtechhk.oss-hongkong.aliyuncs.com/tasks/output/self-face-cutout/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // Only present in async polling results.
    "mask": "https://wxtechhk.oss-hongkong.aliyuncs.com/tasks/output/self-face-cutout/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-mask.jpg", // Only present in async polling results.
    "progress": 100, // Only present in async polling results.
    "state": 1 // Only present in async polling results.
  }
}