# 接口概览

基址，协议，限额与全部接口一览，SDK 与直连调用共用同一份契约。

来源：https://open.shengzhiai.com/sdk/v2/api/

## 接口一览

| 方法 | 路径 | 接口 |
|---|---|---|
| POST | `/api/v1/evaluate` | [原生整段评测](https://open.shengzhiai.com/sdk/v2/api/evaluate/) |
| POST | `/{coreType}` | [声通兼容整段评测](https://open.shengzhiai.com/sdk/v2/api/evaluate-compat/) |
| POST | `/api/v1/tts/generate` | [语音合成](https://open.shengzhiai.com/sdk/v2/api/tts/) |
| GET | `/api/v1/report/{recordId}` | [报告查询](https://open.shengzhiai.com/sdk/v2/api/report/) |
| WSS | `/api/v1/ws/evaluate` | [原生实时评测](https://open.shengzhiai.com/sdk/v2/api/ws-evaluate/) |
| WSS | `/{coreType}` | [声通兼容实时评测](https://open.shengzhiai.com/sdk/v2/api/ws-compat/) |

契约版本 `2.1`，适用接口版本 v1 与 SDK `2.1.0`，五端 SDK 与平台按同一份契约对齐，`1.x` 契约的全部接口与字段继续有效。没有 SDK 的语言直接按契约调用，或用 [OpenAPI 描述](https://open.shengzhiai.com/sdk/v2/api/openapi/)生成客户端。

## 基址与限额

| 用途 | 地址 |
|---|---|
| REST 基址 | `https://open.shengzhiai.com` |
| WebSocket 基址 | `wss://open.shengzhiai.com` |
| 平台接口文档 | `https://open.shengzhiai.com/docs.html` |
| SDK 下载与仓库 | 见[安装](https://open.shengzhiai.com/sdk/v2/installation/) |

全部接口只接受 HTTPS 与 WSS。单次 REST 请求在服务端最长处理 600 秒，其中评测排队最长 540 秒，入口读超时 660 秒。评测上传的请求体上限 50 MB，实时评测单轮音频上限 10 MB，单帧上限 128 KB。

## 通用约定

| 项 | 约定 |
|---|---|
| 编码 | 请求与响应一律 UTF-8，JSON 字段名区分大小写 |
| 鉴权 | appKey 签名或 Bearer token，见[签名与鉴权](https://open.shengzhiai.com/sdk/v2/api/authentication/) |
| 幂等 | 写操作带 `Idempotency-Key`，实时评测在开始帧或参数帧带 `idempotencyKey`，见[幂等](https://open.shengzhiai.com/sdk/v2/api/idempotency/) |
| 时间单位 | `span` 的起止时间单位为 10 毫秒，连读题 `boundaries` 的 `start_ms`，`end_ms`，`gap_ms` 为毫秒，`duration` 为秒 |
| 分数 | 默认百分制，`scale` 改变分制后按比例换算 |
| 错误 | 平台信封 `{"code": 40001, "message": "..."}`，错误码见[错误码](https://open.shengzhiai.com/sdk/v2/api/errors/) |
| 重试 | 只对带幂等键或天然幂等的请求重试，见[重试](https://open.shengzhiai.com/sdk/v2/api/retries/) |

## 契约全文

契约原文见 [CONTRACT.md](https://open.shengzhiai.com/sdk/v2/CONTRACT.md)。