获取序列猴子开放平台 API Key 并调用语音合成接口

序列猴子开放平台提供语音合成（TTS）等接口，开发者可以用它把文本转成音频流，用于有声内容、播报、辅助阅读等场景。要调用这些接口，第一步是在平台上注册账号、创建应用，拿到 appkey 与 secret，然后按规则计算签名并发送请求。这篇教程把从注册到跑通第一次合成的完整链路拆开讲清楚，适合已经具备基本 HTTP 请求能力、准备把语音合成接入自己服务的开发者。如果你只是想先了解这类接口的调用形态，也可以参考站内的 序列猴子 工具条目，再回到本文按步骤操作。

准备工作

在动手写代码之前，需要先确认下面几件事，否则后面的请求会因为缺少凭据或参数而失败。

• 平台账号：需要先在序列猴子开放平台完成注册与登录。登录后按页面提示申请体验，才能进入控制台使用应用管理功能。
• 应用与凭据：在控制台创建应用后，平台会生成该应用的 appkey 与 secret。这两个值都要保存好，secret 只用于本地计算签名，不要写进前端代码或公开仓库。
• 可发送 HTTP 请求的环境：任意能发起 POST 请求的语言或工具都可以，例如 curl、Python、Node.js。请求体是 JSON，因此需要能设置 Content-Type: application/json。
• 时间同步：签名里包含时间戳，且签名有有效期，因此运行请求的机器时间要准确，偏差过大会导致签名校验失败。
• 网络可达性：如果所在网络需要通过代理或防火墙访问外部服务，要提前配置好，否则请求可能被直接拦截。

关于接口的可用区域、计费方式、发音人价格、字幕生成费用等易变信息，请以官网当前公布的内容为准，本文不给出具体数字。

操作步骤

第一步：注册并申请体验

打开序列猴子开放平台，完成注册与登录。登录之后在页面上申请体验，获得使用开放接口的资格。这一步是后续创建应用的前提，没有完成体验申请时，控制台里的应用相关入口可能不可用。

第二步：创建应用并保存 APPKEY

1. 在控制台左侧菜单栏进入「我的应用」。
2. 点击「创建应用」。
3. 在弹出的窗口中填写应用信息，确认后点击提交。
4. 应用创建完成后，页面会展示该应用的 appkey 与 secret，把它们复制保存到安全的位置。

建议把凭据放在服务端的环境变量或密钥管理服务里，例如 SEQ_APPKEY 与 SEQ_SECRET，代码中通过读取环境变量获取，避免硬编码。

第三步：理解签名规则

接口要求每次请求都携带签名。签名的计算方式是：把 appkey、secret、timestamp 三个字符串按顺序拼接，对拼接结果做 MD5，得到一个 32 位的十六进制字符串。拼接时使用的加号本身不参与计算，只是表示连接关系；换句话说，最终参与 MD5 的是三段内容首尾相连的结果。

需要注意的几点：

• timestamp 是当前时间戳，单位为秒，不是毫秒。
• 签名需要每次请求实时计算，不能长期复用同一个签名。
• 签名有效期为 10 分钟，超过这个时间窗口的请求会被拒绝。
• 请求体中的 timestamp 字段必须与计算签名时使用的时间戳完全一致。

下面是一段计算签名的示例代码，语言为 Python：

import hashlib
import time

appkey = "你的 appkey"
secret = "你的 secret"
timestamp = str(int(time.time()))

raw = appkey + secret + timestamp
signature = hashlib.md5(raw.encode("utf-8")).hexdigest()

print(timestamp, signature)

如果使用 Node.js，可以用内置的 crypto 模块完成同样的计算：

const crypto = require("crypto");

const appkey = "你的 appkey";
const secret = "你的 secret";
const timestamp = String(Math.floor(Date.now() / 1000));

const signature = crypto
  .createHash("md5")
  .update(appkey + secret + timestamp)
  .digest("hex");

console.log(timestamp, signature);

第四步：构造请求

语音合成接口使用 POST 方法，请求头需要设置 Content-Type: application/json，请求体为 JSON 对象。请求体中的字段分为必填与可选两类，下面逐一说明。

