创建自定义角色

接口说明

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

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

WARNING

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

基本信息

项目	说明
接口路径	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/saas/custom-agent/cover/uuid.png"
  },
  "traceId": "xEo3sQwB6KRuwFfG2BxNWwlLQhKrvg38",
  "timestamp": "1773298769366"
}

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

错误响应

HTTP 状态码	说明
401	认证失败
400	参数缺失或格式错误
500	Dify 服务错误

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 response = await fetch('/v1/agent/list', {
  method: 'POST',
  headers: await buildAuthHeaders(apiKey, apiSecret, userId, {
    pageNumber: 1, pageSize: 20, language: 'en', type: 'custom'
  }),
  body: JSON.stringify({ pageNumber: 1, pageSize: 20, language: 'en', type: 'custom' }),
})
// 返回当前 API Key 创建的所有自定义角色