角色維護 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

建立角色

修改角色

查詢角色

配置欄位