本地服务 API 参考

OpenASR 可以在本机启动 HTTP 服务，方便现有应用通过统一接口调用本地语音识别能力。

openasr serve

默认监听 127.0.0.1:8080，仅本机可访问。如果要监听非回环地址，必须启用 --tls-self-signed（或配置其他 TLS 方案）并使用配对认证。具体参数以 openasr serve --help 为准。

鉴权

服务端支持三种鉴权模式：

无鉴权（默认）：仅回环地址可访问，不需要密钥。
Bearer Token：通过 openasr apikey create/list/revoke 管理静态密钥（存储侧仅保留 SHA-256 哈希）。任何持有有效密钥的请求均可调用所有接口。
配对模式：维护一个管理员令牌和一套设备配对凭证注册表。此模式下，下表标记为「仅管理员」的接口拒绝配对设备令牌，返回 403 Forbidden（authorization_error）；仅管理员令牌可调用。

/health 在任何模式下均无需认证。缺少或无效凭证返回 401 Unauthorized（authentication_error，附 WWW-Authenticate: Bearer 头）。

完整路由表

「仅管理员」列仅在配对模式下生效。使用单一 Bearer Token 模式时此区分不适用。

方法	路径	仅管理员
GET	`/health`
GET	`/v1/capabilities`
GET	`/v1/devices`
GET	`/v1/models`
GET	`/v1/catalog`
GET	`/v1/config`	✓
PUT	`/v1/config`	✓
GET	`/v1/history`	✓
GET	`/v1/history/{id}`	✓
DELETE	`/v1/history/{id}`	✓
GET	`/v1/speakers`	✓
POST	`/v1/speakers`	✓
PATCH	`/v1/speakers/{id}`	✓
DELETE	`/v1/speakers/{id}`	✓
POST	`/v1/speakers/{id}/reenroll`	✓
GET	`/v1/models/local`
POST	`/v1/models/local/import`	✓
GET	`/v1/models/default`
POST	`/v1/models/default`	✓
PUT	`/v1/models/default`	✓
DELETE	`/v1/models/{id}`	✓
POST	`/v1/models/{id}/pull`	✓
GET	`/v1/models/pull/{job_id}`
GET	`/v1/models/pull/{job_id}/events`
POST	`/v1/models/pull/{job_id}/cancel`	✓
POST	`/v1/models/pull/{job_id}/pause`	✓
POST	`/v1/models/pull/{job_id}/resume`	✓
POST	`/v1/pairing/requests`
GET	`/v1/pairing/requests`	✓
POST	`/v1/pairing/requests/{request_id}/approve`	✓
DELETE	`/v1/pairing/requests/{request_id}`	✓
GET	`/v1/pairing/requests/{request_id}/credential`	*
GET	`/v1/pairing/credentials`	✓
DELETE	`/v1/pairing/credentials/{device_id}`	✓
POST	`/v1/audio/transcriptions`
GET	`/v1/audio/transcriptions/progress`
POST	`/v1/audio/transcriptions/{id}/cancel`
POST	`/v1/audio/transcriptions/{id}/pause`
POST	`/v1/audio/transcriptions/{id}/resume`
POST	`/v1/audio/translations`
ANY	`/v1/audio/realtime`

* 该接口的访问权限取决于配对流程状态。

设计原则：模型/目录列表和能力查询对配对计算设备保持开放；管理员的本地数据（历史、配置、说话人）和所有模型变更操作则仅管理员可调用。

转写

curl -s http://127.0.0.1:8080/v1/audio/transcriptions \
  -F [email protected] \
  -F model=whisper-small \
  -F response_format=json

response_format 支持 json、text、srt、vtt、verbose_json、markdown。接口格式兼容 OpenAI 音频转写接口子集，迁移现有调用时通常只需修改服务地址并确保模型已安装。

任务控制

GET /v1/audio/transcriptions/progress — 查询当前转写任务进度（phase、fraction、done、total）；无任务运行时各字段为零值。短音频单次解码不暴露子步骤，客户端可按经过时间自行估算。
POST /v1/audio/transcriptions/{id}/cancel — 在下一个长音频切片边界取消任务；已解码片段将被丢弃。
POST /v1/audio/transcriptions/{id}/pause — 暂停；解码线程阻塞直到收到 resume 或 cancel。
POST /v1/audio/transcriptions/{id}/resume — 恢复暂停的任务，从下一个切片继续，保留已积累的片段。

客户端中途断开连接时，进行中的解码会通过 RAII 自动取消，不会泄漏解码线程。

翻译

POST /v1/audio/translations 与转写接口用法一致，但固定将源语言音频翻译为英文（对齐 OpenAI translations 接口约定），依赖 Hy-MT2 等具备翻译能力的模型包。

流式接口

GET /v1/audio/realtime 升级为 WebSocket，用于流式转写；已安装翻译模型时还会同步输出流式翻译。以增量事件（VAD、部分/最终转写片段、语音边界等）推送结果，无需等待整段音频处理完成。

配置

GET /v1/config — 返回完整的配置文档（配置 + 偏好设置）。
PUT /v1/config — 接受完整配置文档，或仅包含偏好字段的局部更新（如 {"preferences": {"diarize": true}}）。局部更新只覆盖指定字段，不会重置其他偏好。写入前会校验模型注册表/目录。

