模型与服务

检查服务状态

GET /health

GET /v1/health

两个接口都无需 API Key,只报告服务进程是否在运行。它们不连接授权服务,也不返回授权状态,所以授权服务慢或连不上时也会立即返回。返回成功不代表授权可用,也不代表模型已加载。

请求示例:

Shell
curl --fail-with-body "${EDGESPEAK_BASE_URL%/v1}/health"
curl --fail-with-body "$EDGESPEAK_BASE_URL/health"

输出示例:

JSON
{
  "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。此接口需要包含用量报告功能的运行时。

请求示例:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/usage?refresh=true"

输出示例(节选;数值仅作示意,不代表当前套餐价格):

JSON
{"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;该选哪一档见对齐请求。

请求示例:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/models"

输出示例:

JSON
{
  "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"},传入额外字段会被拒绝。

请求示例:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/download" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B"}'

输出示例:

JSON
{
  "model": "Qwen/Qwen3.5-4B",
  "state": "downloading",
  "bytes_downloaded": 0,
  "total_bytes": 0,
  "error": null
}

total_bytes: 0 可能表示尚未获取到总大小。加载模型前,先通过查询接口轮询进度。

查询下载进度

GET /v1/models/downloads

可每秒查询一次,按 model 找到对应任务;返回空列表不代表模型已安装。

请求示例:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/downloads"

输出示例:

JSON
{
  "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

此接口仅适用于进行中的任务,取消过程同样异步完成。

请求示例:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/download/cancel" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B"}'

输出示例:

JSON
{
  "model": "Qwen/Qwen3.5-4B",
  "state": "cancelling"
}

继续查询 /models/downloads,直到任务进入终态。

加载本机模型

POST /v1/models/load

下载完成后,需先加载模型再调用语言生成或 Realtime;此操作会在服务主机分配内存。响应示例展示稳定的核心字段,服务主机可能另外返回扩展字段。

请求示例:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/load" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B"}'

输出示例:

JSON
{
  "success": true,
  "model": "Qwen/Qwen3.5-4B",
  "status": "loaded"
}

查看运行中的模型

GET /v1/models/running

模型出现在目录中并不代表已就绪,用这个接口查运行状态。示例展示加载成功后的状态,各条目的 status 内容依模型而定。

请求示例:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/running"

输出示例:

JSON
{
  "object": "list",
  "data": [{"id":"Qwen/Qwen3.5-4B","status":{"value":"loaded"}}],
  "runtime": {
    "state": "running"
  }
}

若 data 为空且运行时不处于 loading,需先加载模型,再发起 Realtime 生成。

请求队列状态

同一个鉴权接口在 Headless 服务上提供 runtime.queues,桌面网关不含该字段。以下为 jq 提取后的响应节选:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/running" \
  -H "Authorization: Bearer $EDGESPEAK_API_KEY" | jq '.runtime.queues.native_broadcast'
JSON
{"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

不再使用模型时可通过此接口释放内存,这不会删除已下载的文件。活跃会话可能阻止卸载;请在结束会话后重试。响应示例展示核心字段。

请求示例:

Shell
curl --fail-with-body "$EDGESPEAK_BASE_URL/models/unload" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3.5-4B"}'

输出示例:

JSON
{
  "success": true,
  "model": "Qwen/Qwen3.5-4B",
  "status": "unloaded"
}

继续阅读:文本处理 · API 索引