AI 助手

接入大模型的设置与测试连接、模型评分表、可用状态与额度、会话记录、助手外观。

aiAI 助手鉴权: 用户21 个接口

列出全部用户的 AI 会话

GET/api/v2/ai/admin/conversations

鉴权: 仅管理员

查询参数

字段	类型	必填	说明
page	integer	—	页码,从 1 开始。默认 `1`
page_size	integer	—	每页条数。默认 `20`
user_id	integer	—	只看这个用户的会话。
since	string	—	起始时间(含),RFC 3339;会话最后一条消息不早于它。
until	string	—	结束时间(不含),RFC 3339;会话开始早于它。
kind	string	—	all 全部(缺省);changed 有计划动过网站(建了站或执行完);failed 有计划失败。可选值 `["all","changed","failed"]`
q	string	—	按标题或消息正文的子串搜。

查看任一用户的 AI 会话

GET/api/v2/ai/admin/conversations/{id}

鉴权: 仅管理员

列出我的 AI 会话

GET/api/v2/ai/conversations

鉴权: 用户

查询参数

字段	类型	必填	说明
page	integer	—	页码,从 1 开始。默认 `1`
page_size	integer	—	每页条数。默认 `20`
q	string	—	按标题或消息正文的子串搜。

获取我的 AI 会话

GET/api/v2/ai/conversations/{id}

鉴权: 用户

删除我的 AI 会话

DELETE/api/v2/ai/conversations/{id}

鉴权: 用户

获取我的助手外观

GET/api/v2/ai/look

鉴权: 用户

保存我的助手外观

PUT/api/v2/ai/look

鉴权: 用户

请求体 application/json

字段	类型	必填	说明
name	string	必填	助手名;空 = 用缺省名。
pet	AiPet	必填	助手形象:orb 光球、cat 猫、dog 狗、bot 机器人、ai 按 AI 定制的参数(spec)画。可选值 `["orb","cat","dog","bot","ai"]`
spec	AiLookSpec	—	AI 定制形象的参数清单(白名单内的取值,面板用固定的 SVG 部件按它画)。AiLook 里没有 = 没定制过。写外观时 pet=ai 或 theme=custom 必须带上(code=required),不带则沿用已存的那份;服务端按同一白名单再核并规整(颜色转小写、主色压暗到白字看得清)。
theme	AiTheme	必填	助手主题色:蓝、青、日落、莫兰迪、墨色,custom 取 AI 定制参数(spec)里的三色。只作用于助手面板自己。可选值 `["blue","teal","sunset","morandi","ink","custom"]`

取我上传的助手头像

GET/api/v2/ai/look/avatar

鉴权: 用户

上传我的助手头像

PUT/api/v2/ai/look/avatar

鉴权: 用户

移除我上传的助手头像

DELETE/api/v2/ai/look/avatar

鉴权: 用户

让 AI 按描述出一份定制形象

POST/api/v2/ai/look/generate

鉴权: 用户

请求体 application/json

字段	类型	必填	说明
text	string	必填	想要的样子,去掉控制字符与尖括号后最长 60 个字。

向 AI 助手发一句话

POST/api/v2/ai/messages

鉴权: 用户

请求体 application/json

字段	类型	必填	说明
context	AiContext	—	当前页面上下文:只有页名与打开的那条的 id,数据由服务端现取。首版带详细数据的页:home 首页、attack_logs 攻击记录(ref = 记录 id)、sites 网站列表(ref = 网站 id);其余页只带页名。
conversation_id	integer	—	接着哪段会话说;不带则开新会话(标题取这句的开头)。
text	string	必填	想要的样子,去掉控制字符与尖括号后最长 60 个字。

列出 AI 模型评分表

GET/api/v2/ai/models

鉴权: 仅管理员

取消 AI 助手的计划

POST/api/v2/ai/plans/cancel

鉴权: 用户

请求体 application/json

