角色列表 API

用于检索用户创建的角色列表的 API。

Convai 的角色列表 API 端点

POST https://api.convai.com/character/list

调用此端点以获取用户账户的角色列表。角色列表包含所有角色的相关信息。

请求

请求正文只需要以下头字段：

请求头

字段名	类型	值 / 描述
CONVAI-API-KEY*	字符串	用户的 Convai API 密钥

响应

200：成功

成功时，API 将返回以下格式的嵌套 JSON 对象：

{
  "characters": [
    {
      "character_name": "Rafael",
      "collection_name": "convai_default_collection",
      "user_id": "SOME_USER_ID",
      "character_id": "SOME_CHAR_ID",
      "model_type": "RPM-3D",
      "state_names": [],
      "state_links": [],
      "listing": "未列出",
      "voice_type": "SOME_VOICE",
      "voice_pitch": 0.0,
      "blockchain": "NULL",
      "contract_address": "NULL",
      "mint_address": "NULL",
      "owner_address": "NULL",
      "timestamp": "2023-11-07T02:57:59",
      "character_actions": [
        "笑",
        "走路",
        "跑步",
        "咯咯笑"
      ],
      "character_emotions": [],
      "model_details": {
        "modelType": "RPM-3D",
        "modelLink": "https://models.readyplayer.me/63f8983f9dc8b8dcb3aff14a.glb",
        "modelPlaceholder": "https://models.readyplayer.me/63f8983f9dc8b8dcb3aff14a.png?pose=relaxed&background=0,0,60",
        "METAHUMAN": {
          "avatar_id": "4d923463-f1c8-4169-95f4-d6d19f6ad49a",
          "avatar_image": "https://storage.googleapis.com/experience-asset-storage/user-uploaded-avatar-image/4d923463-f1c8-4169-95f4-d6d19f6ad49a_avatar_image.png?img_last_modified=1737042662?img_last_modified=1737113901",
          "avatar_image_square": "https://storage.googleapis.com/experience-asset-storage/user-uploaded-avatar-image/4d923463-f1c8-4169-95f4-d6d19f6ad49a_avatar_image_square?img_last_modified=1737042662?img_last_modified=1737113901",
          "experience_id": "faa18c71-fc1d-4282-b616-f88a79cd9d62",
          "bg_image": ""
        }
      },
      "language_code": "en-US",
      "guard_rails": {
        "type1": "3"
      },
      "metadata_filter": {},
      "personalised_prompt_config": {
        "MODEL": "gpt-4o",
        "PROMPT": "",
        "VERBOSITY": 2,
        "TEMPERATURE": 0.07,
        "MODERATION_ENABLED": true,
        "USE_COMBINED_PROMPT": "true",
        "ALLOWED_MODERATION_FILTERS": [
          "暴力",
          "暴力/图形化"
        ],
        "USE_ACTION_OPTMIZED_PROMPT": true
      },
      "boosted_words": {
        "words": []
      },
      "guardrail_meta": {
        "limitResponseLevel": 4,
        "blockedWords": []
      },
      "start_narrative_section_id": null,
      "is_narrative_driven": false,
      "character_traits": {
        "catch_phrases": [],
        "speaking_style": "无",
        "personality_traits": {
          "openness": 2,
          "sensitivity": 2,
          "extraversion": 2,
          "agreeableness": 2,
          "meticulousness": 2
        }
      },
      "language_codes": [
        "en-US"
      ],
      "memory_settings": {
        "enabled": false
      },
      "last_interacted_with": "2025-02-20T07:20:13",
      "pronunciation_metadata": {
        "pronunciations": [
          {
            "word": "OCMO",
            "ipaPronunciation": "ɔkmow",
            "customPronunciation": "aukmo"
          }
        ]
      },
      "description": "",
      "speaking_style": {
        "description": "",
        "sample_dialogues": ""
      },
      "embodiment": null,
      "embodiment_data": {}
    },
    {
      "character_name": "Steven",
      "collection_name": "convai_default_collection",
      "user_id": "SOME_USER_ID",
      "character_id": "SOME_CHAR_ID",
      "model_type": "RPM-3D",
      "state_names": [],
      "state_links": [],
      "listing": "未列出",
      "voice_type": "SOME_VOICE",
      "voice_pitch": 0.0,
      "blockchain": "NULL",
      "contract_address": "NULL",
      "mint_address": "NULL",
      "owner_address": "NULL",
      "timestamp": "2024-12-19T10:30:42",
      "character_actions": [],
      "character_emotions": [],
      "model_details": {
        "modelType": "RPM-3D",
        "modelLink": "https://models.readyplayer.me/673282ecef64719015ef8068.glb",
        "modelPlaceholder": "https://models.readyplayer.me/673282ecef64719015ef8068.png?pose=relaxed&background=0,0,60&size=512",
        "METAHUMAN": {
          "avatar_id": "c63e322d-c2cb-46f0-a466-9fd7c8073f9b",
          "avatar_image": "https://storage.googleapis.com/experience-asset-storage/user-uploaded-avatar-image/c63e322d-c2cb-46f0-a466-9fd7c8073f9b_avatar_image.png?img_last_modified=1737042663",
          "avatar_image_square": "https://storage.googleapis.com/experience-asset-storage/user-uploaded-avatar-image/c63e322d-c2cb-46f0-a466-9fd7c8073f9b_avatar_image_square?img_last_modified=1737042663",
          "experience_id": "7eb6e6eb-158d-44b1-8ecf-1657205f7765",
          "bg_image": ""
        }
      },
      "language_code": "en-US",
      "guard_rails": {
        "type1": "3"
      },
      "metadata_filter": {},
      "personalised_prompt_config": {
        "PROMPT": "",
        "MODEL": "gpt-4o-mini",
        "VERBOSITY": 2,
        "SPEAKER": "用户",
        "MODERATION_ENABLED": true,
        "ALLOWED_MODERATION_FILTERS": [
          "暴力",
          "暴力/图形化"
        ],
        "USE_COMBINED_PROMPT": true,
        "TEMPERATURE": 0.7
      },
      "boosted_words": {
        "words": []
      },
      "guardrail_meta": {
        "limitResponseLevel": 4,
        "blockedWords": []
      },
      "start_narrative_section_id": "d20e62cc-bdf5-11ef-a5c2-42010a7be016",
      "is_narrative_driven": true,
      "character_traits": {
        "catch_phrases": [],
        "speaking_style": "无",
        "personality_traits": {
          "openness": 2,
          "sensitivity": 2,
          "extraversion": 2,
          "agreeableness": 2,
          "meticulousness": 2
        }
      },
      "language_codes": [
        "en-US"
      ],
      "memory_settings": {
        "enabled": true
      },
      "last_interacted_with": "2025-02-12T08:23:05",
      "pronunciation_metadata": {
        "pronunciations": []
      },
      "description": "",
      "speaking_style": {
        "description": "",
        "sample_dialogues": ""
      },
      "embodiment": null,
      "embodiment_data": {
        "looks_description": "",
        "clothes_description": ""
          }
        }, .... 
    ]
    }

400：未找到 API 密钥

401：提供的 API 密钥无效

500：内部服务器错误

响应字段说明

• character_name：角色的名称。
• user_id：用户 / 角色所有者的用户 ID。
• character_id：角色的唯一 ID。
• voice_type：角色设置的语音。
• model_type：角色使用的模型（头像）。
• timestamp：角色创建时的时间戳。
• character_actions：用户为角色描述的一组动作。
• character_emotions：用户为角色描述的一组情感。
• personalised_prompt_config：后端中该角色使用的模型和提示词相关信息。
• language_codes：角色支持的语言列表。
• pronunciation_metadata：与角色设置的自定义发音相关的信息。

示例代码片段

import requests

# API 端点的 URL
url = 'https://api.convai.com/character/list'

# 创建请求头
headers = {
     'CONVAI-API-KEY': '<your api key>',
}

# 发起请求
response = requests.post(url, headers=headers)

# 检查请求是否成功
if response.status_code == 200:
    # 打印响应内容
    print(response.json())
else:
    print(f"获取数据失败。状态码：{response.status_code}")