角色维护 API

接口与控制台维护同一份角色数据；草稿和发布版本分开保存。以下接口使用 POST 及请求签名。角色的外部 UID 在当前空间唯一，最长 128 字符，允许英文字母、数字和 ._:@-。

创建角色

POST /api/open/v1/personas/create

字段	必填	说明
`personaUid`	是	接入方角色账号 UID；已绑定时返回 409
`config`	是	完整角色配置，见下方示例
`publish`	否	默认 `false`，只建草稿；`true` 同时尝试发布

以下使用私聊配置，需当前应用已开通私聊；若空间配置了额外必填场景表单，请补齐其 sceneForms 值：

json

{
  "personaUid": "anchor-001",
  "config": {
    "base": {
      "nickname": "小雪",
      "bio": "喜欢旅行和日常聊天",
      "languages": ["zh-CN"],
      "timezone": "Asia/Shanghai",
      "profile": {},
      "life": {},
      "appearance": {},
      "boundaries": {}
    },
    "scenes": {
      "privateChat": {
        "enabled": true,
        "style": "自然接话",
        "initiative": "NORMAL",
        "followUp": "NATURAL",
        "rejection": "REASSURE",
        "offer": {
          "enabled": false,
          "firstOfferMessages": 5,
          "offerInterval": 7,
          "tone": "GENTLE"
        },
        "gift": {
          "enabled": false,
          "cooldownMinutes": 30
        }
      },
      "liveRoom": {
        "enabled": false,
        "style": "",
        "engagement": "NORMAL",
        "followUp": "NATURAL"
      }
    }
  },
  "publish": true
}

发布需要至少启用一个已开通的场景。创建与发布不是一个原子操作：发布校验失败时可能已留下草稿。请按 personaUid 查询后修改，不要直接换 UID 重复创建。

修改角色

POST /api/open/v1/personas/update

json

{
  "personaUid": "anchor-001",
  "config": { "base": { "nickname": "小雪" } },
  "publish": true,
  "lockVersion": 3
}

可用 personaId 代替 personaUid；同传时必须指向同一角色。config 使用 JSON Merge Patch：对象递归合并，null 删除字段，数组整体替换；删除必填字段会校验失败。publish 默认 false。

修改落到草稿；没有草稿时先从发布版本创建。
lockVersion 是可选乐观锁。建议先查询、带回版本再修改；过期返回 409。省略并不防止覆盖自己查询之后的修改。
publish: true 发布整份草稿，包括运营在控制台尚未发布的其他修改。
没有通用请求幂等键保证发布只发生一次。遇到超时先查询版本及内容，再决定是否重试。

查询角色

POST /api/open/v1/personas/get

json

{ "personaUid": "anchor-001" }

成功响应示例（草稿内容作缩略展示）：

json

{
  "code": "OK",
  "message": "success",
  "data": {
    "personaId": "11",
    "personaUid": "anchor-001",
    "status": "DRAFT",
    "version": 0,
    "lockVersion": 0,
    "hasDraft": true,
    "draft": {},
    "published": null,
    "updatedAt": "2026-10-26T08:00:00Z"
  }
}

上例 draft: {} 仅缩略展示，实际是保存的完整配置；创建／修改成功也返回同一结构。

字段	说明
`status`	`DRAFT` 未发布、`ACTIVE` 启用、`PAUSED` 暂停
`version`	发布版本；尚未发布为 0
`lockVersion`	数据修改版本，用于并发控制，与发布版本不同
`hasDraft`	是否有可编辑草稿
`draft` / `published`	草稿及发布配置；无发布版本时 `published` 为 null
`updatedAt`	UTC ISO 8601 时间

配置字段

路径	主要字段
`base`	`nickname`（必填，40 字）、`bio`（160 字）、`timezone`（必填）、`languages`（必填，最多 4 项，`zh-CN` / `en` / `ja` / `es`）
`base.profile`	`birthday`（YYYY-MM-DD）、`height`、`weight`、`occupation`
`base.life`	`interests`、`likes`、`dislikes`、`personality`、`speakingStyle`、`background`
`base.appearance`	`ethnicity`、`skinTone`、`facialFeatures`、`hairstyle`、`bodyDescription`
`base.boundaries`	`prohibitedTopics`、`handoffNotes`（设置文本，不代表已提供人工接管 API）
`scenes.privateChat`	`enabled`、`style`、`initiative`（`QUIET` / `NORMAL` / `ACTIVE`）、`followUp`（`NONE` / `NATURAL` / `ACTIVE`）、`rejection`、`offer`、`gift`
`scenes.liveRoom`	直播配置；本页不提供直播接入 API
`sceneForms`	当前空间场景表单值；按控制台实际配置填写

扩展字段建议先在控制台设置，再用查询接口获取规范结构。平台账号登录、余额及产品内封禁仍由接入方管理。变更同步见角色变更通知。

角色维护 API ​

创建角色 ​

修改角色 ​

查询角色 ​

配置字段 ​

角色维护 API

创建角色

修改角色

查询角色

配置字段