必填字段

字段名	类型	说明
text	String	要合成的文本内容，默认限制为 1000 字符。支持 SSML 标记语言。
appkey	String	在开放平台申请到的应用 appkey。
signature	String	由 appkey、secret、timestamp 拼接后做 MD5 得到的 32 位值。
timestamp	Long	当前时间戳，单位为秒。

可选字段

字段名	类型	默认值	说明
speaker	String	cissy_meet	指定发音人。其他发音人的取值与计费价格需参考声音商店。pro 发音人的合成时长相对较长，选用前要评估耗时。
audio_type	String	mp3	音频格式，可选 pcm、mp3、speex-wb-10、wav，只支持这四种之一。
speed	Float	1.0	语速，支持小数点后两位，取值范围 0.5 到 2.0。
volume	Float	1.0	音量，取值范围 0.1 到 1.0。
pitch	Float	0	语调，小于 0 变低、大于 0 变高，取值范围在 -10 到 10 之间。streaming 接口不支持该参数。
rate	Long	由 speaker 决定	音频采样率，可选 8000、16000、24000。
convert	String	无	可选值 robot，用于转换为机器声。
symbol_sil	String	无	符号停顿时长映射，多个映射用逗号分隔，例如 semi_200,exclamation_200,question_200,comma_200,stop_200。充值后自动开通权限，streaming 接口不支持。
ignore_limit	Boolean	false	设为 true 时文本可超过 1000 字符，最大 3000 字符。充值后自动开通权限。
gen_srt	Boolean	false	是否生成 srt 字幕文件。仅在 ignore_limit 为 true 且 audio_type 为 wav 时才能返回字幕。生成字幕需要额外付费。
srt_len	Long	无	生成字幕的最大长度。中文字幕遇到逗号、句号、感叹号、问号、分号等符号时会自动分句拆分。
merge_symbol	Boolean	false	粗粒度合成参数。设为 true 后语气停顿更接近真人效果，同时会使 symbol_sil 参数失效。
streaming	Boolean	false	是否流式输出。设为 true 且 ignore_limit 为 true、audio_type 不为 wav 时，接口以流式方式返回音频。

一个最小的请求体示例如下：

{
  "appkey": "开发者应用appkey",
  "timestamp": "1665717322",
  "signature": "appkey+secret+timestamp的MD5值",
  "speaker": "cissy_meet",
  "audio_type": "mp3",
  "speed": "1.0",
  "text": "海南长臂猿的叫声，高亢洪亮，响彻山谷。"
}

第五步：发送请求并处理返回

合成成功时，接口直接返回语音流，响应头中的 Content-Type 为 audio/mpeg（对应 mp3 格式），响应体就是音频二进制数据。你可以把它保存成音频文件，也可以直接交给播放器播放。

如果请求了字幕生成，字幕文件的地址会通过响应头返回，字段名为 srt_address。响应头形如：

{
  "Content-Type": "audio/mpeg",
  "srt_address": ""
}

合成失败时，接口返回 JSON 格式的错误信息，包含错误码与描述，例如：

{
  "status": "error",
  "errorMessage": {
    "code": 31002,
    "desc": "failed to convert text to speech"
  }
}

因此客户端在处理响应时，不能一律按音频流读取，应先判断响应头的内容类型：是音频就按二进制写入文件，是 JSON 就解析错误信息并记录错误码，便于排查。

一个完整示例

下面用 Python 走一遍完整流程：读取环境变量中的凭据、计算签名、发送请求、根据响应类型分别处理音频与错误。示例只依赖标准库，便于直接运行。

import hashlib
import json
import os
import time
import urllib.request

APPKEY = os.environ["SEQ_APPKEY"]
SECRET = os.environ["SEQ_SECRET"]
API_URL = "接口地址"  # 以平台文档当前公布的地址为准

timestamp = str(int(time.time()))
signature = hashlib.md5(
    (APPKEY + SECRET + timestamp).encode("utf-8")
).hexdigest()

payload = {
    "appkey": APPKEY,
    "timestamp": timestamp,
    "signature": signature,
    "speaker": "cissy_meet",
    "audio_type": "mp3",
    "speed": "1.0",
    "text": "海南长臂猿的叫声，高亢洪亮，响彻山谷。"
}

