BX3F9K2M7Q4A，永久有效，充值查账都用它）bx- 开头，只在申请成功那一刻显示一次，请立即复制保存到安全的地方）https://3w.chat/chat.html?app=您的编号| 项目 | 说明 |
|---|---|
| 接口地址 | https://3w.chat/ask/（POST，JSON） |
| 认证方式 | 请求头 X-BX-Key: 你的API密钥 |
| 内容类型 | Content-Type: application/json |
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| q | string | 是 | 用户问题，最长 500 字（超出自动截断） |
| app | string | 否 | 您的 APP 编号，用于归属统计（强烈建议带） |
| conv_id | string | 否 | 对话ID（自己生成，字母数字），带上下文时同一对话用同一个 ID |
| ctx | array | 否 | 最近对话上下文 [{"who":"user","text":"…"}]，最多4轮，AI 会参考 |
curl -X POST https://3w.chat/ask/ \\
-H "Content-Type: application/json" \\
-H "X-BX-Key: bx-你的密钥" \\
-d '{"q":"会员多少钱一个月","app":"BX3F9K2M7Q4A","conv_id":"conv001"}'为避免超时，采用"两步取件"：第一次调用立即返回查询中状态，之后用相同问题再次调用取结果：
// 第一次调用，立即返回：
{"ok":true,"pending":true,"answer":"收到，正在帮您翻官方公告…"}
// 通常 30~60 秒后，再次调用相同请求，返回结果：
{"answer":"根据《会员服务说明》公告：基础版每月5元…",
"sources":[{"title":"会员服务说明","url":"https://…"}]}
// 未完成时继续返回 pending:true| code | 含义 | 处理建议 |
|---|---|---|
| RC-2101 | 访问受限 | 检查调用来源网络环境 |
| RC-2102 | 密钥无效或系统繁忙 | 先核对密钥；多次出现请到控制台重置密钥 |
| RC-2201 | 调用过于频繁 | 单密钥 60 次/分钟突发限流，降低调用频率；网页模式套餐额度用尽不会返回本错误码，而是正常响应并自动降级原文模式（见第七节） |
| RC-2301 | 访问受限 | 稍后再试；持续出现请检查调用来源 |
| RC-2401 | 服务维护中 | 稍后再试 |
| RC-2501 | API 余额用尽 | 已暂停服务；充值后即刻恢复 |
所有错误均返回 HTTP 200 + 上述 code + 随机参考号（E-XXXX），不暴露拦截细节。
平台对确认存在异常行为、违规或已处置的应用，会在应用广场、应用详情与客服页旁公开一个状态标签，用户与开发者均可看到，数据直接来自平台记录（GET /ask/apps 与 GET /ask/app-info 同步返回）：
以下接口均 POST JSON，鉴权方式与主 API 相同（token 登录态，或 app+key）：
| 接口 | 参数 | 说明 |
|---|---|---|
| /ask/console/apps | token | 本人全部应用列表（含已删除），含状态/时间/密钥指纹/平台标记（mark、mark_label） |
| /ask/console/reset-key | token, app | 重置密钥，返回新密钥（仅此一次） |
| /ask/console/del-app | token, app | 删除应用（软删除） |
| /ask/console/export | token, app | 导出应用数据（知识库+配置，不含密钥） |
| /ask/console/stats | token, app(可空=全部), days(7/14/30/90) | 评价统计：三档计数、好评率、原因排名、建议原文 |
GET /ask/app-info?app=编号：status（deleted=已删除 / banned=已封禁 / offline=已下架；正常时不返回此字段）、del_ts（删除时间戳）、mark 与 mark_label（公开状态标记：warn=重点关注 / offline=已下架 / banned=已封禁，无标记时为空）、faqs（常见问题列表，来自你的知识库，聊天页自动展示为快捷按钮）。
POST /ask/ 会直接返回"服务已停止"提示，不再产生问答与计费；"重点关注"不影响服务。为合规起见，系统不直接抓取第三方论坛板块。开发者可提供一个自己有权访问的数据接口，系统每日自动增量拉取（按标题去重）：
{"title":"标题","text":"正文","url":"可选原文链接"}；示例（可直接部署为静态 JSON 文件）：你的服务器上放一个 docs.json，内容 [{"title":"会员价格","text":"会员5元每月…","url":"https://…"}]，控制台填该文件地址即可。
在控制台"方式二"填入地址后会立即试拉一次；失败时不再只给一句笼统提示，而是直接显示失败环节，便于自查：
data / list / items 数组字段，每条含 title 与 text（最多取前 50 条）。用户提问命中已配置回调的技能时，AI 的回答开头会自动注明「（已自动调用技能「技能名」为您获取实时信息）」——这是默认且不可关闭的合规要求，确保用户知情。
控制台「工单」标签页底部可设置勿扰时段（开始/结束时间+周一至周日勾选）。生效期间：用户端显示"非开发者工作时间"提示，用户仍可留言（工单正常创建），但邮件通知会在你设定的结束时间后自动补发。
用户与开发者可在「我的中心」查看被处罚记录（处罚原因、处罚详情、处罚结果、预计解除时间，精确到秒）。账号处罚（举报属实自动处理）默认 15 天，到期登录时自动解除；应用下架需邮件申诉复核。开发者也可在控制台「应用管理」查看每个应用的处罚详情。
平台处置（状态标记、下架、封禁、申诉复核）由平台的风控系统按预设规则在服务器侧自动执行：命中风险规则（内容违规、密钥爆破、异常扫描、关联违规等）且风险分达到阈值即自动处置——关联应用下架、关联账号封禁（含不定长期限），处置依据、结果与解除时间会写入你的处罚记录并邮件通知你。开发者侧不提供任何管理接口，也没有可被冒用的管理口令；你只需要关注自己应用的状态与处罚记录。对处置有异议的，请通过工单或邮件申诉，复核时限 3 个工作日，复核成立会解除处置并恢复服务。
用户举报应用：POST /ask/report，参数 id（对话ID）、reason（违法违规/色情低俗/诈骗/侵权/辱骂攻击/其他）、detail（补充说明，选填）、email（联系邮箱，选填——接收处理结果）。系统自动核查对话记录后处理，结果邮件回复。
开发者举报用户：控制台「工单处理」里每个工单有"举报用户"按钮；程序调用加 mode=dev、app、token（需登录态）。系统核查对话后，属实则暂停该用户账号，结果邮件回复开发者。
状态流转：待处理 → 处理中 → 待确认 → 已解决 / 已关闭。开发者回复工单后自动进入"处理中"；标记解决后进入"待确认"，用户可点"确认已解决"或直接回复（回复即自动重开）；优先级 P1-P3 可调；类型标签（使用咨询/问题反馈/功能建议/其他）随建单生成。
独立对话页：控制台「工单处理」点"对话"进入独立工单对话页（/ticket-view.html），完整对话流、状态徽章、操作按钮、双方回复都在一个页面。用户在"我的工单"里点"查看对话"进入同一页面（用户视角，含确认解决按钮）。
| 接口 | 参数 | 说明 |
|---|---|---|
| POST /ask/ticket/set | num, app, token, act | 状态操作。开发者：start/waiting/solve/close/reopen/P1/P2/P3；用户：confirm（确认解决） |
| POST /ask/ticket/msg | num, app, token|key|cid | 读工单对话流（含状态/标题/类型/优先级） |
curl -X POST https://3w.chat/ask/ticket \\
-H "Content-Type: application/json" \\
-d '{"id":"对话ID","title":"问题标题","body":"详细描述",
"contact":"用户联系方式(选填)","imgs":[]}'技能 = 你自己的接口。用户提问命中技能关键词时，应答台会向你的回调地址发一个签名 POST 请求，你的系统返回结果文本，AI 把结果纳入上下文一起作答——即 function calling 的"只读自动执行"档。
在控制台「私有技能登记」填写：
应答台向你 POST 一个 JSON（UTF-8）：
{
"app": "BX你的编号",
"skill": "技能名称",
"q": "用户原话（最多300字）",
"ts": 1792050355
}
请求头两个自定义字段：
X-BX-Skill：技能名的 URL 编码（HTTP 头只允许 ASCII，中文被转义；body 里的 skill 字段是原文，直接用 body 的即可）；X-BX-Sign：签名，算法见下。签名 = sha256( 技能名 + 请求原始body字符串 + csec ) 的十六进制，取前32位
HTTP 200 + 纯文本或 JSON 皆可，1500 字以内，超时上限 8 秒（超时或非 200 = 本次跳过该技能，不影响正常问答）。返回内容会以"技能执行结果"注入 AI 上下文。请返回面向用户的陈述句（如"您的快递已到成都转运中心，预计明天送达"），不要返回原始 JSON。
from flask import Flask, request, abort
import hashlib, json
CSEC = "你登记时填的签名密钥"
SKILL = "查快递"
app = Flask(__name__)
@app.post("/skill")
def skill():
raw = request.get_data(as_text=True) # 原始body，一字不改
d = json.loads(raw)
name = d.get("skill") or "" # 用body里的原文技能名
sign = hashlib.sha256((name + raw + CSEC).encode()).hexdigest()[:32]
if sign != request.headers.get("X-BX-Sign", ""):
abort(401) # 验签失败拒绝
q = d.get("q", "")
# ==== 你的业务逻辑：解析q里的单号、查你自己的库 ====
return "您的快递已到成都转运中心，预计明天送达"
app.run(port=9000)
控制台「客服设置」标签，或程序调用：
| 接口 | 参数 | 说明 |
|---|---|---|
| POST /ask/console/bot-set | token, app, opening(≤50字), fallback(≤50字), vertical(≤200字) | 自定义开场白（留空用默认）、答不上来时的回复、垂直领域（注入 AI 角色设定，API 与网页模式通用） |
| GET /ask/console/contacts | app, token | 回显联系方式与设置 |
| POST /ask/console/contacts | token, app, pub, contacts[], imgs{序号:dataURL} | 保存联系方式（最多6条；预设：微信二维码/QQ二维码/手机号/邮箱/QQ账号；或自定义名称+内容，URL 自动可点击；二维码需 PNG/JPG ≤300KB 并填写图片用途说明——供读屏用户理解）。pub=true 时在应用广场与客服页公开展示，并提供一键复制 |
用户侧：GET /ask/app-info 新增 contacts（公开时返回）与 has_contacts；二维码图片地址 /ask/contact-img?app=编号&i=序号（PNG，5分钟缓存）。
技能网页模式与 API 模式通用：用户问题命中技能关键词时，无论来自内置客服链接还是 API 调用，系统都会自动签名调用你配置的回调地址取数，并在回答中声明。技能登记本身也支持两种方式：控制台「技能登记」标签，或程序调用 POST /ask/console/skill（带 app+key）。
查询类技能的标准流程（与主流客服系统一致）：用户问"查会员"→ 你的回调返回"请提供需要查询的对应账号"→ AI 转述给用户 → 用户直接回复"13800138000"→ 系统识别到这是本技能的补充信息，自动把上一句问题 + 本句补充（如"查会员 13800138000"）再次发给你的回调 → 你返回查询结果 → AI 答复用户。无需任何额外配置。
资金操作红线（行业惯例）：涉及支付、扣费、退款等资金敏感操作，请让回调返回支付链接或办理入口，由用户本人自行完成。机器人只递链接，不代执行资金操作。
用户问题包含技能名称，或描述前 20 字内的任一空格分隔关键词（≥2字）即触发。示例：技能"查快递"、描述"快递 物流 单号 查询"——用户问"帮我查快递，单号SF123"即命中。一个应用可登记多个技能，按登记顺序匹配第一个命中的。
技能函数调用通道是平台面向开发者的核心开放能力：不依赖服务器出口IP，不受IP与机房拦截约束，机房环境可正常使用。
技能调用（用户问题命中你配置的回调地址并取回结果）按 token 独立计费，不再占用套餐次数，与 API 调用共享预充值余额：
api_balance 扣除（按第七节峰谷价格表计价），明细记入账单中心，类型标注"技能消耗"。| 档位 | 价格 | 额度 | 超额行为 |
|---|---|---|---|
| 体验版 | 0 元 | 每天 20 问 | 当日超额自动降级为原文模式（仅返回知识库原文片段），次日恢复 |
| 基础版 | 9.9 元/月 | 500 问/月 | 当月超额降级原文模式，次月1日恢复 |
| 专业版 | 29.9 元/月 | 2000 问/月 | 同上 |
套餐由站长人工开通（付款后报 12 位 APP 编号），开通即刻生效并邮件确认。额度系统自动强制执行，超额不会中断服务。仅约束网页模式内置客服；API 程序调用不受此限制，按 token 计费（见下）。
按 token 计费，用多少扣多少，预充值（¥10 / ¥50 / ¥100 三档）。余额扣完自动停机（RC-2501），充值恢复。价格分高峰/低谷两档（北京时间）：
| 时段（北京时间） | 输入（每百万 tokens） | 输出（每百万 tokens） |
|---|---|---|
| 高峰：工作日 9:00-12:00、14:00-18:00 | ¥4.0 | ¥16.0 |
| 低谷：其余时段（含周末与法定节假日全天） | ¥2.0 | ¥8.0 |
confirm_human: true 与工单链接，开发者可引导终端用户跳转提交工单；工单通知默认发开发者账号邮箱，也可在申请时备注自定义接收邮箱（联系站长配置）。POST /ask/report（带对话 id 与原因）对 API 会话同样生效，系统核查对话记录后自动处置，结果邮件回执。POST /ask/eval（带对话 id、app、满意度）对 API 会话同样生效，数据进控制台「评价数据」。开发者平台对服务器IP、数据中心机房网络实施安全拦截，用于降低自动化与黑产流量对平台的影响。当您的出口IP命中机房规则或平台拦截规则时，直接访问开发者平台官网或平台API可能受限，此时可以使用以下替代接入方法继续完成接入与维护：
申请应用时可同时提交签名密钥与回调地址，用于后续回调验证与安全通信。格式要求：
自技能函数调用通道开放起，平台要求所有 AI 实际操作遵循「实时描述 → 确认授权 → 高危二次确认 → 过程不可关闭展示 → 全程审计」的链路：