上传参考图

接口说明

上传参考人脸图，获取 imageId，再将其传入自定义生图接口的 refImageId 字段。

INFO

此接口为可选步骤，仅在需要参考人脸图时调用。

基本信息

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

签名说明

multipart/form-data 接口无 JSON body，canonicalBody 为空字符串：

signatureBase = "POST\n/v1/image/upload\n{X-Timestamp}\n{X-User-ID}\n\n"
X-Signature   = HMAC-SHA256(signatureBase, apiSecret)

请求体（multipart/form-data）

字段	类型	必填	说明
file	File	✅	图片文件，支持 jpg/png/webp，最大 10MB

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "data": {
    "imageId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

字段	类型	说明
data.imageId	string	图片 ID，传入生图接口的 refImageId 字段

错误响应

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

客户端示例

async function uploadRefImage(apiKey, apiSecret, userId, file) {
  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, {}, {
    url: '/v1/image/upload',
    isMultipart: true,
  })

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

  const response = await fetch('/v1/image/upload', {
    method: 'POST',
    headers,   // 不包含 Content-Type，浏览器自动设置 multipart boundary
    body: formData,
  })

  const result = await response.json()
  if (!result.success) throw new Error('上传失败：' + result.message)
  return result.data.imageId
}