HTTP 接口

mizuoto webui 启动的服务器同时提供网页界面和 HTTP 接口。网页界面能做的事都通过这套接口完成，所以脚本和其他程序也能做同样的事。

地址与文档复制锚点链接

端口以实际启动的为准（默认 7869，被占用时会顺延，见 命令行概览）。用 mizuoto webui --api-prefix /voice 启动时，上表的所有地址（接口、文档、socket 和网页界面）都移到这个前缀下，例如 http://127.0.0.1:7869/voice/api/v1/...、http://127.0.0.1:7869/voice/v1/audio/speech。

OpenAPI 结构里也列出了 socket 推送的事件类型，可以用它生成客户端类型。

资源一览复制锚点链接

所有 REST 路由都在 /api/v1 下：

每个字段的说明见 /docs 或 /openapi.json。

与命令行一致复制锚点链接

每个操作在核心里只有一个方法，接口和命令行都只是解析参数、调用它、再输出结果。所以列表和查询类命令的 mizuoto … --json 与对应接口返回的 JSON 结构相同，例如 mizuoto model list --json 与 GET /api/v1/models。例外是 mizuoto speak --json，它打印 {"job": …, "outputs": […]}，比接口多附上了结果记录。

已加载的模型与检查复制锚点链接

GET /api/v1/engines/{id}/doctor 给出单个引擎的检查结果。模型在服务器的进程中，这些路由描述的就是这个进程。

错误复制锚点链接

出错时返回对应的 HTTP 状态码和统一的结构：

{"code": "not_found", "message": "Unknown model: nope/x", "detail": {"kind": "model", "id": "nope/x", "hint": "mizuoto model list"}}

detail 随错误而不同；detail.hint 存在时是一条能解决问题的命令或说明。请求体本身不合法（缺字段、类型不对）时是 FastAPI 的 422，结构为 {"detail": [...]}。

访问控制本身的拒绝另有三种：bad_host（400）、bad_origin（403）、auth_required（401）。

访问控制复制锚点链接

每个请求依次经过三项检查（mizuoto/api/security.py）：

1. Host 头。 服务器绑定在本机地址（默认 127.0.0.1）时，Host 必须是 localhost、127.0.0.1、::1、绑定的地址，或嵌入方用 extra_hosts / allow_host() 加入的名称，否则返回 400 bad_host。这可以防止 DNS 重绑定。绑定到非本机地址（如 0.0.0.0）时不检查 Host。
2. 来源（Origin）。 改变状态的请求（GET、HEAD、OPTIONS 以外）和 WebSocket，如果带 Origin，它必须是页面自己的来源或列在 server.allowed_origins 中，否则返回 403 bad_origin；没有 Origin 但 Sec-Fetch-Site 表明是跨站请求时同样拒绝。curl、Python 等非浏览器客户端不带这些头，不受影响。server.allowed_origins 非空时服务器还会为这些来源开启 CORS。
3. 访问令牌。 设置了 server.access_token 时，/api/、/ws/、/v1/、/openapi.json 和 /docs 下的每个请求都要带上令牌，否则返回 401 auth_required。唯一的例外是 GET /api/v1/app/health。令牌可以用以下任一方式提供：

mizuoto config set server.access_token "一个足够长的随机字符串"

网页界面遇到 401 时会弹出 访问令牌 对话框，要求输入一次。

只能在本机使用的路由复制锚点链接

下面这些路由会读写服务器磁盘上的任意位置，只接受服务器本机的浏览器（客户端地址和请求的主机名都是本机回环地址），否则返回 403 not_local。通过隧道或同机反向代理转发的请求不算本机。

其中浏览和登记的路径还必须位于 paths.browse_roots 之内（留空时为主文件夹、数据文件夹和所有驱动器/卷）。远程客户端请改用上传：PUT /audio/files，或按角色上传权重 PUT /voices/{id}/weights/{engine}/{role}。

任务复制锚点链接

耗时的操作（合成、下载、训练、项目生成……）返回一个任务（Job），而不是等它完成：

{"id": "j1a13058b6acbeab2259", "kind": "speak", "state": "queued", "progress": null, "result": null, "error": null, ...}

