创建自定义角色

接口说明

基于封面图（coverId）和角色属性创建自定义角色。系统会调用 AI 自动生成角色的性格特征、回复风格和开场白，并将角色保存到账号中，后续可通过角色列表接口查询。

创建成功后，即可使用返回的 agentId 发起会话（与官方角色完全相同的流程）。

WARNING

coverId 有效期仅 30 分钟，请在封面图生成后尽快调用此接口完成创建。

TIP

系统会在创建时写入聊天图片生成所需的工作流配置（ComfyUI workflow，即内部 comfy_prompt）以及 Dify image key。 这些字段由系统生成并维护，客户端无需传入。如果后续 /v1/chat/image 报 Agent missing image generation config 或 RunPod 提示 invalid_prompt，通常表示该角色的工作流数据异常，建议重新创建角色或修复数据。

基本信息

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

请求体

{
  "coverId": "3f6a9b2e-1c4d-4e8f-a7b2-9d0e1f2a3b4c",
  "name": "Mia",
  "voiceId": "female_voice_01",
  "language": "en",
  "gender": "female",
  "age": "18-25",
  "ethnicity": "Asian",
  "bodyType": "Slim",
  "breastSize": "Medium",
  "buttSize": "Medium",
  "hairColor": "black",
  "hairStyle": "Long",
  "personality": "Flirty",
  "occupation": "Photographer",
  "relationship": "Girlfriend",
  "fetish": "Dominant",
  "refImageId": "550e8400-e29b-41d4-a716-446655440000"
}

字段	类型	必填	说明
coverId	string	✅	封面生成接口返回的 coverId，30 分钟有效
name	string	✅	角色名称
voiceId	string	✅	语音 ID，来自素材选项 Voice.code
language	string	✅	语言代码：en / zh / ja 等
gender	string	✅	male 或 female
age	string	✅	来自素材选项 Age.code
ethnicity	string	✅	来自素材选项 Ethnicity.code
bodyType	string	✅	来自素材选项 BodyType.code
breastSize	string	female 必填	来自素材选项 BreastSize.code
buttSize	string	female 必填	来自素材选项 ButtSize.code
hairColor	string	✅	来自素材选项 HairColor.code
hairStyle	string	✅	来自素材选项 HairStyle.code
personality	string	❌	性格特征，来自素材选项 Personality.code
occupation	string	❌	职业，来自素材选项 Occupation.code
relationship	string	❌	关系定位，来自素材选项 Relationship.code
fetish	string	❌	个性化偏好，来自素材选项 Fetish.code
refImageId	string	❌	参考图 ID，可选

响应格式

成功响应

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "agentId": "a36b6b38-e94d-ad19-c170-ad8de3a1a018",
    "name": "Mia",
    "coverUrl": "https://cdn.example.com/custom-agent/cover/uuid.png"
  },
  "traceId": "xEo3sQwB6KRuwFfG2BxNWwlLQhKrvg38",
  "timestamp": "1773298769366"
}

字段	类型	说明
data.agentId	string	角色 UUID，后续所有接口使用此 ID
data.name	string	角色名称
data.coverUrl	string	封面图公开访问 URL

错误响应

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

message	说明
coverId is expired or invalid, please regenerate cover	coverId 已过期（超过 30 分钟）或无效
breastSize is required for female	女性角色未传 breastSize

完整调用流程

// 第一步：查询素材选项（页面初始化时缓存）
const options = await fetchMaterialOptions(apiKey, apiSecret, userId, {
  namespace: 'custom_agent',
  gender: 'female',
  language: 'en',
})

// 第二步（可选）：上传参考图
const refImageId = await uploadRefImage(apiKey, apiSecret, userId, imageFile)

// 第三步（可选）：人脸检测
const hasFace = await detectFace(apiKey, apiSecret, userId, imageFile)
if (!hasFace) {
  console.warn('未检测到人脸，可继续但效果可能较差')
}

// 第四步：生成封面图（需要 30～300s）
const { coverId, imageData } = await generateAgentCover(apiKey, apiSecret, userId, {
  gender: 'female',
  age: options.Age[0].code,
  ethnicity: options.Ethnicity[0].code,
  bodyType: options.BodyType[0].code,
  breastSize: options.BreastSize[0].code,
  buttSize: options.ButtSize[0].code,
  hairColor: options.HairColor[0].code,
  hairStyle: options.HairStyle[0].code,
  refImageId,
})

// 展示 imageData 给用户确认封面效果

// 第五步：创建角色
const { agentId } = await createAgent(apiKey, apiSecret, userId, {
  coverId,
  name: 'Mia',
  voiceId: options.Voice[0].code,
  language: 'en',
  gender: 'female',
  age: options.Age[0].code,
  ethnicity: options.Ethnicity[0].code,
  bodyType: options.BodyType[0].code,
  breastSize: options.BreastSize[0].code,
  buttSize: options.ButtSize[0].code,
  hairColor: options.HairColor[0].code,
  hairStyle: options.HairStyle[0].code,
  personality: options.Personality[0].code,
  refImageId,
})

// 第六步：发起对话（与官方角色完全相同）
const { conversationId } = await createConversation(apiKey, apiSecret, userId, agentId)

查询已创建的自定义角色

// 使用 /v1/agent/list 并传入 type: "custom"
const listBody = { pageNumber: 1, pageSize: 20, language: 'en', type: 'custom' }
const response = await fetch('/v1/agent/list', {
  method: 'POST',
  headers: await buildAuthHeaders(apiKey, apiSecret, userId, listBody, {
    url: '/v1/agent/list',
  }),
  body: JSON.stringify(listBody),
})
// 返回当前 API Key 创建的所有自定义角色