优谷雅言 开发者文档

中英文双语语音评测 · 兼容声通 API 协议 · v1

概述

优谷雅言对用户朗读音频做多维度多层级评分,产出结构化评分、自然语言报告与标准示范音频。基址 https://open.shengzhiai.com,所有接口返回 JSON。

鉴权

三种方式,按场景选择:

快速开始

四步完成第一次评测:

1. 获取密钥:在开放平台控制台创建 API Key,得到 appKey(请求头 X-App-Key)与 secretKey。
2. 准备音频:wav / mp3 / ogg,推荐 16kHz、16bit、单声道 wav(≤10MB、≤5 分钟);其他采样率引擎自动重采样,过低采样率会损失评分精度。
3. 调用评测:multipart 表单 POST /api/v1/evaluate,字段 audio(文件)+ config(JSON 字符串,该分片的 Content-Type 必须为 application/json)。
4. 解析结果:取 result.overall 总分与各维分;保存 recordId 以便事后 GET /api/v1/report/{recordId} 回查。

提交一段中文朗读音频做句子评测:

curl -X POST https://open.shengzhiai.com/api/v1/evaluate \
  -H "X-App-Key: test_app_key" \
  -F "audio=@reading.wav;type=audio/wav" \
  -F 'config={"coreType":"sentence","referenceText":"鹅，鹅，鹅，曲项向天歌。","language":"zh-CN"};type=application/json'

import requests

cfg = '{"coreType":"sentence","referenceText":"鹅，鹅，鹅，曲项向天歌。","language":"zh-CN"}'
r = requests.post("https://open.shengzhiai.com/api/v1/evaluate",
    headers={"X-App-Key": "test_app_key"},
    files={"audio": ("reading.wav", open("reading.wav", "rb"), "audio/wav"),
           "config": (None, cfg, "application/json")})   # config 分片须为 application/json
r.raise_for_status()
print(r.json()["result"]["overall"])

// OkHttp(com.squareup.okhttp3:okhttp)
OkHttpClient client = new OkHttpClient();
String cfg = "{\"coreType\":\"sentence\",\"referenceText\":\"鹅，鹅，鹅，曲项向天歌。\",\"language\":\"zh-CN\"}";
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
    .addFormDataPart("audio", "reading.wav",
        RequestBody.create(new File("reading.wav"), MediaType.parse("audio/wav")))
    .addFormDataPart("config", null,
        RequestBody.create(cfg, MediaType.parse("application/json")))
    .build();
Request req = new Request.Builder()
    .url("https://open.shengzhiai.com/api/v1/evaluate")
    .header("X-App-Key", "test_app_key")
    .post(body).build();
try (Response resp = client.newCall(req).execute()) {
    System.out.println(resp.body().string());
}

const fd = new FormData();
fd.append("audio", fileBlob, "reading.wav");
fd.append("config", new Blob([JSON.stringify(
  {coreType:"sentence", referenceText:"鹅，鹅，鹅，曲项向天歌。", language:"zh-CN"}
)], {type:"application/json"}));                       // config 分片须为 application/json
const r = await fetch("https://open.shengzhiai.com/api/v1/evaluate",
  {method:"POST", headers:{"X-App-Key":"test_app_key"}, body:fd});
console.log((await r.json()).result.overall);

package main

import (
    "bytes"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "net/textproto"
    "os"
)

