模型与服务
检查服务状态
GET /health
GET /v1/health
两个接口都无需 API Key,只报告服务进程是否在运行。它们不连接授权服务,也不返回授权状态,所以授权服务慢或连不上时也会立即返回。返回成功不代表授权可用,也不代表模型已加载。
请求示例:
curl --fail-with-body "${EDGESPEAK_BASE_URL%/v1}/health"
curl --fail-with-body "$EDGESPEAK_BASE_URL/health"输出示例:
{
"capabilities": ["alignment_reference_formats", "alignment_pronunciation_union"],
"status": "ok"
}capabilities 列出本服务支持的可选能力。要查看激活状态,在服务主机执行 edgespeak-cli status。授权不可用时,需要授权的请求返回 license_required(403)或可重试的 license_* 码(503)。
查看用量
GET /v1/usage
读取服务的用量汇总,不启动推理、不消耗额度。网关开启认证时须传网关令牌。refresh=true 会先尝试在线刷新授权;刷新失败仍返回本地汇总,因此不能据此证明在线授权成功。查询参数只接受 refresh=true|false,默认 false;未知或非法参数返回 400。此接口需要包含用量报告功能的运行时。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/usage?refresh=true"输出示例(节选;数值仅作示意,不代表当前套餐价格):
{"plan":"basic","period":{"start":"2026-10-15T00:00:00Z","resetsAt":"2026-11-15T00:00:00Z"},"allowance":{"period":1000000,"addonBalance":0},"used":{"total":120000},"remaining":{"period":880000,"addon":0,"total":880000},"state":"ok"}未激活账号时 plan 为 null。不限额度时,周期额度和剩余值可为 null。读取 period.resetsAt 获得实际计费周期边界,不按自然月推算,也不因更换 SDK 密钥重置用量。完整响应还包含按能力/来源分类、每日历史和同步状态;用量汇总字段保留既有 camelCase 名称。
发现模型与能力
GET /v1/models
模型目录列出服务已知的模型,也可能包含未下载或未加载的条目。调用时可按 supported_endpoints 选择接口,参考 default_for 获取默认模型,并在发送请求前检查 execution_location。下方为单条记录节选,实际目录内容因环境而异。对齐模型的 supported_endpoints 包含 /v1/audio/alignments;该选哪一档见对齐请求。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/models"输出示例:
{
"object": "list",
"data": [
{
"id": "Qwen/Qwen3.5-4B",
"object": "model",
"created": 0,
"owned_by": "EdgeSpeak",
"supported_endpoints": [
"/v1/chat/completions",
"/v1/responses",
"/v1/messages",
"/v1/tokenize"
],
"features": [
"reasoning",
"vision",
"tool_calling"
],
"execution_location": "local",
"default_for": []
}
]
}调用后续接口时,请使用模型目录中实际存在的 ID。local 模型在服务主机执行;配置为 remote 的模型会接收该请求。内置 EdgeSpeak/Skylark 已经可用,不支持下载、加载或卸载。语音模型与语言模型的生命周期能力可能不同;下面的顺序适用于支持这些操作的本机语言模型。
开始下载模型
POST /v1/models/download
下载会占用服务主机的网络与磁盘空间。此接口会启动后台任务并返回 202 Accepted,不代表模型已可推理。四个 POST 生命周期接口都只接受 {"model":"目录 ID"},传入额外字段会被拒绝。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/download" \
-H "Content-Type: application/json" \
-d '{"model":"Qwen/Qwen3.5-4B"}'输出示例:
{
"model": "Qwen/Qwen3.5-4B",
"state": "downloading",
"bytes_downloaded": 0,
"total_bytes": 0,
"error": null
}total_bytes: 0 可能表示尚未获取到总大小。加载模型前,先通过查询接口轮询进度。
查询下载进度
GET /v1/models/downloads
可每秒查询一次,按 model 找到对应任务;返回空列表不代表模型已安装。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/downloads"输出示例:
{
"object": "list",
"data": [
{
"model": "Qwen/Qwen3.5-4B",
"state": "completed",
"bytes_downloaded": 2500000000,
"total_bytes": 2500000000,
"error": null
}
]
}状态包括 downloading、completed、failed、cancelled。这里的字节数仅为示意。下载失败时可读取 error 字段;重试需重新发起 POST 请求。
取消进行中的下载
POST /v1/models/download/cancel
此接口仅适用于进行中的任务,取消过程同样异步完成。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/download/cancel" \
-H "Content-Type: application/json" \
-d '{"model":"Qwen/Qwen3.5-4B"}'输出示例:
{
"model": "Qwen/Qwen3.5-4B",
"state": "cancelling"
}继续查询 /models/downloads,直到任务进入终态。
加载本机模型
POST /v1/models/load
下载完成后,需先加载模型再调用语言生成或 Realtime;此操作会在服务主机分配内存。响应示例展示稳定的核心字段,服务主机可能另外返回扩展字段。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/load" \
-H "Content-Type: application/json" \
-d '{"model":"Qwen/Qwen3.5-4B"}'输出示例:
{
"success": true,
"model": "Qwen/Qwen3.5-4B",
"status": "loaded"
}查看运行中的模型
GET /v1/models/running
模型出现在目录中并不代表已就绪,用这个接口查运行状态。示例展示加载成功后的状态,各条目的 status 内容依模型而定。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/running"输出示例:
{
"object": "list",
"data": [{"id":"Qwen/Qwen3.5-4B","status":{"value":"loaded"}}],
"runtime": {
"state": "running"
}
}若 data 为空且运行时不处于 loading,需先加载模型,再发起 Realtime 生成。
请求队列状态
同一个鉴权接口在 Headless 服务上提供 runtime.queues,桌面网关不含该字段。以下为 jq 提取后的响应节选:
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/running" \
-H "Authorization: Bearer $EDGESPEAK_API_KEY" | jq '.runtime.queues.native_broadcast'{"active":1,"waiting":3,"execution_capacity":1,"oldest_wait_ms":1200}冷加载或切换模型期间,runtime.state 可为 loading。此时模型列表暂时为空,但依然会返回队列;不要把暂时为空的列表当作卸载完成。
每个队列都包含 active、waiting、execution_capacity 与 oldest_wait_ms。http_transcribe、http_alignment、http_segmentation、http_normalization、http_diarization、http_speaker_embedding、http_broadcast 和 http_realtime 属于入口调度队列;native_transcribe / native_broadcast 则是跨 REST、Realtime、MCP 和预加载的原生模型占用。active 包含已获准但仍在准备或收尾的任务,不等同于 GPU 并发推理数。同一任务可能同时出现在两层队列中,不能把各队列数值相加作为请求总数。排在全局上传槽之前的等待不计入这些统计。
取消等待中的操作会移除其登记;已启动的阻塞任务可能继续执行,直到完成或原生取消收尾。Realtime 会话会持续占用直到会话关闭,切换转录模型可能因此等待较久。配置详情见并发与睡眠参数。
卸载运行中的模型
POST /v1/models/unload
不再使用模型时可通过此接口释放内存,这不会删除已下载的文件。活跃会话可能阻止卸载;请在结束会话后重试。响应示例展示核心字段。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/unload" \
-H "Content-Type: application/json" \
-d '{"model":"Qwen/Qwen3.5-4B"}'输出示例:
{
"success": true,
"model": "Qwen/Qwen3.5-4B",
"status": "unloaded"
}