详见配置参考。

历史记录

GET /v1/history — 分页列出历史转写/翻译任务。支持 search、kind（file 或 live，其他值返回 400）、limit（默认 50，最大 500）、offset 查询参数。返回 {object, data, total, limit, offset}。列表按 history_retention 偏好自动剪裁。
GET /v1/history/{id} — 单条记录详情；不存在时返回 404。
DELETE /v1/history/{id} — 删除单条记录；返回 {deleted: true, id}。

说话人

GET/POST /v1/speakers、PATCH/DELETE /v1/speakers/{id}、POST /v1/speakers/{id}/reenroll 提供说话人的列出、创建、重命名、删除和重新注册功能。详见说话人分离。

模型管理

GET /v1/catalog — 返回签名的模型目录（可用模型、量化版本、许可证）。
GET /v1/models/local — 列出已安装的模型包，每个包附带 is_default 标志。
GET /v1/models/default — 返回当前默认模型包。
POST /v1/models/default / PUT /v1/models/default — 设置默认模型（按 id 或自动选择已安装的最佳量化版本）。
DELETE /v1/models/{id} — 删除已安装的模型包；若该包是默认模型，同时清除默认选择。
POST /v1/models/local/import — 从本机磁盘上已有的 .oasr 文件安装模型包，不联网。

拉取任务

POST /v1/models/{id}/pull — 启动异步下载任务（请求体可含 quant、size、accept_license、from）。模型包已安装时返回 200；否则返回 202 Accepted 及排队任务快照。许可证受限模型需 accept_license: true，否则 400。
GET /v1/models/pull/{job_id} — 任务状态快照（job_id、state、model_id、display_name、quant、bytes_done、bytes_total、speed_bps、eta_s、installed、error 等）。
GET /v1/models/pull/{job_id}/events — Server-Sent Events 流式推送下载进度。
POST /v1/models/pull/{job_id}/cancel / pause / resume — 任务生命周期控制。

设备配对

配对机制允许远程计算设备安全接入服务端。配对请求 ID 为 32 位十六进制，设备 ID 为 24 位十六进制。远程计算客户端在请求中附带 x-openasr-remote-compute: client 头。

POST /v1/pairing/requests — 远程设备发起配对请求（无需认证），返回 202。
GET /v1/pairing/requests — 管理员列出待处理的配对请求。
POST /v1/pairing/requests/{request_id}/approve — 批准请求并签发设备凭证。
DELETE /v1/pairing/requests/{request_id} — 拒绝/移除请求。
GET /v1/pairing/requests/{request_id}/credential — 获取已批准请求的凭证。
GET /v1/pairing/credentials — 列出所有已签发的设备凭证。
DELETE /v1/pairing/credentials/{device_id} — 吊销设备凭证。

功能与设备查询

GET /v1/capabilities — 返回当前绑定模型/后端的能力描述（transcription、realtime），派生自已绑定 .oasr 包的能力声明。
GET /v1/devices — 枚举硬件/计算设备信息（default_execution_target、devices），供界面的执行目标选择器使用；返回的是守护进程自身 ggml 运行时检测到的真实设备列表。

`/health`

curl -s http://127.0.0.1:8080/health

除 status、server_version、pid、instance_token 之外，响应中还包含以下字段，用于排查模型驻留和闲置行为：

model_installed（bool）：是否已绑定模型。全新安装尚未拉取任何模型时为 false；此时守护进程仍然健康，只是暂时没有可用模型。
model_resident（bool）：模型运行时是否驻留内存。model_installed: true, model_resident: false 表示模型已绑定但运行时已被卸载（闲置超过 idle_unload 阈值或本次启动后尚未加载），下一次请求需要冷加载，这是预期行为。
native_active_count（u64）：当前活跃的请求/会话数，离线转写、翻译以及已连接的实时流式会话均计入。可用于排查 idle_unload 为何尚未触发。
idle_seconds（u64）：活跃计数上一次归零后经过的秒数（有活跃请求时恒为 0）。可与 idle_unload 阈值对比，判断距离下次回收还有多久。
abandoned_worker_count（u64）：被看门狗判定为永久卡死的解码 worker 数。正常为 0；非零值强烈提示 GPU/驱动层面的解码卡死。该计数达到内部阈值后守护进程会主动退出，由上层进程管理器重启。

闲置卸载

服务端在模型闲置一段可配置的时间（idle_unload）后自动卸载运行时以释放内存——模型包保留在磁盘上，下次请求重新加载即可。默认阈值为闲置 10 分钟；其他可选值：never（从不卸载）、now（约 5 秒）、2m、1h。

模型与网络行为

服务端使用与 CLI 相同的 native 后端，在本机运行 ggml 支持的模型包。模型必须已安装，或在启动时通过 --model-pack 明确指定。

普通转写请求不会触发模型下载。服务端唯一会从网络下载模型的入口是需要管理员认证的 POST /v1/models/{id}/pull 拉取接口；POST /v1/models/local/import 只从磁盘已有文件安装，同样不联网。服务本身不包含遥测。

可用模型见模型页面，CLI 的安装和管理命令见 CLI 参考。