func main() {
    buf := &bytes.Buffer{}
    w := multipart.NewWriter(buf)
    fw, _ := w.CreateFormFile("audio", "reading.wav")
    f, _ := os.Open("reading.wav")
    defer f.Close()
    io.Copy(fw, f)
    h := textproto.MIMEHeader{}                      // config 分片须为 application/json
    h.Set("Content-Disposition", `form-data; name="config"`)
    h.Set("Content-Type", "application/json")
    cw, _ := w.CreatePart(h)
    cw.Write([]byte(`{"coreType":"sentence","referenceText":"鹅，鹅，鹅，曲项向天歌。","language":"zh-CN"}`))
    w.Close()

    req, _ := http.NewRequest("POST",
        "https://open.shengzhiai.com/api/v1/evaluate", buf)
    req.Header.Set("X-App-Key", "test_app_key")
    req.Header.Set("Content-Type", w.FormDataContentType())
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

/* gcc evaluate.c -o evaluate -lcurl  (libcurl ≥ 7.56,curl_mime API) */
#include <stdio.h>
#include <curl/curl.h>

int main(void) {
    curl_global_init(CURL_GLOBAL_ALL);
    CURL *h = curl_easy_init();
    if (!h) return 1;

    curl_mime *form = curl_mime_init(h);
    curl_mimepart *p = curl_mime_addpart(form);          /* 音频文件分片 */
    curl_mime_name(p, "audio");
    curl_mime_filedata(p, "reading.wav");
    curl_mime_type(p, "audio/wav");
    p = curl_mime_addpart(form);                          /* config JSON 分片 */
    curl_mime_name(p, "config");
    curl_mime_data(p,
        "{\"coreType\":\"sentence\",\"referenceText\":\"鹅，鹅，鹅，曲项向天歌。\",\"language\":\"zh-CN\"}",
        CURL_ZERO_TERMINATED);
    curl_mime_type(p, "application/json");                /* 必须:否则报 50000 */

    struct curl_slist *hdr =
        curl_slist_append(NULL, "X-App-Key: test_app_key");
    curl_easy_setopt(h, CURLOPT_URL,
        "https://open.shengzhiai.com/api/v1/evaluate");
    curl_easy_setopt(h, CURLOPT_HTTPHEADER, hdr);
    curl_easy_setopt(h, CURLOPT_MIMEPOST, form);

    CURLcode rc = curl_easy_perform(h);   /* 响应 JSON 默认写到 stdout */
    if (rc != CURLE_OK)
        fprintf(stderr, "error: %s\n", curl_easy_strerror(rc));

    curl_slist_free_all(hdr);
    curl_mime_free(form);
    curl_easy_cleanup(h);
    curl_global_cleanup();
    return (int)rc;
}

<?php
// PHP ≥ 8.1(CURLStringFile 用于带 Content-Type 的字符串分片)
$cfg = '{"coreType":"sentence","referenceText":"鹅，鹅，鹅，曲项向天歌。","language":"zh-CN"}';
$ch = curl_init("https://open.shengzhiai.com/api/v1/evaluate");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-App-Key: test_app_key"],
    CURLOPT_POSTFIELDS     => [   // 数组形式即 multipart/form-data
        "audio"  => new CURLFile("reading.wav", "audio/wav", "reading.wav"),
        "config" => new CURLStringFile($cfg, "config", "application/json"),
    ],
]);
$raw = curl_exec($ch);
if ($raw === false) { die("curl error: " . curl_error($ch)); }
curl_close($ch);
$res = json_decode($raw, true);
echo $res["result"]["overall"], PHP_EOL;

朗读评测 POST/api/v1/evaluate

中英文朗读多维评分(完整度/准确度/声调/流利度/朗读技巧/情感),返回全文/句/字/音素多层级。multipart 表单:audio(文件)+ config(JSON,Content-Type 须为 application/json)。

config 核心字段

全部可选参数(refPinyin / agegroup / phonemeOutput / includeReport / includeStandardAudio / includeAsrText / taskType 等)见 评测参数。

多语言示例

curl -X POST https://open.shengzhiai.com/api/v1/evaluate \
  -H "X-App-Key: test_app_key" \
  -F "audio=@reading.wav;type=audio/wav" \
  -F 'config={"coreType":"sentence","referenceText":"鹅，鹅，鹅，曲项向天歌。","language":"zh-CN","includeReport":true,"includeStandardAudio":true,"includeAsrText":true};type=application/json'

