Text-to-Speech API – Response & Metrics Specification

本接口用于将文本转换为语音（Text-to-Speech），并在返回结果中提供关键性能指标，便于调用方评估实时性与整体合成效率。

Response Structure

当请求成功时，服务端将返回 HTTP 200，并返回如下 JSON 结构：

{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "created_at": "2026-01-20T11:39:02+08:00",
  "status_code": 200,
  "model_id": "flash_v2_5",
  "first_packet_latency_ms": 277,
  "tts_latency_ms": 0,
  "total_duration_ms": 327,
  "request_params": {
    "format": "mp3_44100_64",
    "language_code": "",
    "model_id": "flash_v2_5",
    "quality": "0",
    "text_length": 20,
    "voice_uid": "771e***************e852"
  }
}

Top-Level Fields

Field	Type	Description
`request_id`	string	请求唯一标识，用于日志追踪与问题排查
`created_at`	string (ISO 8601)	服务端生成该响应的时间（含时区）
`status_code`	integer	HTTP 状态码，`200` 表示成功
`model_id`	string	本次请求实际使用的 TTS 模型
`first_packet_latency_ms`	integer	首包延迟（毫秒），表示从服务端接收请求到返回第一段音频数据的耗时
`tts_latency_ms`	integer	TTS 合成阶段耗时（毫秒），部分模式下可能不可用，可能返回 `0`
`total_duration_ms`	integer	端到端总耗时（毫秒），覆盖整个请求生命周期

Latency Metrics Explanation（重要）

first_packet_latency_ms

衡量实时体验最重要的指标

表示用户从发起请求到“听到第一声音”的等待时间

数值越低，实时性越好

tts_latency_ms

表示 TTS 引擎内部的纯合成耗时

在以下场景中可能返回 0：

强流式或短文本请求

当前模型/版本暂未上报该分项

0 并不表示失败或异常

total_duration_ms

端到端整体耗时

通常满足：
total_duration_ms ≥ first_packet_latency_ms

推荐作为性能评估的最终参考指标

request_params（生效参数回显）

request_params 用于回显本次请求最终生效的参数配置，便于排查请求行为与服务端策略调整。

Field	Type	Description
`format`	string	输出音频格式，例如 `mp3_44100_64`
`language_code`	string	语言代码；空字符串 `""` 表示自动检测或使用默认语言策略
`model_id`	string	本次请求使用的模型 ID
`quality`	string	合成质量等级（字符串枚举），如 `"0"`
`text_length`	integer	输入文本长度统计值
`voice_uid`	string	音色 ID

⚠️ 注意：request_params 中的值以服务端最终生效配置为准，可能与请求入参存在差异。

Example Interpretation（示例解读）

以上示例表示：

输入文本长度为 20

首包延迟为 277ms，适合实时/低等待场景

端到端总耗时为 327ms

tts_latency_ms = 0 属于正常情况，表示该分项在本次请求中未单独上报

Troubleshooting & Support

当遇到异常或性能问题时，请在工单或技术支持中提供以下信息：

request_id

created_at

status_code

model_id

first_packet_latency_ms

tts_latency_ms

total_duration_ms

request_params

以上信息将有助于快速定位问题并进行优化分析。

Request_id客户端查询

Text-to-Speech API – Response & Metrics Specification

Response Structure

Top-Level Fields

Latency Metrics Explanation（重要）

first_packet_latency_ms

tts_latency_ms

total_duration_ms

request_params（生效参数回显）

Example Interpretation（示例解读）

Troubleshooting & Support

请求参数

返回响应

Request_id客户端查询

Text-to-Speech API – Response & Metrics Specification#

Response Structure#

Top-Level Fields#

Latency Metrics Explanation（重要）#

first_packet_latency_ms#

tts_latency_ms#

total_duration_ms#

request_params（生效参数回显）#

Example Interpretation（示例解读）#

Troubleshooting & Support#

请求参数

返回响应

Text-to-Speech API – Response & Metrics Specification

Response Structure

Top-Level Fields

Latency Metrics Explanation（重要）

first_packet_latency_ms

tts_latency_ms

total_duration_ms

request_params（生效参数回显）

Example Interpretation（示例解读）

Troubleshooting & Support