服务目录查询 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 }
  }
}

常见错误：400 invalid_request、402 insufficient_quota、413 file_too_large / duration_too_long、429 rate_limited、503 service_unavailable。

---

POST /services/passthrough/text-refine

移动端语音转写文本润色业务包装接口。当前支持 voice_cleanup profile，用于清理口语赘词、错别字和断句。

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

请求

{
  "text": "嗯 今天 天气 很好",
  "profile": "voice_cleanup",
  "model": "可选，不传时读取 client.models.cloud.refineModel"
}

响应

{
  "success": true,
  "data": {
    "text": "今天天气很好。",
    "profile": "voice_cleanup",
    "model": "qwen-flash",
    "usage": {
      "unit": "token",
      "input_tokens": 42,
      "output_tokens": 12,
      "total_tokens": 54
    }
  }
}

常见错误：400 invalid_request / unsupported_profile、402 insufficient_quota、413 text_too_large、429 rate_limited、502 provider_error、503 service_unavailable。