state 依次经过 queued、waiting（等待 GPU、引擎或其他资源，waiting_for 说明在等什么）、running，最后是 completed、failed、cancelled 或 interrupted（服务器在任务运行中退出）。完成后 result 中有结果，失败时 error 有 code、message、detail。

合成可以直接等待结果：POST /api/v1/tts/speak?wait=true&timeout=600。任务结束后返回完成的任务，result.output_id（批量时为 result.output_ids）是结果的 id；超过 timeout 秒（默认 600，最多 3600）仍未结束时返回 504 timeout，detail.job_id 是仍在继续运行的任务，之后照常查询即可。

结果音频用 GET /api/v1/outputs/{id}/content 下载，GET /api/v1/outputs/{id} 返回它的参数、时长、采样率和生成耗时。

不想轮询的话，订阅 事件 中的 job_updated。

示例复制锚点链接

合成并下载复制锚点链接

BASE=http://127.0.0.1:7869
AUTH="Authorization: Bearer $MIZUOTO_TOKEN"   # 没有设置令牌时可省略

job=$(curl -s -H "$AUTH" -H "Content-Type: application/json" \
  "$BASE/api/v1/tts/speak?wait=true" \
  -d '{"model": "qwen3tts/1.7b-custom-voice", "text": "你好，欢迎使用 Mizuoto。", "voice_spec": {"preset": "vivian"}, "style": {"instruct": "语气轻快"}}')
id=$(echo "$job" | jq -r .result.output_id)
curl -s -H "$AUTH" "$BASE/api/v1/outputs/$id/content" -o hello.wav

请求体就是 SpeakRequest，主要字段如下（完整定义见 /docs）：

voice、voice_spec 都不给时使用模型自带的音色（模型需支持）。只想检查请求而不运行，用 POST /api/v1/tts/plan，它返回分段、生效的参数和警告。请求中没有的顶层字段会被忽略（这样发送新版本字段的客户端仍能工作），并在警告中列出（“Ignored fields the request does not have: …”）：引擎选项应放在 engine_options 中，写成 options 会被忽略。音色转换和语音编辑会把这类字段记入日志。

上传一段音频并克隆复制锚点链接

PUT /api/v1/audio/files 的请求体就是文件本身（不是 multipart），name 查询参数给出文件名。返回的 id 作为参考音频的 audio_id：

audio_id=$(curl -s -H "$AUTH" -X PUT --data-binary @ref.wav \
  "$BASE/api/v1/audio/files?name=ref.wav" | jq -r .id)

curl -s -H "$AUTH" -H "Content-Type: application/json" "$BASE/api/v1/tts/speak?wait=true" -d @- <<EOF
{"model": "qwen3tts/1.7b-base", "text": "这是克隆出来的声音。",
 "voice_spec": {"references": [{"audio_id": "$audio_id", "transcript": "参考音频里说的话。"}]}}
EOF

不给 transcript 时，若开启了 tts.auto_transcribe 且已下载语音识别模型，会自动识别；否则模型要支持无文本克隆。想长期使用这个音色，把它加进音色库（POST /api/v1/voices），之后用 "voice": "<id>" 引用。

事件复制锚点链接

服务器通过 socket.io 推送事件，挂在 /ws（socket.io 路径 /ws/socket.io）。推送只有服务器到客户端一个方向；所有操作仍走 REST，REST 的结果是准的，事件只用来及时刷新。

import socketio  # pip install "python-socketio[client]"

sio = socketio.Client()

@sio.on("job_updated")
def on_job(data):
    job = data["job"]
    print(job["id"], job["state"], job["progress"])

sio.connect("http://127.0.0.1:7869", socketio_path="/ws/socket.io", auth={"token": "<令牌>"})
sio.wait()

流式合成复制锚点链接

WebSocket：/api/v1/tts/stream复制锚点链接

边生成边收到音频。协议如下：

