人脸检测

接口说明

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

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	认证失败
400	文件缺失
500	人脸检测服务不可用

客户端示例

async function detectFace(apiKey, apiSecret, userId, imageFile) {
  // 人脸检测不含 JSON body，签名使用空对象
  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, {})

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

  const response = await fetch('/v1/agent/face-detect', {
    method: 'POST',
    headers: {
      Authorization: headers['Authorization'],
      'X-Signature': headers['X-Signature'],
      'X-Timestamp': headers['X-Timestamp'],
      'X-User-ID': headers['X-User-ID'],
    },
    body: formData,
  })

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

TIP

签名计算时，人脸检测接口的请求体为 multipart/form-data，签名使用空对象 {} 计算，与其他 JSON 接口一致。详见认证说明。