import requests

cfg = {"coreType": "sentence",
       "referenceText": "鹅，鹅，鹅，曲项向天歌。",
       "language": "zh-CN", "includeReport": True}
r = requests.post("https://open.shengzhiai.com/api/v1/evaluate",
    headers={"X-App-Key": "test_app_key"},
    files={"audio": ("reading.wav", open("reading.wav", "rb"), "audio/wav"),
           "config": (None, __import__("json").dumps(cfg, ensure_ascii=False), "application/json")})
d = r.json()
print(d["recordId"], d["result"]["overall"], d["result"]["tone"])
print(d["report"]["summary"])

// OkHttp:multipart audio + config(application/json)
String cfg = "{\"coreType\":\"sentence\",\"referenceText\":\"鹅，鹅，鹅，曲项向天歌。\",\"language\":\"zh-CN\"}";
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
    .addFormDataPart("audio", "reading.wav",
        RequestBody.create(new File("reading.wav"), MediaType.parse("audio/wav")))
    .addFormDataPart("config", null,
        RequestBody.create(cfg, MediaType.parse("application/json")))
    .build();
Request req = new Request.Builder()
    .url("https://open.shengzhiai.com/api/v1/evaluate")
    .header("X-App-Key", "test_app_key").post(body).build();
try (Response resp = new OkHttpClient().newCall(req).execute()) {
    System.out.println(resp.body().string());
}

// 见「快速开始」Go 完整示例;要点:config 分片用 CreatePart 显式
// 设 Content-Type: application/json,音频用 CreateFormFile。
h := textproto.MIMEHeader{}
h.Set("Content-Disposition", `form-data; name="config"`)
h.Set("Content-Type", "application/json")
cw, _ := w.CreatePart(h)
cw.Write([]byte(`{"coreType":"sentence","referenceText":"鹅，鹅，鹅，曲项向天歌。","language":"zh-CN"}`))

// Node 20+:内置 fetch / FormData / Blob
import { readFile } from "node:fs/promises";

const fd = new FormData();
fd.append("audio", new Blob([await readFile("reading.wav")], {type:"audio/wav"}), "reading.wav");
fd.append("config", new Blob([JSON.stringify({
  coreType: "sentence",
  referenceText: "鹅，鹅，鹅，曲项向天歌。",
  language: "zh-CN"
})], {type:"application/json"}));
const r = await fetch("https://open.shengzhiai.com/api/v1/evaluate",
  {method:"POST", headers:{"X-App-Key":"test_app_key"}, body:fd});
const d = await r.json();
console.log(d.recordId, d.result.overall);

响应(节选,真实调用 recordId=eval_9aa80c616edb)

{
  "recordId": "eval_9aa80c616edb", "eof": 1,
  "result": {
    "overall": 67, "pronunciation": 69, "tone": 100, "fluency": 71,
    "rhythm": 67, "integrity": 68, "speed": 77, "rear_tone": "rise",
    "duration": "7.320", "warning": [],
    "words": [{"word":"鹅","pinyin":"e","rawpinyin":"e2","symbolpinyin":"é",
      "charType":0,"readType":0,"tone":"tone2",
      "scores":{"overall":100,"pronunciation":100,"tone":100},
      "span":{"start":28,"end":32},
      "phonemes":[{"phoneme":"E","phone":"e","pronunciation":100,"tone_index":"2"}], ...}],
    "sentences": [{"sentence":"鹅，鹅，鹅，曲项向天歌。","index":0,
      "scores":{"overall":67,"pronunciation":69,"fluency":71,"integrity":68},"details":[...]}],
    "compositeReport": {"compositeScore":67,"emotionScore":66,"stopConnScore":70,
      "intonationScore":72,"readSpeedScore":57, ...},
    "yuguScores": {...}
  },
  "report": {"source":"llm","summary":"本次朗读总体表现尚可…","dimensions":{...},"suggestions":[...]},
  "standardAudio": {"url":"https://…/tts/audio/ab3393f2021111ef.wav","format":"wav","duration":"4.280"},
  "asrText": {"text":"鹅 鹅 鹅 曲 项 向 天 歌 …","alignment":[...]},
  "warnings": []
}

