生成角色封面图

接口说明

根据用户选择的体型、种族、发型等属性，调用 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	认证失败
400	请求参数缺失或格式错误
500	RunPod 生成服务错误

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)

  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)
  }
}