文档/API Reference

文字转语音 API

通过一个同步 HTTP 接口生成沢渡雫 AI 合成语音。请求完成后返回私有对象存储中的限时试听与下载链接，适合网页、工作流和后端服务集成。

正在检查服务 WAV · PCM 16-bit · Mono 中 / 日 / 英同步响应

Base URL

文档会自动使用当前服务地址。当前页面对应 正在读取…。

AI 合成内容声明

所有输出均为 AI 生成语音，不是角色、作品官方或声优本人的真实录音。公开或商业使用前，请自行确认相关权利与许可。

快速开始

向 POST /api/tts 发送 JSON。接口同步等待生成和对象存储上传完成，然后返回 JSON 下载信息。

POST /api/tts

curl --request POST \
  --url {BASE_URL}/api/tts \
  --header 'Authorization: <YOUR_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "こんばんは。今日も一緒に帰ろうね。",
    "language": "ja",
    "style": "gentle",
    "speed": 1.0
  }'

import requests

response = requests.post(
    "{BASE_URL}/api/tts",
    headers={
        "Authorization": "<YOUR_TOKEN>",
        "Content-Type": "application/json",
    },
    json={
        "text": "こんばんは。今日も一緒に帰ろうね。",
        "language": "ja",
        "style": "gentle",
        "speed": 1.0,
    },
    timeout=180,
)
response.raise_for_status()
result = response.json()

audio = requests.get(result["download_url"], timeout=60)
audio.raise_for_status()
with open(result["filename"], "wb") as file:
    file.write(audio.content)

const response = await fetch("{BASE_URL}/api/tts", {
  method: "POST",
  headers: {
    Authorization: "<YOUR_TOKEN>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "こんばんは。今日も一緒に帰ろうね。",
    language: "ja",
    style: "gentle",
    speed: 1.0
  })
})

if (!response.ok) {
  throw new Error(await response.text())
}

const result = await response.json()
console.log(result.download_url)

身份验证

除 /、/docs、/docs/openapi 和 /health 外，API 端点都要求在请求头传入访问令牌。

Header	格式	说明
`Authorization`必填	`<YOUR_TOKEN>`	推荐格式。直接发送服务方提供的固定令牌。
`Authorization`	`Bearer <YOUR_TOKEN>`	兼容 Bearer 格式；与直接令牌等价。

不要把令牌写进公开前端代码

浏览器内直接调用会让访问者看到令牌。面向公开用户时，应由你自己的后端代理请求。公网入口使用 HTTPS，但令牌仍不应写入公开前端代码。

生成语音

主要生产端点。请求会等待模型生成完成，因此客户端超时建议设置为至少 180 秒。短文本热启动通常更快，但不提供固定延迟 SLA。

POST /api/tts

Content-Type: application/json · Response: application/json

请求参数

字段	类型	默认值	约束与说明
`text`必填	string	—	待合成文本，首尾空白会被移除。当前公网限制 300 个 Unicode 字符。
`language`	enum	`ja`	jazhenauto
`style`	enum	`auto`	autoneutralgentlesademotionalreflective
`speed`	number	`1.0`	`0.5–2.0`。1.0 为原速，越小越慢，越大越快。
`top_k`	integer	`15`	`1–100`。语义采样候选数量；值越小通常越稳定。
`top_p`	number	`1.0`	`0.1–1.0`。核采样概率阈值，建议保持默认。
`temperature`	number	`1.0`	`0.1–1.5`。越高变化越大，稳定生成建议 0.8–1.0。
`seed`	integer	`-1`	`-1` 表示随机；固定 0–4294967295 可提高可复现性。
`device`	enum	`auto`	`auto \| cuda \| cpu`。当前公网实例始终覆盖为 `cpu`。
`precision`	enum	`auto`	`auto \| fp16 \| fp32`。当前公网实例始终覆盖为 `fp32`。

普通用户只需设置四项

绝大多数请求只需要 text、language、style 和 speed。采样参数保持默认值通常最稳定。

language 参数