返回值说明

以下逐字段说明以一次真实 /api/v1/evaluate 调用(中文《咏鹅》朗读,recordId eval_9aa80c616edb)为准,示例列为该次调用的真实取值。

顶层字段

result 字段

words[] 字段(字/词级)

asrText.alignment[] 字段(逐字对齐)

开放题 POST/api/v1/evaluate · config.coreType = "open"

看图说话 / 情景问答 / 自由表达。与朗读评测同一端点,config 设 coreType:"open" + taskType(picture / situational / free),referenceText 作为题干/任务提示(考生自由作答);返回内容/语言/表达三组主观维 + 客观音质维(Distill-MOS)。

curl -X POST https://open.shengzhiai.com/api/v1/evaluate \
  -H "X-App-Key: test_app_key" \
  -F "audio=@answer.wav;type=audio/wav" \
  -F 'config={"coreType":"open","taskType":"free","referenceText":"请谈谈你最喜欢的季节。","language":"zh-CN"};type=application/json'

cfg = {"coreType": "open", "taskType": "free",
       "referenceText": "请谈谈你最喜欢的季节。", "language": "zh-CN"}
r = requests.post("https://open.shengzhiai.com/api/v1/evaluate",
    headers={"X-App-Key": "test_app_key"},
    files={"audio": ("answer.wav", open("answer.wav", "rb"), "audio/wav"),
           "config": (None, json.dumps(cfg, ensure_ascii=False), "application/json")})
res = r.json()["result"]
print(res["overall"], res["content"], res["feedback"]["suggestions"])

String cfg = "{\"coreType\":\"open\",\"taskType\":\"free\","
    + "\"referenceText\":\"请谈谈你最喜欢的季节。\",\"language\":\"zh-CN\"}";
// multipart 组装与朗读评测完全一致(audio 文件 + config application/json 分片)
// 取分:result.overall / result.content / result.delivery / result.feedback

cw.Write([]byte(`{"coreType":"open","taskType":"free",` +
    `"referenceText":"请谈谈你最喜欢的季节。","language":"zh-CN"}`))
// multipart 组装与朗读评测一致;解析 result.overall / content / delivery / feedback

fd.append("config", new Blob([JSON.stringify({
  coreType: "open", taskType: "free",
  referenceText: "请谈谈你最喜欢的季节。", language: "zh-CN"
})], {type:"application/json"}));
const d = await (await fetch("https://open.shengzhiai.com/api/v1/evaluate",
  {method:"POST", headers:{"X-App-Key":"test_app_key"}, body:fd})).json();
console.log(d.result.overall, d.result.feedback);

响应(节选,真实调用 recordId=open_3538888d398c)

{
  "recordId": "open_3538888d398c", "eof": 1,
  "result": {
    "taskType": "free", "language": "zh", "duration_s": 4.36,
    "transcript": "今天天气很好我们一起去公园小鸟在唱歌", "hasSpeech": true,
    "overall": 57,
    "content":     {"overall":50, "relevance":60, "coherence":50, "task_achievement":40},
    "languageUse": {"overall":35, "grammar":30, "vocabulary":40},
    "delivery":    {"overall":91, "fluency":100, "pronunciation":78,
                    "speech_rate_label":"266.0 字/分", "n_pauses":0},
    "feedback": {"strengths":"…", "weaknesses":"回答偏离了题目要求…", "suggestions":["…"]},
    "audioQuality": {"mos":4.51, "quality":88},
    "scoringSource": "asr+llm+vad+sfgop+distillmos"
  }
}

英文连读 POST/api/v1/evaluate · config.coreType = "connected"

