获取上架列表，含 template_id 与 hardware_channels。设备绑定时需要 template_id 创建角色实例，channel_id 用于绑定路径。

响应 data: Publishing[]：

{
  "id": 1,
  "template_id": 10,
  "template_name": "默认模版",
  "publish_name": "chirpy 初代",
  "publish_logo": "https://...",
  "interaction_name": "自由对话",
  "publish_game_url": "https://...",
  "template_info": {
    "description": "...",
    "basic_personality": "...",
    "gender": "female",
    "catchphrase": "...",
    "background": "...",
    "creator_name": "官方",
    "source": "官方"
  },
  "hardware_channels": [
    {
      "channel_id": 100,
      "channel_type": "official_hardware",
      "channel_type_display": "官方硬件",
      "hardware_type": "AI玩偶",
      "status": "online"
    }
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

仅返回已上架渠道。

响应 data: Channel[]：

{
  "channel_id": 100,
  "publish_name": "chirpy 初代",
  "channel_type": "official_hardware",
  "channel_type_display": "官方硬件",
  "hardware_type": "AI玩偶",
  "status": "online",
  "publishing_id": 1,
  "template_id": 10,
  "created_at": "...",
  "updated_at": "..."
}

获取单个上架的详细信息。

响应 data：

{
  "id": 1,
  "template_id": 10,
  "template_name": "温柔姐姐",
  "publish_name": "温柔姐姐-公开版",
  "interaction_name": "小柔",
  "greeting": "你好呀~",
  "personality": "温柔体贴",
  "background_story": "..."
}

将硬件设备 ID 与外部用户 ID 关联，设备通过网关聊天时使用绑定用户身份。

请求 body：

{
  "device_id": "123456",
  "product_key": "（可选，渠道内重复设备 ID 时必填）",
  "external_user_id": "<user_id>",
  "external_user_nickname": "（可选）用户昵称"
}

响应 data: BindDeviceResult：

{
  "device_id": "123456",
  "product_key": "...",
  "channel_id": 100,
  "binding_id": 999,
  "character_id": 555,
  "external_user_id": "<user_id>",
  "external_user_nickname": "..."
}

校验规则（错误码）：

解绑仅清空设备上的外部用户信息，不删除角色绑定或已有聊天记录；但该用户将无法再通过 Open API 查询对应硬件会话。

请求 body：

{
  "device_id": "123456",
  "product_key": "（可选，消歧用）",
  "external_user_id": "<user_id>"  // 必须与设备当前绑定的外部用户 ID 一致
}

响应 data: UnbindDeviceResult：

{
  "device_id": "123456",
  "product_key": "...",
  "channel_id": 100,
  "binding_id": 999,
  "character_id": 555,
  "external_user_id": "<user_id>",
  "external_user_nickname": "...",
  "unbound": true
}

校验错误码：

查询范围仅限当前 API Key 已关联且处于上架状态的硬件渠道。

请求 query：

{
  "device_id": "123456",
  "channel_id": 100,       // 可选，消歧
  "product_key": "..."     // 可选，消歧
}

响应 data: DeviceCharacterResult：

{
  "device_id": "123456",
  "product_key": "...",
  "channel_id": 100,
  "binding_id": 999,
  "character_id": 555,
  "template_publishing_id": 1,
  "external_user_id": "<user_id>",      // 未绑定时空串
  "external_user_nickname": "..."        // 未绑定时空串
}

查询约束（错误码）：

响应 data: CharacterDetail：

{
  "id": 555,
  "template_id": 10,
  "name": "小叽",
  "description": "...",
  "basic_personality": "...",
  "personality": "...",
  "gender": "female",
  "age_stage": "adult",          // young / adult / old
  "background": "...",
  "background_story": "...",
  "greeting": "你好呀！",
  "avatar": "/path/to/avatar.png",
  "catchphrase": "...",
  "rag_enabled": false,
  "memory_enabled": true,
  "tts_enabled": true,
  "tts_voice_id": "qwen-xxx",
  "tts_audio_codec": "pcm",      // pcm 或 opus
  "recommendation_enabled": false,
  "vision_enabled": false,
  "created_at": "...",
  "updated_at": "..."
}

仅提交变更字段。

请求 body（Partial<CharacterUpdate>，全可选）：

{
  "name": "...",
  "description": "...",
  "avatar": "...",
  "basic_personality": "...",
  "personality": "...",
  "background": "...",
  "background_story": "...",
  "greeting": "...",
  "gender": "...",
  "age_stage": "...",
  "catchphrase": "...",
  "rag_enabled": false,
  "memory_enabled": true,
  "tts_enabled": true,
  "tts_voice_id": "...",
  "tts_audio_codec": "pcm",
  "recommendation_enabled": false,
  "vision_enabled": false
}

响应 data: CharacterDetail（同 GET 详情）。

响应：{ success: true, message: "Character deleted" }

合并查询指定用户的 Open API 与已授权绑定设备会话，默认只返回有效会话。

请求 query：

{
  "user_id": "<user_id>",           // 必填
  "character_id": 555,              // 可选
  "session_source": "all",          // all（默认）/ open_api / device
  "channel_id": 100,                // 可选，仅筛选指定渠道硬件会话
  "device_id": "123456",            // 可选
  "product_key": "...",             // 可选
  "include_expired": false,         // true 时含自动失效会话
  "include_inactive": false,        // true 时含手动关闭会话
  "page": 1,
  "page_size": 20                   // 默认 20，最大 100
}

响应（分页，保留完整对象）：

{
  "data": [
    {
      "id": 1001,
      "name": "open_api_小叽_<user_id>",  // 自动生成：open_api_{角色名}_{user_id}
      "session_source": "device",          // open_api=APP会话 / device=硬件网关会话
      "character_id": 555,
      "character_name": "小叽",
      "user_id": "<user_id>",
      "publishing_id": 1,                  // 硬件会话有；APP 会话为 null
      "channel_id": 100,                  // 同上
      "device_id": "123456",              // 同上
      "product_key": "...",               // 同上
      "is_active": true,                  // false=已手动关闭
      "is_expired": false,                // true=已自动失效（>24h 或 >5000 条）
      "message_count": 42,
      "last_message_at": "2026-01-01T12:00:00Z",
      "expired_at": null,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 3, "total_count": 58, "has_next": true, "has_previous": false },
  "last_message_at": "..."
}

会话状态说明：

API 默认按时间正序返回（旧→新）。

请求 query：

{
  "user_id": "<user_id>",
  "page": 1,
  "page_size": 50
}

响应（分页）：

{
  "data": [
    {
      "id": 9001,
      "chat_session_id": 1001,
      "character_id": 555,      // 用户消息时为 null
      "content": "你好",
      "message_type": "text",
      "is_user": true,
      "created_at": "2026-01-01T12:00:00Z"
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 3, "total_count": 58, "has_next": true, "has_previous": false },
  "last_message_at": "..."
}

返回已删除会话 ID 与消息条数。

请求 query：

{ "user_id": "<user_id>" }

响应 data: DeleteSessionResult：

{
  "deleted_session_id": 1001,
  "deleted_count": 42
}

备用功能：可导入设备端产生的对话。

请求 body：

{
  "user_id": "<user_id>",
  "messages": [
    { "role": "user", "content": "你好", "created_at": "（可选）" },
    { "role": "assistant", "content": "你好呀！", "created_at": "（可选）" }
  ]
}

响应 data: ImportMessagesResult：

{
  "imported_count": 2,
  "session_id": 1001
}

字段说明：

返回音频流（PCM-16 LE 单声道 或 OGG/Opus 容器）。响应头携带采样率与编码格式。

请求 body（TTSRequest）：

{
  "text": "要合成的文本",
  "voice_id": "（可选，内置音色名或自定义音色 ID，不传用角色配置）"
}

响应：

• 响应头：X-Sample-Rate（如 24000）、X-Audio-Codec（pcm / opus）
• 响应体：音频二进制流（Transfer-Encoding: chunked）

错误响应（error_code）：

内置音色清单（普通话，voice_id 取值）：