值	用途	处理方式	建议
`ja`	日语	非英文片段使用日语前端和 OpenJTalk 读音。	纯日语文本首选。
`zh`	普通话中文	非英文片段使用中文规范化、拼音和 BERT 特征。	纯中文文本首选。
`en`	英语	整段文本强制使用英文 G2P。	纯英文文本首选。
`auto`	自动识别	逐段检测语言，混合文本分别进入相应前端。	语言未知或中日英混合时首选。

text 与 language 不一致时

接口不会预先拒绝，而是按照指定语言继续处理。中文汉字配 ja 可能产生日语音读；日语假名配 zh 可能漏读、错读或生成失败；非英文内容配 en 通常效果最差。不能保证标签正确时请使用 auto。

短汉字字符串本身可能无法可靠区分中文与日文，自动检测也不是绝对准确。若业务侧明确知道语言，显式传入 ja 或 zh 会更稳定。

style 参数

风格通过不同参考片段影响韵律、情绪和语气，不是保证固定强度的情绪分类器。

值	显示名称	适用场景
`auto`	自动推荐	日语使用 neutral，中文使用 reflective，英文使用 sad。
`neutral`	自然 / 中性	通用对白、说明、默认日语。
`gentle`	温柔 / 陪伴	柔和对白、安慰或陪伴语气。
`sad`	低落 / 悲伤	低沉、悲伤语气；当前英文自动推荐。
`emotional`	情绪化 / 强表达	情绪起伏更明显的对白。
`reflective`	沉思 / 叙述	平缓叙述、思考语气；当前中文自动推荐。

成功响应

成功时返回 HTTP 200 和 JSON。该接口不直接返回 WAV 二进制。

{
  "status": "completed",
  "generation_id": "20260804_043826_53a955ac",
  "ai_generated": true,
  "model_id": "shizuku-v2",
  "filename": "shizuku_v2_ai_20260804_043826_53a955ac.wav",
  "content_type": "audio/wav",
  "size_bytes": 93484,
  "sample_rate": 32000,
  "duration_seconds": 1.46,
  "inference_seconds": 4.925,
  "total_server_seconds": 4.925,
  "inference_device": "cpu",
  "inference_precision": "fp32",
  "model_reload_seconds": 0.0,
  "storage": "minio",
  "object_key": "audio/2026/08/04/shizuku_v2_ai_example.wav",
  "playback_url": "https://tts.suakitsu.com/shizuku-tts/audio/...signed-query...",
  "download_url": "https://tts.suakitsu.com/shizuku-tts/audio/...signed-query...",
  "download_url_expires_at": "2026-08-05T04:38:26+00:00",
  "download_url_ttl_seconds": 86400
}

字段	类型	说明
`status`	string	同步生成成功时固定为 `completed`。
`generation_id`	string	唯一生成 ID，用于日志关联。
`ai_generated`	boolean	固定为 `true`。
`model_id`	string	实际模型标识，当前为 `shizuku-v2`。
`filename`	string	建议保存的 WAV 文件名。
`content_type`	string	固定为 `audio/wav`。
`size_bytes`	integer	文件大小，单位字节。
`sample_rate`	integer	采样率，单位 Hz；实际以响应为准。
`duration_seconds`	number	音频时长，单位秒。
`inference_seconds`	number	模型推理耗时。
`total_server_seconds`	number	排队和推理总耗时。
`inference_device`	string	实际推理设备；公网实例为 `cpu`。
`inference_precision`	string	实际精度；公网实例为 `fp32`。
`model_reload_seconds`	number	设备或精度变化触发的模型重新加载耗时。
`storage`	string	当前固定为 `minio`。
`object_key`	string	私有对象键，不能直接无签名访问。
`playback_url`	string	适合 audio 标签或播放器使用的限时 URL。
`download_url`	string	带附件下载响应头的限时 URL。
`download_url_expires_at`	datetime	ISO 8601 格式的链接过期时间。
`download_url_ttl_seconds`	integer	链接有效秒数，当前为 86400。

下载链接与对象生命周期

playback_url

响应头为 inline，适合网页 <audio>、播放器和即时预览。