英文连读/失爆/弱读判定与节奏分析。与朗读评测同一端点,config 设 coreType:"connected"、language:"en-US",referenceText 为目标英文句;逐词边界标注连读是否实现。

curl -X POST https://open.shengzhiai.com/api/v1/evaluate \
  -H "X-App-Key: test_app_key" \
  -F "audio=@english.wav;type=audio/wav" \
  -F 'config={"coreType":"connected","referenceText":"The quick brown fox jumps over the lazy dog.","language":"en-US"};type=application/json'

cfg = {"coreType": "connected", "language": "en-US",
       "referenceText": "The quick brown fox jumps over the lazy dog."}
r = requests.post("https://open.shengzhiai.com/api/v1/evaluate",
    headers={"X-App-Key": "test_app_key"},
    files={"audio": ("english.wav", open("english.wav", "rb"), "audio/wav"),
           "config": (None, json.dumps(cfg), "application/json")})
res = r.json()["result"]
print(res["connected_overall"], res["linking"], res["rhythm"], res["boundaries"])

String cfg = "{\"coreType\":\"connected\",\"language\":\"en-US\","
    + "\"referenceText\":\"The quick brown fox jumps over the lazy dog.\"}";
// multipart 组装与朗读评测完全一致
// 取分:result.connected_overall / linking / rhythm / boundaries[]

cw.Write([]byte(`{"coreType":"connected","language":"en-US",` +
    `"referenceText":"The quick brown fox jumps over the lazy dog."}`))
// 解析 result.connected_overall / linking / rhythm / boundaries

fd.append("config", new Blob([JSON.stringify({
  coreType: "connected", language: "en-US",
  referenceText: "The quick brown fox jumps over the lazy dog."
})], {type:"application/json"}));
const d = await (await fetch("https://open.shengzhiai.com/api/v1/evaluate",
  {method:"POST", headers:{"X-App-Key":"test_app_key"}, body:fd})).json();
console.log(d.result.connected_overall, d.result.boundaries);

响应(节选,真实调用 recordId=conn_7a9b15dc84f0)

{
  "recordId": "conn_7a9b15dc84f0", "eof": 1,
  "result": {
    "connected_overall": 69, "linking": 8, "rhythm": 100,
    "elision": 0, "reduction": 100,
    "raw": {"linking_rate":0.548, "nPVI_V":31.5, "pctV":33.3, ...},
    "n_boundaries": 3,
    "boundaries": [
      {"between":["quick","brown"], "tags":["elision"],    "gap_ms":90.0,
       "continuity":0.25, "realized":0.37, "start_ms":740.0, "end_ms":970.0},
      {"between":["jumps","over"],  "tags":["linking_CV"], "gap_ms":80.0, ...}
    ],
    "calibrated": true, "classifier": true, "posterior_used": true
  }
}

音素级评分(GOP)

无需单独端点:朗读评测 config 的 phonemeOutput(默认开)即输出音素级明细 —— result.words[].phonemes[] 给出每个声母/韵母的 pronunciation(0-100)、音素符号(phoneme/phone)与时间区间;asrText.alignment[].gop_score 给出逐字声学 GOP 真值(零发音标注的 CTC 后验 + 判别头打分,无声学证据时为 null)。

// 真实 words[0].phonemes(《咏鹅》首字"鹅")
"phonemes": [{"phoneme":"E", "phone":"e", "category":0,
              "pronunciation":100, "tone_index":"2",
              "span":{"start":28,"end":32}}]
// 真实 asrText.alignment[0]
{"char":"鹅","index":0,"read_status":"correct","gop_score":100.0,
 "asr_pinyin":"e2","asr_tone":"2","asr_final":"e"}

实时 WebSocket WS/api/v1/ws/evaluate

边录边传,结束即评。协议(文本帧 JSON + 二进制音频帧):