字段	类型	必填	说明
plan_id	AiPlanKey	必填	计划号(随机,32 位十六进制)。

执行 AI 助手的计划

POST/api/v2/ai/plans/execute

鉴权: 用户

请求体 application/json

字段	类型	必填	说明
password	string	—	当前登录口令。
plan_id	AiPlanKey	必填	计划号(随机,32 位十六进制)。
totp_code	string	—	动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。

修改 AI 助手计划的参数

POST/api/v2/ai/plans/revise

鉴权: 用户

请求体 application/json

字段	类型	必填	说明
domain	string	必填	网站域名。
origin	string	必填	源站地址(IP 或域名)。
plan_id	AiPlanKey	必填	计划号(随机,32 位十六进制)。
port	integer	必填	回源端口。
upid	integer	必填	用哪份已购套餐(须属计划的属主租户)。

获取 AI 助手的计划

GET/api/v2/ai/plans/{plan_id}

鉴权: 用户

获取 AI 助手接入设置

GET/api/v2/ai/settings

鉴权: 仅管理员

保存 AI 助手接入设置

PUT/api/v2/ai/settings

鉴权: 仅管理员

请求体 application/json

字段	类型	必填	说明
api_key	string	—	API 密钥;不传沿用已存的,传空串清掉(助手随之不可用)。只封存入库,不回显。
api_type	AiApiType	必填	接口类型:openai 为 OpenAI 兼容(/chat/completions,国内多数服务商也走它);claude 为 Anthropic 原生(/messages);moonshot 为 Kimi(OpenAI 兼容,预设地址不同)。可选值 `["openai","claude","moonshot"]`
base_url	string	—	服务地址(公网 HTTPS);从没保存过为空。
model	string	必填	模型名。

测试 AI 助手连接

POST/api/v2/ai/settings/probe

鉴权: 仅管理员

请求体 application/json

字段	类型	必填	说明
api_key	string	—	API 密钥;不传沿用已存的,传空串清掉(助手随之不可用)。只封存入库,不回显。
api_type	AiApiType	必填	接口类型:openai 为 OpenAI 兼容(/chat/completions,国内多数服务商也走它);claude 为 Anthropic 原生(/messages);moonshot 为 Kimi(OpenAI 兼容,预设地址不同)。可选值 `["openai","claude","moonshot"]`
base_url	string	—	服务地址(公网 HTTPS);从没保存过为空。
model	string	必填	模型名。

获取 AI 助手可用状态

GET/api/v2/ai/status

鉴权: 用户

AI 助手对象

