Character management API

The API and console edit the same character. Draft and published configurations are separate. All endpoints use POST and request signing. The external UID is unique within the workspace and limited to 128 characters: letters, digits, and ._:@-.

Create

POST /api/open/v1/personas/create

Field	Required	Meaning
personaUid	Yes	Your character account UID; an existing binding returns 409
config	Yes	Complete character configuration; example below
publish	No	Defaults to false (draft only); true also attempts publication

This example requires private chat to be enabled for the application. Supply sceneForms values if the workspace has additional required scene fields. Chinese sample text can be replaced with your character's content.

{
  "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
}

Publication requires at least one enabled, authorized scene. Creation and publication are not atomic: publication validation can fail after a draft has been created. Query by personaUid and update that draft instead of creating another UID.

Update

POST /api/open/v1/personas/update

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

Use personaId instead of personaUid, or provide both if they identify the same character. config uses JSON Merge Patch: objects merge recursively, null deletes a field, and arrays replace the entire previous array. Removing a required field fails validation. publish defaults to false.

• Updates modify the draft. When necessary, a draft is first created from the published version.
• lockVersion is an optional optimistic lock. Read the character and send its version back; a stale version returns 409. Omitting it does not protect changes made after your last read.
• publish: true publishes the entire draft, including other unpublished console edits.
• There is no generic request idempotency key guaranteeing one publication. After a timeout, query the version and content before deciding whether to retry.

Get

POST /api/open/v1/personas/get

{"personaUid":"anchor-001"}

Example response with an abbreviated draft:

{"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: {} is abbreviated here; actual responses contain the saved configuration. Create and update return the same structure.

Field	Meaning
status	DRAFT (unpublished), ACTIVE, or PAUSED
version	Published version, or 0 before first publication
lockVersion	Mutation version for concurrency control, distinct from the published version
hasDraft	Whether an editable draft exists
draft / published	Draft and published configurations; published is null before publication
updatedAt	UTC ISO 8601 timestamp

Configuration fields

Path	Main fields
base	nickname (required, 40 characters), bio (160 characters), timezone (required), languages (required, at most 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 (configuration text, not a human-handoff API)
scenes.privateChat	enabled, style, initiative (QUIET, NORMAL, ACTIVE), followUp (NONE, NATURAL, ACTIVE), rejection, offer, gift
scenes.liveRoom	Live configuration; this page does not define a live integration API
sceneForms	Values for the workspace's scene forms; use its console configuration

For additional fields, configure them in the console and query the resulting canonical structure. Account login, balances, and product bans remain your responsibility. See character change notifications for synchronization.