接入文档

一个 endpoint，一个 Authorization 头，拿回 mp3

鉴权

所有 API 请求需要在 HTTP 头里带上 Bearer 形式的 API key：

http

Authorization: Bearer JK********

登录控制台后在「API key」面板复制；激活码用完后请重新购买。

POST /api/v1/tts

将文本合成为语音，同步返回 mp3 字节流。

请求

http

POST /api/v1/tts HTTP/1.1
Host: vox.timor419.com
Authorization: Bearer JK********
Content-Type: application/json

{
  "text": "你好世界",
  "voice_id": "云楚灵"
}

字段	类型	必填	说明
text	string	是	要合成的文本，1-2000 字符
voice_id	string	否	音色 ID（首页可试听挑选）。省略则用平台默认

响应

成功返回 200 OK， body 是 mp3 字节流。附加信息在响应头：

字段	类型	必填	说明
Content-Type	header	否	audio/mpeg
X-Request-Id	header	否	本次请求唯一 ID
X-Voice-Id	header	否	实际使用的音色（URI-encoded）
X-Units	header	否	本次扣费的字符数
X-Remaining	header	否	剩余余额

代码示例

curl

bash · curl

curl -X POST https://vox.timor419.com/api/v1/tts \
  -H "Authorization: Bearer JK********" \
  -H "Content-Type: application/json" \
  -d '{"text":"你好世界","voice_id":"云楚灵"}' \
  --output hello.mp3

Python

python

import requests

resp = requests.post(
    "https://vox.timor419.com/api/v1/tts",
    headers={"Authorization": "Bearer JK********"},
    json={"text": "你好世界", "voice_id": "云楚灵"},
    timeout=60,
)
resp.raise_for_status()
with open("hello.mp3", "wb") as f:
    f.write(resp.content)
print("remaining:", resp.headers.get("X-Remaining"))

Node.js

javascript

import { writeFile } from "node:fs/promises";

const res = await fetch("https://vox.timor419.com/api/v1/tts", {
  method: "POST",
  headers: {
    Authorization: "Bearer JK********",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "你好世界", voice_id: "云楚灵" }),
});
if (!res.ok) throw new Error(`tts failed: ${res.status}`);
await writeFile("hello.mp3", new Uint8Array(await res.arrayBuffer()));
console.log("remaining:", res.headers.get("X-Remaining"));

错误码

HTTP	code	说明
400	invalid_params	text 缺失 / 超长（> 2000 字）/ JSON 格式错误
401	missing_api_key	Authorization 头缺失或格式错误
401	invalid_api_key	API key 不存在或已被删除
402	insufficient_balance	余额不足，请重新购买激活码
403	account_disabled	账户被停用，请联系客服
403	api_key_revoked	API key 已被吊销
429	rate_limited	调用过快（60 次/分钟/key）
502	synthesis_failed	底层引擎合成失败，可重试
504	synthesis_failed (timeout)	底层引擎超时，可重试

限流 + 计费

单个 API key：60 次/分钟。超过返回 429 + Retry-After 头。
按字符计费：1 中文字符 = 1 字符；英文字母、空格、标点、数字也各算 1 字符。
扣费幂等：调用失败时不扣费；调用成功扣费一次。（每次请求生成唯一 request_id，可在用量历史中查看。）
单次最长 2000 字符；更长请客户端拆段调用。