字段	类型	必填	说明
api_key	string	—	API 密钥;不传沿用已存的,传空串清掉(助手随之不可用)。只封存入库,不回显。
api_type	AiApiType	—	接口类型:openai 为 OpenAI 兼容(/chat/completions,国内多数服务商也走它);claude 为 Anthropic 原生(/messages);moonshot 为 Kimi(OpenAI 兼容,预设地址不同)。可选值 `["openai","claude","moonshot"]`
available	boolean	—	是否显示并可用助手;代登录会话与本人一样。
avatar_ver	integer	—	头像版本;0 = 没传头像(显示所选形象),大于 0 时用 GET /ai/look/avatar 取图,换图后变大。
base_url	string	—	服务地址(公网 HTTPS);从没保存过为空。
cert_id	integer	—	申请的证书。
cname	string	—	建站响应给的接入名;等解析时让用户把域名 CNAME 到它。
code	string	—	失败细分:blocked 地址被拒(内网等)、auth 密钥被拒、rate_limited 上游限流、timeout 超时、refused 模型拒答、protocol 回包格式不对、http 其他状态码、connect 连不上。
connect_ms	integer	—	连通耗时毫秒(最近一次请求)。
context	AiContext	—	当前页面上下文:只有页名与打开的那条的 id,数据由服务端现取。首版带详细数据的页:home 首页、attack_logs 攻击记录(ref = 记录 id)、sites 网站列表(ref = 网站 id);其余页只带页名。
conversation_id	integer	—	接着哪段会话说;不带则开新会话(标题取这句的开头)。
created_at	string	—	创建时刻。
detail	string	—	给管理员看的说明(含上游错误摘要,不含密钥)。
domain	string	必填	网站域名。
error	string	—	失败原因。
error_code	string	—	失败原因里的错误码部分(步骤接口回的 code,或 no_cname)。
events	AiPlanEvent[]	—	每一步的记录,按先后(只在会话详情里给)。
expired	boolean	—	待执行但已过了执行期限(由服务端按 expires_at 算)。
expires_at	string	—	过了不能再执行。
fetched_on	string	—	取数日期。
first_token_ms	integer	—	已跑各轮里最慢的首字毫秒。
has_delegated	boolean	—	有代登录会话发的消息。
high_risk	boolean	—	执行前要当场复核本人。
id	integer	—	会话 id。
items	AiModel[]	—	按指数从高到低。
key_set	boolean	—	是否已设置 API 密钥(密钥本身不回显)。
kind	AiPlanKind	—	create_site 新增网站(先只开 HTTP,加好解析后再申请证书);delete_site 删除网站(高危,执行前复核本人)。可选值 `["create_site","delete_site"]`
last_plan	object	—	最近提出的一份计划;没有计划时不给。
message_count	integer	—	消息条数。
messages	AiMessage[]	—	全部消息(只在获取单个会话时有)。
model	string	—	模型名。
name	string	—	助手名;空 = 用缺省名。
ok	boolean	—	是否通过。
origin	string	必填	源站地址(IP 或域名)。
outdated	boolean	—	取数超过 90 天,面板提示「评分可能过时」。
params	AiPlanParams	—	冻结的计划参数。新增网站有 domain、origin、port、upid、package(管理员代建另有 tenant_id);删除网站有 site_id,site_name 与 domains 给人核对。
password	string	—	当前登录口令。
pet	AiPet	—	助手形象:orb 光球、cat 猫、dog 狗、bot 机器人、ai 按 AI 定制的参数(spec)画。可选值 `["orb","cat","dog","bot","ai"]`
plan_count	integer	—	提出的计划份数(含已被改参数取代的)。
plan_id	AiPlanKey	必填	计划号(随机,32 位十六进制)。
plans	AiPlan[]	—	这段对话提出的计划,按先后,含每一步记录(只在获取单个会话时有)。
port	integer	必填	回源端口。
probe_first_token_ms	integer	—	探测 3 轮里最慢的首字毫秒;没通过为 0。
probe_ok	boolean	—	保存时探测是否通过;换模型或密钥后清零。
probe_round_ms	integer	—	探测 3 轮里最慢的整轮毫秒;没通过为 0。
probed_at	string	—	探测通过的时刻;没通过为 null。
ready	boolean	—	设置是否可用(有密钥、有模型且探测通过);授权另判,见 /ai/status。
reason	string	—	不可用的原因:unlicensed 没开通;expired 授权已过期;not_configured 管理员还没接好模型;demo 演示模式;delegated 已不再返回(代登录会话现与本人一样可用),留着只为旧面板识别。可选值 `["unlicensed","expired","not_configured","delegated","demo"]`
reauth_methods	AiReauthMethod[]	—	高危计划可用的复核方式;不高危为空。
retention_days	integer	—	会话保留天数(配置 retention.ai_chat_days,按会话最后一条消息算,过了连同查询记录与计划一起清理)。
revoking_until	string	—	服务商已收回授权时,此刻前照常可用。
round_ms	integer	—	已跑各轮里最慢的整轮毫秒。
rounds	integer	—	跑完的轮数(通过时为 3)。
site_id	integer	—	建好的网站。
spec	AiLookSpec	—	AI 定制形象的参数清单(白名单内的取值,面板用固定的 SVG 部件按它画)。AiLook 里没有 = 没定制过。写外观时 pet=ai 或 theme=custom 必须带上(code=required),不带则沿用已存的那份;服务端按同一白名单再核并规整(颜色转小写、主色压暗到白字看得清)。
state	AiPlanState	—	proposed 待执行;running 执行中;wait_dns 网站已建、等用户加解析(再执行即申请证书);done 完成;failed 失败(见 error);cancelled 已取消;superseded 已被改参数后的新计划取代。可选值 `["proposed","running","wait_dns","done","failed","cancelled","superseded"]`
step	string	—	没通过时停在哪一步:connect 连不上或上游报错;tool 没按格式调用工具报数;echo 复述不对;first_token 首字超时;round 整轮超时。可选值 `["connect","tool","echo","first_token","round"]`
text	string	必填	想要的样子,去掉控制字符与尖括号后最长 60 个字。
theme	AiTheme	—	助手主题色:蓝、青、日落、莫兰迪、墨色,custom 取 AI 定制参数(spec)里的三色。只作用于助手面板自己。可选值 `["blue","teal","sunset","morandi","ink","custom"]`
title	string	—	标题(首条提问的开头)。
tool_calls	AiToolCall[]	—	只读查询记录,按先后(只在获取单个会话时有)。
tool_count	integer	—	只读查询次数。
totp_code	string	—	动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。
updated_at	string	—	最后一条消息时刻(保留期按它算)。
upid	integer	必填	用哪份已购套餐(须属计划的属主租户)。
usage	object	—	本人生成后的用量与额度(本次已计入)。
user_deleted	boolean	—	属主账号已删除(只在管理员接口里给)。
user_id	integer	—	会话属主(只在管理员接口里给)。
username	string	—	属主用户名(只在管理员接口里给;用户已删时为空)。
version	string	—	评分口径版本。

