模型与服务
检查服务状态
GET /health
GET /v1/health
两个接口都无需 API Key。服务运行时即使授权不可用也会返回 HTTP 200，因此需要同时检查两个字段；返回成功不代表模型已加载。
请求示例：
curl --fail-with-body "${EDGESPEAK_BASE_URL%/v1}/health"
curl --fail-with-body "$EDGESPEAK_BASE_URL/health"输出示例：
{
"status": "ok",
"license": "active"
}license 只有 active 与 inactive 两种值。在服务主机执行 edgespeak-cli status 可查看激活详情。
发现模型与能力
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"
}