Label Extraction API
把一段脑电实验的任务描述，解析成结构化的任务分类、标签集合与标注粒度。 脑电数据里最贵的不是信号，是标签——这个接口解决的就是「标签从哪来」。 引擎与 BrainDataOS 的标签抽取 Agent 同一套规则口径，服务端计算，客户端不可篡改。
快速开始
三步接进来：签发密钥 → 发一个 POST → 拿到结构化标签。不需要安装 SDK，用 curl 就能验证。
密钥与配额
这个沙箱环境支持即时签发，无需审核。平台只保存密钥的 SHA-256 摘要，服务端无法反推明文—— 所以完整密钥只在签发和轮换时显示一次。
试运行
真实调用线上接口，不是本地模拟。响应里会带回本次消耗和剩余配额。
// 点左侧「发送请求」，这里会显示真实响应
confidence、
review_required 和 alternatives——
低于 0.5 置信度直接提示需要人工复核，候选答案摊开让下游自己判断。
产品设计上，这比假装 100% 准确要负责任。
— alternatives / review_required 是对原 CLI 版本的增量改进
接口参考
Base URL 与当前控制台同源。完整机器可读描述见 /openapi.json。
把一条实验描述解析为结构化标签。
{
"text": "participant performs left and right hand motor imagery",
"min_confidence": 0.45 // 可选，低于该值则抑制结果
}
{
"request_id": "req_00012_a3f1c9",
"input": "participant performs left and right hand motor imagery",
"task": "motor_imagery",
"task_category": "motor_imagery",
"labels": ["left_hand", "right_hand", "feet", "tongue", "rest"],
"label_type": "trial_level",
"matched_keyword": "motor imagery",
"confidence": 0.65,
"review_required": false,
"alternatives": [],
"evidence": { "text": "motor imagery", "span": { "start": 38, "end": 51 } },
"meta": { "engine": "rules", "version": "v1", "quota_remaining": 499 }
}
X-Quota-Limit: 500 X-Quota-Remaining: 499 X-RateLimit-Limit: 60
批量抽取，返回逐条结果与类别分布。批量计 1 次配额，是刻意的产品决策——鼓励合并请求，降低双方的连接开销。
{ "items": ["overnight polysomnography for sleep staging", "auditory oddball with P300"] }
{
"count": 2,
"results": [ { "index": 0, "task": "sleep_staging", ... }, ... ],
"summary": {
"category_distribution": { "sleep": 1, "attention": 1 },
"label_types": { "epoch_level": 1, "trial_level": 1 },
"review_required": 0,
"mean_confidence": 0.44
}
}
返回当前密钥的配额、已用量与重置日期。查询本身不计配额。
{
"key_id": "key_9f2c1a",
"prefix": "bdos_live_9f2c…7a1e",
"quota": { "limit": 500, "used": 12, "remaining": 488, "window": "monthly", "resets_on": "2026-12-01" },
"total_used": 12
}
沙箱环境即时签发。{"name":"my-app"} 仅用于标识，不影响权限。
{
"key": "bdos_live_5f3a…（完整值仅此一次）",
"id": "key_9f2c1a",
"preview_prefix": "bdos_live_5f3a…",
"quota": { "limit": 500, "window": "monthly", "rate_limit_per_min": 60 }
}
POST /v1/keys/rotate 轮换（旧值立即失效）、DELETE /v1/keys 吊销。均需 Bearer。
返回全部 23 条匹配规则：关键词 → 任务 → 标签集合 → 标注粒度。接口的判定逻辑是公开的，可被审计，这是做数据类平台的基本要求。
/health 用于探针与状态灯，同时暴露规则数与活跃密钥数；/v1/meta 返回版本、配额策略与全局调用量。
代码示例
示例里的密钥会随你在上方签发的密钥自动更新。
错误码
统一响应体 {request_id, error:{code,message,hint}}——前端可以按 code 分支处理，不用正则匹配文案。
| HTTP | code | 含义 | 怎么处理 |
|---|---|---|---|
| 400 | invalid_argument | 必填字段缺失或类型错误 | 检查 body 里的 text / items |
| 400 | invalid_json | 请求体不是合法 JSON | 检查引号转义与 Content-Type |
| 400 | text_too_long | 单条超过 2000 字符 | 拆条后走批量接口 |
| 400 | batch_too_large | 单批超过 50 条 | 分多次提交 |
| 401 | missing_key | 没有 Authorization 头 | 带上 Bearer 密钥 |
| 401 | invalid_key | 密钥不存在或已被轮换 | 使用最近一次签发的值 |
| 401 | revoked_key | 密钥已吊销 | 重新签发 |
| 413 | payload_too_large | 请求体超过 64KB | 拆分请求 |
| 429 | rate_limited | 超过 60 次/分钟 | 降低频率或改用批量 |
| 429 | quota_exceeded | 本月 500 次用尽 | 次月 1 日重置 |
| 404 | endpoint_not_found | 路径不存在 | 对照 /openapi.json |
| 500 | internal_error | 服务端异常 | 带 request_id 反馈 |
配额与限流
两套阈值解决两种滥用：配额防长期占用，限流防瞬时打爆。
| 维度 | 阈值 | 为什么这么定 |
|---|---|---|
| 月度配额 | 500 次 / 密钥 | 够一个人把整份数据集跑完，但不够被当成免费算力薅 |
| 分钟限流 | 60 次 / 分钟 | 批量接口已覆盖高吞吐场景，单条高频多半是脚本失控 |
| 批量折算 | 50 条 = 1 次 | 把成本推向「合并请求」，同时降低双方连接开销 |
| 用量查询 | 不计配额 | 计量本身不该成为被计量的成本 |
| 重置周期 | 每月 1 日 | 自然月边界，用户心智模型最清楚 |