wss://open.shengzhiai.com/api/v1/ws/evaluate
← {"event":"connected","message":"stream channel ready"}
→ {"cmd":"start","coreType":"sentence","referenceText":"今天天气很好","language":"zh-CN"}
← {"event":"started"}
→ 二进制音频分片 ×N(或文本帧 {"cmd":"audio","data":"<base64>"})
→ {"cmd":"end"}
← {"event":"result","recordId":"eval_…","eof":1,"result":{…},"report":{…},"asrText":{…},"warnings":[]}

import asyncio, json, websockets

async def main():
    async with websockets.connect("wss://open.shengzhiai.com/api/v1/ws/evaluate") as ws:
        print(await ws.recv())                       # {"event":"connected",...}
        await ws.send(json.dumps({"cmd": "start", "coreType": "sentence",
            "referenceText": "今天天气很好", "language": "zh-CN"}))
        print(await ws.recv())                       # {"event":"started"}
        data = open("reading.wav", "rb").read()
        for i in range(0, len(data), 3200):          # ~100ms/帧
            await ws.send(data[i:i+3200])
        await ws.send(json.dumps({"cmd": "end"}))
        final = json.loads(await ws.recv())          # {"event":"result",...}
        print(final["result"]["overall"])

asyncio.run(main())

// JDK 11+ java.net.http.WebSocket,无第三方依赖
HttpClient client = HttpClient.newHttpClient();
WebSocket ws = client.newWebSocketBuilder()
    .buildAsync(URI.create("wss://open.shengzhiai.com/api/v1/ws/evaluate"),
        new WebSocket.Listener() {
            @Override public CompletionStage<?> onText(WebSocket w, CharSequence data, boolean last) {
                System.out.println(data);            // connected / started / result
                w.request(1);
                return null;
            }
        }).join();
ws.sendText("{\"cmd\":\"start\",\"coreType\":\"sentence\","
    + "\"referenceText\":\"今天天气很好\",\"language\":\"zh-CN\"}", true);
byte[] audio = Files.readAllBytes(Path.of("reading.wav"));
for (int i = 0; i < audio.length; i += 3200)
    ws.sendBinary(ByteBuffer.wrap(audio, i, Math.min(3200, audio.length - i)), true).join();
ws.sendText("{\"cmd\":\"end\"}", true);

// go get github.com/gorilla/websocket
c, _, err := websocket.DefaultDialer.Dial(
    "wss://open.shengzhiai.com/api/v1/ws/evaluate", nil)
if err != nil { panic(err) }
defer c.Close()
c.ReadMessage()                                      // connected
c.WriteJSON(map[string]string{"cmd": "start", "coreType": "sentence",
    "referenceText": "今天天气很好", "language": "zh-CN"})
c.ReadMessage()                                      // started
audio, _ := os.ReadFile("reading.wav")
for i := 0; i < len(audio); i += 3200 {
    end := i + 3200
    if end > len(audio) { end = len(audio) }
    c.WriteMessage(websocket.BinaryMessage, audio[i:end])
}
c.WriteJSON(map[string]string{"cmd": "end"})
_, msg, _ := c.ReadMessage()                         // result
fmt.Println(string(msg))

// npm i ws
import WebSocket from "ws";
import { readFileSync } from "node:fs";

const ws = new WebSocket("wss://open.shengzhiai.com/api/v1/ws/evaluate");
ws.on("message", raw => {
  const d = JSON.parse(raw);
  if (d.event === "connected")
    ws.send(JSON.stringify({cmd:"start", coreType:"sentence",
      referenceText:"今天天气很好", language:"zh-CN"}));
  else if (d.event === "started") {
    const buf = readFileSync("reading.wav");
    for (let i = 0; i < buf.length; i += 3200) ws.send(buf.subarray(i, i + 3200));
    ws.send(JSON.stringify({cmd:"end"}));
  } else if (d.event === "result") {
    console.log(d.result.overall);
    ws.close();
  }
});