curl

# 列出全部用户的 AI 会话
curl "https://panel.example.com/api/v2/ai/admin/conversations" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 查看任一用户的 AI 会话
curl "https://panel.example.com/api/v2/ai/admin/conversations/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 列出我的 AI 会话
curl "https://panel.example.com/api/v2/ai/conversations" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 获取我的 AI 会话
curl "https://panel.example.com/api/v2/ai/conversations/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 删除我的 AI 会话
curl -X DELETE "https://panel.example.com/api/v2/ai/conversations/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 获取我的助手外观
curl "https://panel.example.com/api/v2/ai/look" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 保存我的助手外观
curl -X PUT "https://panel.example.com/api/v2/ai/look" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 取我上传的助手头像
curl "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 上传我的助手头像
curl -X PUT "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 移除我上传的助手头像
curl -X DELETE "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 让 AI 按描述出一份定制形象
curl -X POST "https://panel.example.com/api/v2/ai/look/generate" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 向 AI 助手发一句话
curl -X POST "https://panel.example.com/api/v2/ai/messages" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 列出 AI 模型评分表
curl "https://panel.example.com/api/v2/ai/models" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 取消 AI 助手的计划
curl -X POST "https://panel.example.com/api/v2/ai/plans/cancel" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 执行 AI 助手的计划
curl -X POST "https://panel.example.com/api/v2/ai/plans/execute" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 修改 AI 助手计划的参数
curl -X POST "https://panel.example.com/api/v2/ai/plans/revise" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 获取 AI 助手的计划
curl "https://panel.example.com/api/v2/ai/plans/{plan_id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 获取 AI 助手接入设置
curl "https://panel.example.com/api/v2/ai/settings" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 保存 AI 助手接入设置
curl -X PUT "https://panel.example.com/api/v2/ai/settings" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 测试 AI 助手连接
curl -X POST "https://panel.example.com/api/v2/ai/settings/probe" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 获取 AI 助手可用状态
curl "https://panel.example.com/api/v2/ai/status" \
  -H "X-API-Key: $GOCDN_API_KEY"