适用场景什么时候需要调用文本转语音文本转语音Text-to-Speech, TTS是将书面文字转换为自然语音的技术。在日常开发中您可能会遇到以下需要合成语音的场景新闻资讯播报后端从RSS或CMS获取新闻正文通过TTS接口生成音频供移动端或智能音箱播放。短视频配音创作者将字幕文案批量合成语音避免真人录音的人力维护复杂度与时间消耗。有声书制作将电子书章节逐段传入接口产出连续的有声内容。语音通知与提醒在订单状态变更、告警触发时动态生成语音文件推送给用户。客服IVR交互式语音应答根据用户按键选择合成对应的语音提示菜单。这些场景的共同特点是“文字动态变化、无法预先录制”因此需要一个高效的合成接口。本文要介绍的TTS语音合成API来自alapi.cn通过一次POST请求即可获得MP3格式的音频数据支持5种不同风格的中文音色特别适合国内开发者快速集成。接口能力边界了解限制才能正确使用在编写代码之前明确接口的约束条件可以避免大部分调用失败单次合成文本长度1~500字符。中英文均按1字符计数标点符号、空格均计入。如果您的文本超过500字符需要手动截断或分段合成后拼接音频。音色选择目前提供5种预置音色通过voice_type参数指定female_zhubo女声主播默认male_zhubo男声主播male_rap男声说唱female_sichuan女声四川话male_db男声低沉输出格式接口返回base64编码的MP3音频同时提供一个可直接用于HTMLaudio标签的data URLaudio_data_url以及音频字节数等信息。QPS限制每秒最多3次请求。若短时间内并发过高将收到429状态码。建议在业务中做好请求排队或限流。鉴权方式调用需携带API Key。支持两种方式X-API-Key请求头或标准的Authorization: Bearer sk_live_xxx。下面示例均使用X-API-Key。不缓存策略500字符的音频约1MB重复请求概率低因此服务端不提供结果缓存。每次请求都会实时合成请合理控制请求频率。请求参数与鉴权详解请求基本信息项目值接口地址https://v1.apizero.cn/api/tts请求方法POSTContent-Typeapplication/json或application/x-www-form-urlencoded请求头Header参数名是否必填类型说明示例值X-API-Key是除非匿名调用string您的API Key格式sk_live_xxxxxxxxxxxxxxsk_live_xxxxxxxxxxxxxxContent-Type否string默认可省略建议显式指定application/json注意匿名调用每日有10次调用次数限制无需传API Key但生产环境强烈建议使用正式Key。请求体Body以JSON格式为例请求体是一个包含两个字段的JSON对象字段类型必填说明示例值textstring是待合成的文本1~500字符欢迎使用语音合成服务voice_typestring否音色代码默认female_zhubofemale_zhubocurl 实战一条命令合成语音下面是一个完整的curl请求请将$APIZERO_API_KEY替换为您自己的API Key。curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {text: 今天天气真好适合出门走走。, voice_type: female_zhubo} \ https://v1.apizero.cn/api/tts执行后终端将输出一个JSON字符串。如果请求成功code字段为0data中包含音频数据。进阶保存音频到文件若想将返回的base64音频解码为MP3文件可以配合jq和base64命令Linux/macOScurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {text: 测试音频保存为文件。} \ https://v1.apizero.cn/api/tts | jq -r .data.audio | base64 -d output.mp3Windows用户可使用PowerShell$response Invoke-RestMethod -Uri https://v1.apizero.cn/api/tts -Method Post -Headers {X-API-Key你的APIKey} -Body ({text测试音频; voice_typefemale_zhubo} | ConvertTo-Json) -ContentType application/json $base64 $response.data.audio [System.IO.File]::WriteAllBytes(output.mp3, [System.Convert]::FromBase64String($base64))返回值字段解读成功响应HTTP 200示例{ code: 0, msg: 成功, request_id: abc123def456, data: { audio: SUQzAwAAAAAAA...base64字符串, audio_data_url: data:audio/mpeg;base64,SUQzAwAAAAA..., audio_format: mp3, audio_mime: audio/mpeg, audio_size_bytes: 12750, text: 欢迎使用语音合成服务, text_length: 10, voice_desc: 标准普通话女声主播风格适合资讯播报, voice_name: 女声主播, voice_type: female_zhubo } }关键字段说明audiobase64编码的MP3音频数据。长度约为原始音频的4/3倍500字符音频大约对应17000字符的base64字符串。audio_data_url拼接好的Data URL可以直接赋值给HTMLaudio标签的src属性播放。audio_size_bytes解码后的MP3文件字节数可用于进度条或带宽预估。audio_format/audio_mime音频格式与MIME类型固定为mp3/audio/mpeg。voice_desc/voice_name当前使用的音色描述与名称便于调试时确认。text/text_length回传的原始文本及其长度可用于校验请求是否被正确接收。常见错误码与排查思路非0 code典型原因处理方式1001参数缺失或格式错误检查text字段是否为非空字符串长度是否在1~500之间检查JSON格式是否合法。1002鉴权失败API Key无效或未提供确认X-API-Key请求头正确设置且Key未过期。匿名调用每日10次用完也会返回此错误。1003文本超长500字符截短文本或分段多次请求。1004不支持的voice_type检查音色代码是否在可选列表中。1005内部合成超时或上游服务异常稍后重试若持续失败请联系技术支持。429请求频率超过QPS限制3次/秒增加调用间隔或使用队列控制并发。所有错误响应均会返回code、msg和request_id字段msg描述具体原因。请务必记录request_id以便在需要时反馈给服务端排查。工程化注意事项1. 音频播放方式在Web前端中可以通过fetch发起请求获取JSON然后直接用返回的audio_data_url播放const response await fetch(https://v1.apizero.cn/api/tts, { method: POST, headers: { X-API-Key: sk_live_xxxxxxxxxxxxxx, Content-Type: application/json }, body: JSON.stringify({ text: 你好世界, voice_type: female_zhubo }) }); const json await response.json(); if (json.code 0) { const audio new Audio(json.data.audio_data_url); audio.play(); }2. 长文本分段策略当文本超过500字符时需要分割后逐个请求然后在前端或后端拼接音频。分割时最好按句子边界句号、问号、感叹号断开避免切断词语导致听感不连贯。拼接操作可在后端使用FFmpeg或前端Web Audio API实现。3. 请求频率控制生产环境建议使用令牌桶或滑动窗口限流保证每秒不超过3次请求。若使用Node.js可借助bottleneck库Python可使用aiolimiter。4. 失败重试与幂等处理对于非参数错误如超时、5xx可实现指数退避重试。由于每次请求的text不同天然幂等无需额外处理。5. 安全存储API Key不要在客户端代码中硬编码API Key。建议服务端封装一层代理接口将敏感Key保护在服务器端。参考文档TTS语音合成 接口文档原始Markdown文档