头像抠图API

免费体验

AI 自动识别图像中的人脸或头部区域，去除背景并输出干净的透明图。适用于人物头像、宠物头像、卡通角色、贴纸、活动道具等场景。支持异步、同步两种调用方式。

接口返回的链接有效期为 1 小时，请及时下载存储。

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建头像抠图任务

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

请求参数

image_url string 可选

源图像 URL。与 image_file 二选一；如果传入此参数，其他图像源参数必须为空。

二选一必填
image_file file 可选

源图像文件（二进制）。与 image_url 二选一；如果传入此参数，其他图像源参数必须为空。

图片上传要求请参看使用规范与限制#2。

sync string | number 可选

是否等待结果就绪并立即返回。0 表示异步返回 task_id，稍后通过 task_id 获取结果；1 表示同步等待结果并立即返回。结果最多保留 1 小时。

crop number 可选

是否裁剪至目标边缘。0 表示返回原始图像大小（默认）；1 表示裁剪至目标边缘。

output_format string 可选

结果图片格式。png 表示透明图（默认）；jpg 表示 JPG 图片。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见 状态码说明。

message string

接口返回消息。成功时通常为 success。

data.task_id string

异步头像抠图任务 ID。创建任务成功后返回，用于后续查询头像抠图结果。

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见 状态码说明。

message string

接口返回消息。成功时通常为 success。

data.task_id string

头像抠图任务 ID。

data.created_at string

任务创建时间，Unix 时间戳字符串。

data.processed_at string

任务开始处理时间，Unix 时间戳字符串。

data.completed_at string

任务完成时间，Unix 时间戳字符串。

data.image string

头像抠图结果图片 URL，链接有效期为 1 小时。

data.mask string

结果 mask 图片 URL，链接有效期为 1 小时。

data.output_type number

返回的图片类型。

data.progress number

任务处理进度。100 表示处理完成。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见 状态码说明。

查询头像抠图结果

异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 60 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。

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

路径参数

task_id string 必填

头像抠图任务 ID。创建异步头像抠图任务后返回，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见 状态码说明。

message string

接口返回消息。成功时通常为 success。

data.task_id string

头像抠图任务 ID。

data.created_at string

任务创建时间，Unix 时间戳字符串。

data.processed_at string

任务开始处理时间，Unix 时间戳字符串。

data.completed_at string

任务完成时间，Unix 时间戳字符串。

data.image string

头像抠图结果图片 URL，链接有效期为 1 小时。

data.mask string

结果 mask 图片 URL，链接有效期为 1 小时。

data.progress number

任务处理进度。100 表示处理完成。

data.state number

任务状态码。1 表示处理成功，大于 1 表示处理中，小于 0 表示失败，详见 状态码说明。

使用规范与限制

  1. 接口返回的链接有效期为 1 小时，请及时下载存储。

  2. 上传图片需符合以下格式、分辨率和大小限制。

    格式分辨率大小
    jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw最大 4096x4096最大20MB