声通兼容实时 WebSocket WSwss://host/{coreType}

面向存量声通接入方的流式评测,URL 直接取声通 coreType(如 /sent.eval.cn、/word.eval、/para.eval.cn 等附录全集)。与同名 POST /{coreType} 兼容 REST 同址共存(升级请求走 WS、普通 POST 走 REST)。

// 浏览器:连接声通兼容 WS 做中文句子流式评测
const ws = new WebSocket("wss://ygyx.dragonai.tech/sent.eval.cn");
ws.binaryType = "arraybuffer";
ws.onmessage = (e) => {
  const d = JSON.parse(e.data);
  if (d.event === "connected") ws.send(JSON.stringify({refText:"北京你好", language:"zh-CN", realtime_feedback:true}));
  else if (d.event === "started") sendAudioFramesThen(() => ws.send(JSON.stringify({cmd:"end"})));
  else if (d.eof === 0) console.log("进度", d.result.bytes);
  else if (d.eof === 1) { console.log("终评", d.result.overall); ws.close(); }
};

标准读音 TTS POST/api/v1/tts/generate

JSON body:text(≤1000 字符)、language(zh-CN / en-US / en-GB)、voice(female / male / xiaoyan / xiaofeng)、format(wav / mp3 / ogg)、speed / pitch / volume(0-100,默认 50)、sampleRate(采样率 Hz,可选 8000 / 16000 / 24000,默认 16000)、style(≤200 字自然语言风格指令,如「用新闻播报的语气」「温柔地朗读」)。按合成字符数计量(coreType tts.standard),单 Key 限频 60 次/分。

curl -X POST https://open.shengzhiai.com/api/v1/tts/generate \
  -H "X-App-Key: test_app_key" -H "Content-Type: application/json" \
  -d '{"text":"今天天气真好","language":"zh-CN","voice":"female",
       "format":"wav","sampleRate":16000,"style":"用新闻播报的语气"}'

// 真实响应
{"code":0,"message":"success",
 "data":{"audioUrl":"https://…/tts/audio/ab3393f2021111ef.wav",
         "duration":"4.280","format":"wav","warnings":[]},
 "timestamp":1781274776737}

语音识别 ASR POST/api/v1/asr/recognize

独立语音转文字(纯转写,不评测)。multipart/form-data:audio(音频文件 wav/mp3,≥16kHz)+ language(zh 中文 Paraformer / en 英文 WhisperX,默认 zh)。返回 data.text(转写文本)、data.words(中文逐字时间戳 start_ms/end_ms)、data.duration(秒)、data.confidence(英文置信度)。按音频时长(秒)计量(coreType asr.stream),单 Key 限频 60 次/分。

curl -X POST https://open.shengzhiai.com/api/v1/asr/recognize \
  -H "X-App-Key: test_app_key" \
  -F "audio=@speech.wav" -F "language=zh"

// 真实响应
{"code":0,"message":"success",
 "data":{"text":"今天天气很好我们一起去公园",
         "language":"zh","duration":4.36,
         "words":[{"word":"今","start_ms":290,"end_ms":450}, …],
         "confidence":null},
 "timestamp":1782632…}

报告查询 GET/api/v1/report/{recordId}

按 recordId 查询历史评测报告,返回统一信封:data.recordId / data.score(评测时的完整 result)/ data.report(AI 报告)。recordId 不存在时返回 {"code":40001,"message":"评测记录不存在: …"}。

curl https://open.shengzhiai.com/api/v1/report/eval_9aa80c616edb \
  -H "X-App-Key: test_app_key"
→ {"code":0,"message":"success","data":{"recordId":"eval_9aa80c616edb","score":{…},"report":{…}}}

coreType 参考

原生接口 coreType(config 必填)

声通协议兼容层

