生成角色封面图

接口说明

根据用户选择的体型、种族、发型等属性，调用 AI 生成自定义角色封面图。

WARNING

该接口为同步阻塞接口，生成过程通常需要 30～300 秒，请设置足够长的超时时间（建议 ≥ 350 秒）。

INFO

接口返回 coverId（有效期 30 分钟）供后续创建角色使用，同时返回 imageData（base64）供前端预览，无需等待上传完成。

基本信息

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

请求体

{
  "gender": "female",
  "age": "18-25",
  "ethnicity": "Asian",
  "bodyType": "Slim",
  "breastSize": "Medium",
  "buttSize": "Medium",
  "hairColor": "black",
  "hairStyle": "Long",
  "refImageId": "550e8400-e29b-41d4-a716-446655440000"
}

字段	类型	必填	说明
gender	string	✅	male 或 female
age	string	✅	来自素材选项 Age.code
ethnicity	string	✅	来自素材选项 Ethnicity.code
bodyType	string	✅	来自素材选项 BodyType.code（受 gender 过滤）
breastSize	string	female 必填	来自素材选项 BreastSize.code
buttSize	string	female 必填	来自素材选项 ButtSize.code
hairColor	string	✅	来自素材选项 HairColor.code
hairStyle	string	✅	来自素材选项 HairStyle.code（受 gender 过滤）
refImageId	string	❌	参考图 ID，由上传参考图接口返回

TIP

所有选项 code 请通过 POST /v1/config/options（namespace: "custom_agent"）查询获取。

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "coverId": "3f6a9b2e-1c4d-4e8f-a7b2-9d0e1f2a3b4c",
    "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "traceId": "xEo3sQwB6KRuwFfG2BxNWwlLQhKrvg38",
  "timestamp": "1773298769366"
}

字段	类型	说明
data.coverId	string	封面临时 ID，30 分钟有效，创建角色时传入
data.imageData	string	封面图 base64 数据，供前端预览

错误响应

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

message	说明
breastSize is required for female	女性角色未传 breastSize
buttSize is required for female	女性角色未传 buttSize

客户端示例

async function generateAgentCover(apiKey, apiSecret, userId, params) {
  const {
    gender, age, ethnicity, bodyType,
    breastSize, buttSize, hairColor, hairStyle, refImageId
  } = params

  const body = { gender, age, ethnicity, bodyType, hairColor, hairStyle }
  if (breastSize) body.breastSize = breastSize
  if (buttSize)   body.buttSize   = buttSize
  if (refImageId) body.refImageId = refImageId

  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, body, {
    url: '/v1/agent/cover',
  })

  const controller = new AbortController()
  const timeoutId = setTimeout(() => controller.abort(), 350000) // 350s 超时

  try {
    const response = await fetch('/v1/agent/cover', {
      method: 'POST',
      headers,
      body: JSON.stringify(body),
      signal: controller.signal,
    })

    const result = await response.json()
    if (!result.success) throw new Error(result.message)

    return {
      coverId: result.data.coverId,     // 传给创建接口
      imageData: result.data.imageData, // 展示给用户确认
    }
  } finally {
    clearTimeout(timeoutId)
  }
}