agents

characters

android_app

web_app

evaluation

更新智能体（AI 角色）

更新任何图片，都会将图片全部记录在 background_images 字段中，用于保存历史记录如果没有提供 avatar，则会自动截取头像，并记录在 avatar 字段中

put/api/v1/ai/agents/{agent_id}

Path parameters

agent_idstring required

Request body

namestring nullable

genderstring nullable

avatarstring nullable

backgroundstring nullable

background_imagesstring[] nullable

background_animatedstring nullable

voice_idstring nullable

settingsobject nullable

introstring nullable

openingstring nullable

opening_audio_urlstring nullable

visibility'PUBLIC' | 'PRIVATE'

AI 角色可见性

source'USER_CREATED' | 'AUTO_GENERATED'

AI 角色来源

photosstring[] nullable

categorystring nullable

promptstring nullable

已废弃 - 请使用personality字段代替

main_promptstring nullable

mode_promptstring nullable

character_card_specstring nullable

personalitystring nullable

scenariostring nullable

message_examplestring nullable

creator_notesstring nullable

post_history_instructionsstring nullable

alternate_greetingsstring[] nullable

character_bookobject nullable

tagsstring[] nullable

character_versionstring nullable

extensionsobject nullable

energy_pointsinteger nullable

需要新增的能量点数，会累加到 agent 的积分列中

replace_background_imagesboolean nullable

是否替换 background_images 列表。为 True 时完全替换，为 False 或 None 时追加

request_idstring nullable

Response

Successful Response

namestring required

genderstring required

avatarstring nullable

backgroundstring nullable

background_imagesstring[] nullable

background_animatedstring nullable

voice_idstring nullable

settingsobject nullable

introstring nullable

openingstring nullable

opening_audio_urlstring nullable

visibility'PUBLIC' | 'PRIVATE'

AI 角色可见性

source'USER_CREATED' | 'AUTO_GENERATED'

AI 角色来源

photosstring[] nullable

categorystring nullable

promptstring nullable

已废弃 - 请使用personality字段代替

main_promptstring nullable

主提示词 - 作为第一个system message，覆盖全局默认主提示词。可以是预设 ID 或自定义文本

mode_promptstring nullable

模式提示词 - 放在角色卡提示词后面，覆盖全局默认模式提示词。可以是预设 ID 或自定义文本

character_card_specstring nullable

personalitystring nullable

角色性格特点 (推荐)

scenariostring nullable

背景设定 (推荐)

message_examplestring nullable

对话示例

creator_notesstring nullable

创作者备注

post_history_instructionsstring nullable

alternate_greetingsstring[] nullable

character_bookobject nullable

tagsstring[] nullable

character_versionstring nullable

extensionsobject nullable

idstring required

readable_idstring required

status'PENDING' | 'APPROVED' | 'REJECTED' required

AI角色状态

creator_idstring nullable

created_atinteger required

updated_atinteger nullable

deleted_atinteger nullable

versioninteger required

energy_pointsinteger

Agent 当前能量点数，对应数据库 points 列

is_followedboolean

follower_countinteger

connector_countinteger

Changes

Changed in 8 of the 26 revisions of this API.122

Jan 28, 20261e014c365df212See the full diff
- ●
  removed the optional property user from the response with the 200 status
  response-optional-property-removed
- ○
  added the new optional request property source
  new-optional-request-property
- ○
  added the optional property source to the response with the 200 status
  response-optional-property-added
Jan 12, 20265b77ae7cc5c42See the full diff
- ○
  added the new optional request property replace_background_images
  new-optional-request-property
- ○
  added the optional property creator/anyOf[subschema #1: User]/user_photo to the response with the 200 status
  response-optional-property-added
Dec 12, 2025b2372bf7485c3See the full diff
- ○
  added the new optional request property energy_points
  new-optional-request-property
- ○
  added the optional property creator/anyOf[subschema #1: User]/actions to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property energy_points to the response with the 200 status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Nov 25, 202505cf5f034c746See the full diff
- ○
  api tag android_app added
  api-tag-added
- ○
  api tag evaluation added
  api-tag-added
- ○
  api tag web_app added
  api-tag-added
- ○
  added the new optional request property background_animated
  new-optional-request-property
- ○
  added the optional property background_animated to the response with the 200 status
  response-optional-property-added
- ○
  added the required property version to the response with the 200 status
  response-required-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Sep 29, 2025bd9470194fe12See the full diff
- ○
  added the new optional request property request_id
  new-optional-request-property
- ○
  added the optional property user to the response with the 200 status
  response-optional-property-added
Sep 26, 2025d681a7df36092See the full diff
- ○
  added the optional property avatar_size to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property background_size to the response with the 200 status
  response-optional-property-added
Sep 25, 20257ee2ad97db782See the full diff
- ○
  added the new optional request property meta_data
  new-optional-request-property
- ○
  added the optional property meta_data to the response with the 200 status
  response-optional-property-added
Sep 10, 202556253b536c003See the full diff
- ○
  added the new optional request property opening_audio_url
  new-optional-request-property
- ○
  added the optional property deleted_at to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property opening_audio_url to the response with the 200 status
  response-optional-property-added

Full history