面向声通存量客户的协议适配端点 POST /{coreType}(coreType 取声通命名:word.eval / sent.eval / para.eval 及 .cn 中文、.pro 自适应变体)。multipart 表单:audio(音频文件)+ request(JSON 字符串,内含 refText 与鉴权三元组 appKey / timestamp(秒级)/ sig);响应按声通字段命名(顶层含 applicationId / dtLastResponse / refText / result),存量接入零改造迁移。

评测参数

以下参数均放在 config JSON 内(原生接口字段命名,与声通同名参数语义对齐):

错误码参考

① 平台统一信封 code(评测/TTS/报告/控制台接口)

错误响应统一为 {"code", "message", "timestamp"}(成功时为 {"code":0,"message":"success","data":…};评测成功响应直接返回结果体不包信封)。

鉴权细分另有业务码(如 2001 token 已过期、2002 token 无效),以响应 message 为准。

② 声通兼容层错误(实测 detail 原文)

③ 音频质量警告码(result.warning[],评分仍返回)

SDK 使用指南

当前形态:REST + WebSocket 直连,无需安装 SDK。所有能力经标准 HTTP multipart 与 WebSocket 暴露,本页已提供可直接复制运行的多语言调用示例:

五端 SDK(已发布,对应 PRD §5.3 SDK-001~005)

各 SDK 均封装:整段评测(REST)、TTS、报告查询、原生实时 WS、声通兼容 REST/WS,内置 HMAC-SHA256 签名器(命中统一测试向量)与录音采集(16k/16bit/单声道),含 Demo/示例与 README 集成文档。点击下载(tar.gz):

对接契约(字段/签名/协议单一基准):CONTRACT.md · 校验:SHA256SUMS。仍可不装 SDK,直接按本页 REST/WS 示例接入。

Demo 示例

两个在线工具与平台同域部署,打开即用,均为单文件页面,可直接查看源码作为接入参考。以下代码片段中 BASE = "https://open.shengzhiai.com"。

// 浏览器录音 → multipart 评测;能力仅切换 config.coreType(word/sentence/passage/connected/open/alpha),
// config.language 固定 zh-CN 或 en-US(中英分流);实时模式走 WS /api/v1/ws/evaluate。关闭浏览器音频处理三件套,交给引擎链路降噪。
const stream = await navigator.mediaDevices.getUserMedia({audio:
  {noiseSuppression:false, autoGainControl:false, echoCancellation:false}});
const mr = new MediaRecorder(stream), chunks = [];
mr.ondataavailable = e => chunks.push(e.data);
mr.onstop = async () => {
  const fd = new FormData();
  fd.append("audio", new Blob(chunks, {type:"audio/webm"}), "rec.webm");
  fd.append("config", new Blob([JSON.stringify({coreType:"sentence",
    referenceText:"鹅，鹅，鹅，曲项向天歌。", language:"zh-CN"})],
    {type:"application/json"}));
  const r = await fetch(BASE + "/api/v1/evaluate",
    {method:"POST", headers:{"X-App-Key":"test_app_key"}, body:fd});
  render((await r.json()).result);   // 六维分 + words[] 逐字四色着色
};
mr.start(); setTimeout(() => mr.stop(), 5000);

// 纯前端:六维滑杆打分(0-100)→ Blob 导出 CSV,无任何网络请求
let csv = "sample_id,rater_id,dimension,score\n";
for (const sid in store)
  for (const dim in store[sid])   // integrity/accuracy/fluency/reading_skill/emotion/tone
    csv += `${sid},${rater},${dim},${store[sid][dim]}\n`;
download(new Blob([csv], {type:"text/csv"}), `ratings_${rater}.csv`);

// 多评委线下聚合(脚本随引擎工程交付):
//   python annotation_aggregate.py ratings_A.csv ratings_B.csv ratings_C.csv
//   → 两两 Pearson / ICC(2,k) / 共识金标 CSV / 低一致样本标记

FAQ 常见问题

实时接口清单(OpenAPI 自动同步)