req = urllib.request.Request(
    API_URL,
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST"
)

with urllib.request.urlopen(req) as resp:
    content_type = resp.headers.get("Content-Type", "")
    body = resp.read()
    srt_address = resp.headers.get("srt_address")

if content_type.startswith("audio/"):
    with open("output.mp3", "wb") as f:
        f.write(body)
    print("音频已保存，大小：", len(body), "字节")
    if srt_address:
        print("字幕地址：", srt_address)
else:
    print("合成失败：", body.decode("utf-8"))

运行前需要先设置两个环境变量：

export SEQ_APPKEY="你的 appkey"
export SEQ_SECRET="你的 secret"
python tts_demo.py

如果一切正常，当前目录下会出现 output.mp3，可以直接播放确认发音人、语速是否符合预期。如果返回的是 JSON，则根据 errorMessage.code 与 desc 定位问题，常见原因是签名不匹配、时间戳过期、文本超长或参数取值越界。

进阶用法一：长文本合成

默认情况下 text 限制为 1000 字符。需要合成更长的文本时，把 ignore_limit 设为 true，上限提高到 3000 字符。该能力需要充值后自动开通权限，未开通时请求会被拒绝。超过 3000 字符的文本仍需要自行切分，分段请求后再拼接音频。

进阶用法二：生成字幕

需要字幕时，同时设置 ignore_limit 为 true、gen_srt 为 true，并把 audio_type 设为 wav。只有这个组合才会返回字幕，其他音频格式不返回。字幕文件地址在响应头 srt_address 中，生成字幕需要额外付费。可以用 srt_len 控制单条字幕的最大长度，中文文本会在逗号、句号、感叹号、问号、分号等标点处自动断句。

进阶用法三：流式输出

对首包延迟敏感的场景，可以把 streaming 设为 true。生效条件是 ignore_limit 为 true 且 audio_type 不为 wav，此时接口以流式方式返回音频，客户端可以边接收边播放。需要注意，流式接口不支持 pitch 与 symbol_sil 两个参数。

进阶用法四：调整停顿与语气

如果希望标点处的停顿更可控，可以用 symbol_sil 指定各类符号对应的停顿时长，例如 semi_200,exclamation_200,question_200,comma_200,stop_200，该能力需要充值后开通。如果更在意整体语气自然度，可以改用 merge_symbol=true 打开粗粒度合成，此时停顿更接近真人，但 symbol_sil 会失效，两者不要同时依赖。

注意事项

• 签名有效期：签名有效期为 10 分钟，且必须每次请求实时计算。缓存签名或复用旧时间戳都会导致校验失败。
• 时间戳单位：timestamp 使用秒级时间戳，误用毫秒会让签名与请求体不一致。
• 文本长度：默认上限 1000 字符，开启 ignore_limit 后上限 3000 字符。超长文本需要自行分段。
• 字幕限制：只有 ignore_limit=true 且 audio_type=wav 时才可能返回字幕，其他格式不返回；字幕生成额外计费。
• 参数互斥：merge_symbol=true 会让 symbol_sil 失效；流式接口不支持 pitch 与 symbol_sil。
• 发音人耗时：pro 发音人的合成时长相对较长，对响应时间敏感的场景要谨慎选择。
• 响应类型判断：成功返回音频流，失败返回 JSON，客户端必须先判断内容类型再决定解析方式，否则会把错误信息当成音频写入文件。
• 网络与代理：若网络环境需要代理或防火墙放行，配置不当会导致请求被阻断，表现为连接失败而非接口报错。
• 凭据安全：secret 只应在服务端参与签名计算，不要下发到客户端，也不要提交到代码仓库。
• 计费与权限：发音人价格、字幕费用、长文本与停顿映射等权限的开通条件会随平台调整，具体以官网当前信息为准。

把上面的流程跑通之后，剩下的工作就是按业务需要封装：把签名计算抽成函数、把音频写入对象存储、把错误码映射成可读提示，并在文本切分与并发控制上做好边界处理。