服务目录查询 API

面向登录用户读取服务目录、可用 provider 和默认服务选择。

基础信息

• 基础路径：/services
• 认证方式：JWT Bearer Token 或 API Key（combinedAuth）。

端点

补充端点

本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。

GET /services/defaults/:serviceType

读取指定服务类型的默认 Provider / Offering。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
serviceType	服务类型

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

---

GET /services/offerings

读取当前可用服务目录。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

---

GET /services/providers

读取当前可用服务 Provider。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

---

POST /services/passthrough/asr/transcriptions

移动端云端 ASR 业务包装接口。客户端使用 JWT 或 mobile:full OAuth token，不需要也不会接触模型网关 API Key。

认证：JWT Bearer Token，或 OAuth Access Token（wno-...，需 mobile:full scope）。

请求：multipart/form-data

字段	必填	说明
file	是	音频文件。服务端默认限制 10MB、120 秒，可用环境变量调整
model	否	不传时读取 client.models.cloud.asrModel
language	否	语言提示，如 auto / zh
prompt	否	ASR 上下文提示

响应

{
  "success": true,
  "data": {
    "text": "转写文本",
    "language": "auto",
    "duration_seconds": 1.5,
    "model": "step-asr",
    "usage": { "unit": "second", "amount": 1.5 }
  }
}

duration_seconds / usage.amount 是服务端核定的计费时长：WAV / MP3 按音频结构计算，其他格式在文件大小与声明时长相符时采用声明值，不符或无法解析时由服务端解码实测（不采用文件头里可改写的时长）。

常见错误：400 invalid_request、402 insufficient_quota、413 file_too_large / duration_too_long、422 invalid_request（无法确定音频时长）、429 rate_limited、503 service_unavailable（含服务端音频解码器不可用或排队已满）。