Delia TTS API

面向开发者与 AI Agent 的调用文档

给 AI 的最短说明

调用 POST https://tts.delia.love/api/tts，请求头携带 X-API-Key，JSON body 至少包含 text。成功响应是 MP3 二进制数据，不是 JSON。

认证

所有 TTS 请求都必须提供有效且已启用的 API Key：

X-API-Key: dtts_YOUR_API_KEY

也可以使用 Authorization: Bearer dtts_YOUR_API_KEY。不要同时发送两种认证头。

合成语音

POSThttps://tts.delia.love/api/tts
字段类型必填说明
textstring是需要朗读的纯文本，硬上限 5000 字符；建议单次 ≤ 2000 汉字，详见字数限制
voicestring否声音名称，默认 zh-CN-XiaoxiaoNeural
ratestring否语速，例如 +20% 或 -10%，默认 +0%
pitchstring否音高，例如 +5Hz，默认 +0Hz
volumestring否音量，例如 +10%，默认 +0%

字数限制与耗时参考

上游（Microsoft Edge TTS）的真实限制不是字符数，而是单次合成的音频时长约 10 分钟。按 1 倍语速换算，中文约 2500–2800 字封顶，超过会返回 502；语速调快（如 rate: "+100%"）单位时间读得更多，可容纳的字数相应增加。

建议：单次请求控制在 2000 汉字（或 3000 英文词）以内；追求响应速度时按句或按段切分（每次几十到几百字）并发请求，客户端再按顺序播放或拼接——同为 24kHz/48kbps 单声道 MP3，分段音频可直接按字节顺序拼接。

实测耗时参考（中文、1 倍速、zh-CN-XiaoxiaoNeural，含网络往返）：

文本长度音频时长响应时间（约）
一句话（约 20 字）数秒0.5–1 秒
500 字≈ 1.8 分钟3–4 秒
1000 字≈ 3.6 分钟6–8 秒
2000 字≈ 7 分钟12–15 秒
2500 字≈ 9 分钟18–20 秒
3000 字以上超过 10 分钟上限失败（502）

响应时间与文本长度大致成正比（合成是实时流式的，约每秒生成 30 秒音频）。注意服务端单次请求总时限 60 秒，长文本请务必分段。

成功响应

状态码 200，Content-Type 为 audio/mpeg，响应体是 MP3 文件字节。客户端应保存为 .mp3、创建 Blob，或直接送入音频播放器。

声音列表

GEThttps://tts.delia.love/api/voices

返回 Microsoft Edge TTS 可用声音的 JSON 数组。使用每项的 ShortName 作为合成请求的 voice。

机器可读 OpenAPI

GEThttps://tts.delia.love/api/openapi.json

支持 OpenAPI 3.1 的 AI Agent、ChatGPT Action、Postman 或代码生成工具可以直接导入这个地址，自动识别接口、参数、认证方式和响应类型。

打开 OpenAPI JSON →

代码示例

curl

curl -X POST https://tts.delia.love/api/tts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dtts_YOUR_API_KEY" \
  -d '{"text":"你好，世界","voice":"zh-CN-XiaoxiaoNeural","rate":"+0%"}' \
  --output speech.mp3

JavaScript

const response = await fetch("https://tts.delia.love/api/tts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "dtts_YOUR_API_KEY"
  },
  body: JSON.stringify({
    text: "你好，世界",
    voice: "zh-CN-XiaoxiaoNeural",
    rate: "+0%"
  })
});

if (!response.ok) throw new Error(await response.text());
const audioBlob = await response.blob();

Python

import requests

response = requests.post(
    "https://tts.delia.love/api/tts",
    headers={"X-API-Key": "dtts_YOUR_API_KEY"},
    json={
        "text": "你好，世界",
        "voice": "zh-CN-XiaoxiaoNeural",
        "rate": "+0%",
    },
)
response.raise_for_status()
open("speech.mp3", "wb").write(response.content)

错误响应

错误响应是 JSON：{"error":"错误信息"}

状态码含义
400JSON 无效、缺少 text 或参数错误
401缺少、无效或已停用的 API Key
413文本超过 5000 字符
502上游语音合成失败（常见原因：文本过长，音频超过约 10 分钟上限，请分段）
503API Key 数据库暂时不可用

AI Agent 行为要求

  • 不要虚构 API Key；缺少 Key 时向用户索取。
  • 将成功响应按二进制处理，不要尝试解析为 JSON 或文本。
  • 需要选择声音时，先调用 /api/voices。
  • 不要把真实 API Key 写入公开代码、日志或回答正文。