# 语音合成与报告

合成示范音，按 recordId 查询评测报告。

来源：https://open.shengzhiai.com/sdk/v2/guides/tts-report/

## 语音合成

把一段文本合成为示范音，返回音频地址与时长，常用于跟读题的标准音。中文音色取 `xiaoyan` 女声或 `xiaofeng` 男声，英文取 `female` 或 `male`，格式取 `mp3`，`wav`，`ogg`，语速，音调，音量取值 0 到 100，默认 50。

Java：

```java
TtsResult tts = client.tts(new TtsRequest("你好世界", "zh-CN", "xiaoyan").format("mp3"));
System.out.println("示范音 " + tts.getAbsoluteUrl() + "，时长 " + tts.getDuration() + " 秒");
```

网页：

```js
const tts = await client.tts({ text: '你好世界', language: 'zh-CN', voice: 'xiaoyan', format: 'mp3' });
console.log('示范音', tts.absoluteUrl, '时长', tts.duration);
```

cURL：

```bash
# 语音合成。被签名参数为请求体顶层的非空标量字段，按键名排序
BODY='{"text":"你好世界","language":"zh-CN","voice":"xiaoyan","format":"mp3"}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIGN=$(printf 'format=mp3&language=zh-CN&text=你好世界&voice=xiaoyan' | openssl dgst -sha256 -hmac "$YUGU_SECRET_KEY" -binary | base64)

curl -sS https://open.shengzhiai.com/api/v1/tts/generate \
  -H "Content-Type: application/json" \
  -H "X-App-Key: $YUGU_APP_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d "$BODY"
```

| 端 | 方法 | 可直接播放的地址 |
|---|---|---|
| Java | `tts(TtsRequest)` | `TtsResult.getAbsoluteUrl()` |
| 安卓 | `tts(request, options)`，异步 `ttsAsync` | `resolvedUrl` |
| iOS | `tts(_:options:)`，另有 `async` 写法 | `absoluteAudioUrl` |
| 网页 | `tts(request, options)` | `absoluteUrl` |
| 小程序 | `tts(params, options)` | `fullUrl`，可直接交给 `InnerAudioContext` |

语音合成是写操作，带幂等键，重试不会重复计费。接口定义见[语音合成](https://open.shengzhiai.com/sdk/v2/api/tts/)。

## 报告查询

按 `recordId` 查询一次评测的报告，只能查询本账号的记录，记录不存在时回 HTTP 400，错误码 40001。返回的 `data.score` 为评测分数，`data.report` 为自然语言点评，改进建议与维度分。

Java：

```java
ReportResult report = client.getReport(args[0]);
JsonNode data = report.getData();
System.out.println("总分 " + data.path("score").path("overall").asDouble());
System.out.println("点评 " + data.path("report").path("summary").asText());
```

网页：

```js
const report = await client.getReport(process.argv[2]);
console.log('点评', report.report?.summary, '维度分', report.report?.dimensionScores);
```

cURL：

```bash
# 报告查询。被签名参数为空集合，recordId 是路径的一段
RECORD_ID=eval_a31712f40cbf
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIGN=$(printf '' | openssl dgst -sha256 -hmac "$YUGU_SECRET_KEY" -binary | base64)

curl -sS "https://open.shengzhiai.com/api/v1/report/$RECORD_ID" \
  -H "X-App-Key: $YUGU_APP_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGN"
```

| 字段 | 含义 |
|---|---|
| `data.score.overall` | 总分，与评测结果的 `result.overall` 一致 |
| `data.report.summary` | 整体点评 |
| `data.report.suggestions` | 改进建议，逐条给出 |
| `data.report.dimensionScores` | 维度分，键随语种与题型不同，值为 null 表示本次不评该维 |

报告查询天然幂等，SDK 照常重试。评测时设置 `includeReport` 会生成 AI 报告，评测结果的 `report` 另含整体点评与改进建议。接口定义见[报告查询](https://open.shengzhiai.com/sdk/v2/api/report/)。