download_url

响应头为 attachment，适合保存文件或交付最终结果。

链接有效期

两个 URL 当前均为 24 小时。签名过期后会返回 403。

对象保存期

WAV 与元数据最多保留 7 天，由 MinIO 生命周期规则自动清理。

链接本身已经带签名，下载时不需要再传 Authorization。不要修改 URL 中的查询参数；任何签名改动都会导致 403。

健康状态

GET /health

无需鉴权。用于探针、部署检查以及读取动态限制，包括最大文本长度、并发上限、模型设备和对象存储状态。

curl {BASE_URL}/health

模型元数据

GET /api/metadata

需要鉴权。返回模型 ID、使用声明、支持语言、全部参考风格、各语言推荐风格及当前实际推理设备。

选择推理设备

POST /api/device

本地 GPU/CPU 版本可用它预加载指定设备。当前公网容器锁定为 CPU/FP32，因此即使传入 cuda 或 fp16，服务也会安全覆盖成 CPU/FP32。

错误响应与重试

状态码	含义	建议处理
200	生成完成	读取 JSON 中的试听或下载 URL。
401	鉴权失败	检查 Authorization 是否缺失、错误或包含多余空格。
422	参数校验失败	修正类型、枚举或取值范围；不要自动重试原请求。
429	队列已满	读取 `Retry-After`，等待后指数退避重试。
500	合成失败	记录响应与 generation 上下文，稍后重试或缩短文本。
502	对象存储上传失败	原音频可能未交付；稍后重新发起生成。
503	模型加载中或设备不可用	先轮询 `/health`，服务 ready 后再试。

{
  "detail": "missing or invalid Authorization header"
}

参数校验产生的 422 通常返回 detail 数组，其中包含字段位置、错误类型、说明和原始输入。

限制与性能

项目	当前公网实例	说明
最大文本长度	300 字符	以 `/health.max_text_length` 为准。
并发入口	10 个	超过上限立即返回 429。
实际模型推理	双实例并行	两个独立推理容器由 least_conn 入口分流，最多同时生成 2 条，其余已接收请求排队。
计算资源	CPU / FP32	每个推理容器固定 3 vCPU、4.5 GiB；入口容器上限 0.25 vCPU、128 MiB。
建议客户端超时	≥ 180 秒	冷启动、长文本或排队时会明显变慢。
幂等性	不支持	每次成功请求都会生成新的 generation_id 和对象。

实测短日语句子热启动约 5 秒，首次触发语言资源缓存时可能约 30 秒。这是当前硬件上的观测值，不是 SLA。

数据、安全与合规

私有对象存储

桶不公开；无签名访问返回 403。只有限时 URL 可下载。

保存内容

WAV 与生成元数据会保存，元数据包含请求文本和生成参数。

保留时间

对象生命周期当前为 7 天；测试或敏感文本不应直接提交。

传输安全

API 与 MinIO 签名下载链接均通过 https://tts.suakitsu.com 加密传输。

不要提交秘密或个人敏感信息

引擎运行日志和私有元数据可能包含完整输入文本。调用方应先完成数据分类、授权与必要的脱敏处理。

常见问题

为什么接口返回 JSON，而不是直接返回 WAV？

音频先进入对象存储，JSON 返回可交付给用户的下载链接，便于网页播放、任务记录和后续下载。

language 传错会自动报错吗？

不会。引擎会按指定语言继续处理，因此可能成功但发音错误，也可能在文本前端阶段失败。无法保证时请传 auto。

下载 URL 过期后还能直接使用 object_key 吗？

不能。桶是私有的，object_key 不是公开 URL。当前没有刷新签名接口；需要在链接有效期内完成下载。

可以同时请求很多段文本吗？

入口最多接受 10 个在途请求，两个模型实例最多同时生成 2 条，其余请求排队。批量任务仍应处理 429 与超时。

为什么同样文本每次听起来略有不同？

默认 seed=-1 会随机采样。使用固定非负 seed，并保持其他参数一致，可提高可复现性，但不能保证逐字节完全一致。