1. 客户端发送一条 JSON 文本消息，内容是一个 SpeakRequest。
2. 服务器回复 {"type": "queued", "job_id": …}。
3. 开始生成时回复 {"type": "start", "job_id": …, "sample_rate": 24000, "granularity": "token" | "segment" | "emulated"}。
4. 之后是二进制消息：单声道 16 位小端 PCM，采样率为 start 中的值；每一段开始前有一条 {"type": "segment", "index": n}。
5. 最后是 {"type": "end", "job_id": …, "output_ids": […], "output_id": …}，或 {"type": "error", "code", "message", "detail"}。

二进制消息一定是音频，其他消息都是 JSON 文本。整段结果仍然照常保存为一个结果（output_id）。客户端随时可以发送 {"type": "cancel"} 取消。

granularity 说明音频有多“细”：token 是模型逐 token 输出（CosyVoice、VoxCPM、Qwen3-TTS），segment 是每段一次，emulated 是模型本身不分段输出、由 Mizuoto 切分文本来模拟。

流式文本输入：模型支持 流式文本输入（CosyVoice 2 和 3）时，请求中设 "text_stream": true，text 只是开头；之后发送 {"type": "text", "text": "…"} 追加文本，最后发送 {"type": "flush"}。在 flush 之前断开连接会取消任务。

import asyncio, json
import websockets  # pip install websockets

async def main():
    url = "ws://127.0.0.1:7869/api/v1/tts/stream?token=<令牌>"
    req = {"model": "cosyvoice/cosyvoice2-0.5b", "text": "边生成边播放。", "voice": "my-voice"}
    pcm = bytearray()
    async with websockets.connect(url) as ws:
        await ws.send(json.dumps(req))
        async for message in ws:
            if isinstance(message, bytes):
                pcm += message           # 交给播放器，或累积起来
                continue
            event = json.loads(message)
            if event["type"] == "start":
                rate = event["sample_rate"]
            elif event["type"] in ("end", "error"):
                print(event)
                break
    print(len(pcm) // 2 / rate, "秒")

asyncio.run(main())

HTTP：POST /tts/speak?stream=true复制锚点链接

不方便用 WebSocket 时，同一个请求加上 stream=true，响应就是边生成边发送的音频（分块传输）：

响应头 X-Mizuoto-Sample-Rate 是采样率，X-Mizuoto-Job 是任务 id（结果仍会保存）。这种方式不支持流式文本输入。

curl -sN -H "$AUTH" -H "Content-Type: application/json" \
  "$BASE/api/v1/tts/speak?stream=true" \
  -d '{"model": "qwen3tts/1.7b-custom-voice", "text": "边生成边播放。", "voice_spec": {"preset": "vivian"}}' \
  | ffplay -nodisp -autoexit -

兼容 OpenAI 的接口复制锚点链接

为 OpenAI 语音接口编写的客户端可以直接使用 Mizuoto。这两个路由在 /v1 下（不在 /api 下；有 --api-prefix 时在 <前缀>/v1），同样需要访问令牌：

请求字段的对应关系：

这个接口按宽松模式处理参数：模型不接受的参数被丢弃，而不是报错。错误采用 OpenAI 的格式 {"error": {"message", "type", "param", "code"}}，其中 code 是 Mizuoto 的错误代码。成功的响应带有 X-Mizuoto-Job 和 X-Mizuoto-Model 头。

先给常用的名字起别名：

mizuoto config set tts.model_aliases '{"tts-1": "qwen3tts/1.7b-custom-voice", "tts-1-hd": "cosyvoice/cosyvoice3-0.5b"}'
mizuoto config set tts.default_model qwen3tts/1.7b-custom-voice

from openai import OpenAI

# api_key：设置了访问令牌时填令牌，否则任意字符串
client = OpenAI(base_url="http://127.0.0.1:7869/v1", api_key="<令牌>")

with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="vivian",
    input="你好，这是兼容 OpenAI 的接口。",
    instructions="用平静的语气",
    response_format="mp3",
) as response:
    response.stream_to_file("speech.mp3")

下一步复制锚点链接

• 在 Python 中使用：不经过 HTTP，直接调用核心服务，或把服务器嵌入自己的程序。
• 命令行：同样的操作在终端里完成。
• 远程主机：让引擎在另一台机器上运行。