上传参考图

接口说明

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

INFO

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

基本信息

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

签名说明

multipart/form-data 无 JSON body，签名基于空参数：

X-Signature = sha256("" + 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	认证失败
400	文件格式不支持或超过大小限制
500	上传失败

客户端示例

async function uploadRefImage(apiKey, apiSecret, userId, file) {
  const timestamp = Math.floor(Date.now() / 1000).toString()
  const requestId = crypto.randomUUID().replace(/-/g, '')

  // 空参数签名
  const hashBuffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(apiSecret))
  const signature = Array.from(new Uint8Array(hashBuffer))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('')

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

  const response = await fetch('/v1/image/upload', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
      'X-Request-ID': requestId,
      'X-User-ID': userId,
      // 不设置 Content-Type，浏览器自动设置 multipart boundary
    },
    body: formData,
  })

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