人脸检测

接口说明

上传参考图后，调用此接口检测图片中是否含有有效人脸。此步骤可选，主要用于在进行后续封面生成前对参考图进行质量校验。

INFO

若跳过此步骤，可直接将参考图 ID（refImageId）传入 生成封面图 接口；人脸检测服务不可用时，跳过即可，不影响封面生成流程。

基本信息

项目	说明
接口路径	POST /v1/agent/face-detect
请求类型	multipart/form-data
响应类型	application/json
认证方式	API Key + 请求签名（认证说明）

请求参数

字段	类型	必填	说明
file	File	✅	图片文件，支持 JPEG / PNG，大小 ≤ 20MB

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "hasFace": true
  },
  "traceId": "xEo3sQwB6KRuwFfG2BxNWwlLQhKrvg38",
  "timestamp": "1773298769366"
}

字段	类型	说明
data.hasFace	boolean	true 表示检测到人脸，false 表示未检测到

错误响应

HTTP 状态码	说明
401	鉴权失败（缺少请求头、时间戳过期、API Key 无效或签名错误）
200	业务错误：success=false，常见 code 为 10400 或 10500，错误原因见 message

客户端示例

async function detectFace(apiKey, apiSecret, userId, imageFile) {
  // multipart 接口，canonicalBody 为空字符串
  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, {}, {
    url: '/v1/agent/face-detect',
    isMultipart: true,
  })

  const formData = new FormData()
  formData.append('file', imageFile)

  const response = await fetch('/v1/agent/face-detect', {
    method: 'POST',
    headers,
    body: formData,
  })

  const result = await response.json()
  return result.data.hasFace // true / false
}

TIP

multipart/form-data 接口的 canonicalBody 固定为空字符串，不参与请求体字段的签名。详见认证说明。