Matchering 2.0 API 使用详解

目标：面向需要把 Matchering 2.0 母带能力接入自动化流水线的读者，逐端点实测官方 Web 应用内置的 HTTP API——会话创建、目标/参考音轨上传、状态轮询与结果下载，给出可直接执行的 curl 全流程与状态码手册。所有请求与响应均在《Matchering 2.0 Docker Compose 部署指南》部署的 2.0.6 环境实测取得。

一、环境信息

本文 API 实测环境如下：

💡 说明：这套 HTTP API 是 Web 界面自身使用的内部接口（前端页面即调用它工作），官方未将其作为对外契约文档化，接口形态以 2.0.6 源码为准——这正是本文逐端点实测的价值所在。若需要更完整的编程参数控制（采样率、位深、限制器等），应改用 Python 库而非此 HTTP API，参数层面见《Matchering 2.0 配置参数详解》。

二、前置条件

1. 已按《Matchering 2.0 Docker Compose 部署指南》完成部署，服务在本机 8141 端口可达；
2. 验证服务可达（首页 HTML 返回 200）：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8141/

实测回显：

200

3. 准备两条测试音轨（目标轨与参考轨），格式要求：立体声、无损 WAV/FLAC 优先（MP3 需 FFmpeg 且会触发 3004 有损警告）；
4. 无需认证——API 未设任何鉴权（REST_FRAMEWORK 配置 UNAUTHENTICATED_USER: None），这也是它只适合内网使用的原因，公网暴露风险见 B2 篇常见问题。

三、API 总览

全部端点共 3 个，统一挂在 /api/ 前缀下（路由源码 mgw_back/urls.py 经主 URLconf include 到 api/），围绕「会话」这一核心资源组织：

⚠️ 实测排障注记：不带 /api/ 前缀访问 /session/ 会得到 Django 404 调试页。该页反而列出了全部 URL 模式（api/、media/...、favicon），是定位前缀的最快途径——这也是官方镜像 DEBUG=True 的一个副作用（公网暴露会泄漏路由表，见 B2 篇安全提醒）。

通用约定：

• 认证：无。所有端点匿名可用；
• 格式：请求体除上传外为 JSON（Content-Type: application/json）；上传为 multipart，文件字段名固定 file；
• 状态模型：会话状态由 4 位数字 code 表达（2001 上传中 → 2002 排队处理 → 2003~2009 处理各阶段 → 2010 完成；4xxx 为错误），全量码表见第七节；
• 数据留存：会话与上传文件默认保留 60 分钟（MGW_STORE_DATA_FOR_MINUTES = 60），过期后由下一次创建会话的操作触发清理，token 失效返回 404；
• 处理模型：异步。上传两条音轨后任务进入 Redis 队列（django-rq），由内置 worker 执行，客户端轮询 code 直至 2010。

四、创建会话（POST /api/session/）

创建会话是全流程第一步，返回的 token 是后续上传与轮询的凭据。

4.1 最简调用

curl -s -X POST http://127.0.0.1:8141/api/session/ \
  -H "Content-Type: application/json" \
  -d '{}'

实测回显（单行 JSON）：

{"token":"ywfV9EtPbSjHAcXu63irybmoBrPYRjC3","target":null,"reference":null}

响应字段：token（32 位随机串，会话唯一凭据）、target 与 reference（两条音轨的文件名，创建时为 null）。请把 token 存入 shell 变量，后续命令都要用：

TOKEN=$(curl -s -X POST http://127.0.0.1:8141/api/session/ \
  -H "Content-Type: application/json" -d '{}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
echo "$TOKEN"

实测回显：

IYoUnUkJpeCBJ9AUdLl4mcZuaST4Yf46

4.2 请求体参数

POST /api/session/ 支持三个可选 JSON 字段（源码 SessionCreate.post），用于「复用上一会话素材」的场景：

约束：keep_target 与 keep_reference 不能同时为 true（源码直接抛 ValidationError）；previous 指向的会话不存在时按无继承处理。换参考轨重跑同一目标（调音师最常见的动作）即 { "previous": "<旧token>", "keep_target": true }。继承后旧会话被删除，素材转到新会话名下。

五、上传音轨（POST /api/upload/<token>/<file_type>/）

5.1 端点语义

file_type 路径参数只能取 target（待母带的曲目）或 reference（参考曲），multipart 文件字段名固定为 file。两条音轨都上传成功后，服务端把会话置为 2002 并立即把任务投入队列（源码 UploadFile.post）。

5.2 上传目标轨

curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST "http://127.0.0.1:8141/api/upload/${TOKEN}/target/" \
  -F "file=@/opt/matchering/data/target.wav"

实测回显：

201

5.3 上传参考轨（自动触发处理）

curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST "http://127.0.0.1:8141/api/upload/${TOKEN}/reference/" \
  -F "file=@/opt/matchering/data/reference.wav"

实测回显：

201

两个 201 即两条音轨落库成功、处理任务已排队。上传后立刻轮询一次可看到 2002（排队）：

curl -s "http://127.0.0.1:8141/api/session/${TOKEN}/"

实测回显：

{"created":"2026-10-30T03:46:02.211131","code":2002,"target":"target","reference":"reference","result16":null,"result24":null,"preview_target":null,"preview_result":null,"warnings":[]}

5.4 重复上传与顺序的行为

源码约束：同一 file_type 已有文件或会话 code 已非 2001 时，上传直接 400（ValidationError）。因此先传 target 后传 reference 或反之均可（本文实测为先 target 后 reference），但每类只能传一次；传错想换文件只能开新会话。

六、全流程实战：从两条 WAV 到母带结果

6.1 准备测试音轨

无现成音轨时，用 ffmpeg 合成两条风格不同的测试音即可（20 秒短音足以完成流程验证；ffmpeg 在 Matchering 运行环境内自带，宿主机没有时可直接在部署环境执行同款命令）：

ffmpeg -y -v error -f lavfi -i "sine=frequency=220:duration=20" \
  -af "tremolo=f=2:d=0.7,volume=0.35" -ac 2 -ar 44100 -sample_fmt s16 target.wav
ffmpeg -y -v error -f lavfi -i "sine=frequency=262:duration=20" \
  -af "tremolo=f=2:d=0.4,volume=0.85" -ac 2 -ar 44100 -sample_fmt s16 reference.wav
ls -la target.wav reference.wav

实测回显：

-rw-r--r-- 1 root root 3528078 Oct 30 03:46 reference.wav
-rw-r--r-- 1 root root 3528078 Oct 30 03:46 target.wav

音轨规格核对（ffprobe -v error -show_entries stream=codec_name,channels,sample_rate -of csv=p=0 target.wav）：

pcm_s16le,44100,2

即 44100 Hz、双声道、16-bit PCM——正是 Matchering 的理想输入格式（无需重采样、无需声道转换）。

6.2 轮询至完成

上传完成后轮询（20 秒短音轨处理极快，本文实测首次轮询即已完成；长曲目按需间隔轮询）：

curl -s "http://127.0.0.1:8141/api/session/${TOKEN}/" | python3 -m json.tool

处理完成时的实测回显：

{
    "created": "2026-10-30T03:46:02.211131",
    "code": 2010,
    "target": "target",
    "reference": "reference",
    "result16": "/media/Matchering_16bit_target_BCvo.wav",
    "result24": "/media/Matchering_24bit_target_RTNw.wav",
    "preview_target": "/media/dloLjdxhZMNiInLp.flac",
    "preview_result": "/media/5rTG3I84V9UzWWFx.flac",
    "warnings": [
        3002
    ]
}

字段解读：code: 2010 表示任务完成；result16/result24 是 16-bit 与 24-bit 两档 WAV 母带的服务端媒体路径（本身就是可拼在主机名后的相对 URL）；preview_target/preview_result 是 FLAC 预览；target/reference 回显原始文件名；warnings 是处理过程中的 3xxx 警告码数组（本例实测出现的 3002 = 目标轨疑似带限制器痕迹的保守提示，不阻断任务，见第七节）。

6.3 下载结果

结果文件挂在服务的 /media/ 路径下（平铺，文件名带随机后缀），result16 字段值本身就是下载路径，直接拼接主机名即可：

curl -s -o master_16bit.wav -w "%{http_code}\n" \
  "http://127.0.0.1:8141/media/Matchering_16bit_target_BCvo.wav"
curl -s -o master_24bit.wav -w "%{http_code}\n" \
  "http://127.0.0.1:8141/media/Matchering_24bit_target_RTNw.wav"
file master_16bit.wav master_24bit.wav

实测回显：

200
200
master_16bit.wav: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, stereo 44100 Hz
master_24bit.wav: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 24 bit, stereo 44100 Hz

核对要点：file 识别出 16-bit 与 24-bit 两档、44100 Hz 立体声 WAV——这就是 Matchering 四维匹配后的母带成品；响度效果量化（本例目标轨 RMS -36.36 dB 对齐到参考轨 -27.30 dB 附近）见 B2 篇 4.6 节实测表。

6.4 全流程脚本化模板

把 6.1~6.3 串成一条可复用的流水线（自动化使用时轮询改 while 循环并设超时）：

#!/bin/bash
set -e
BASE=http://127.0.0.1:8141
TOKEN=$(curl -s -X POST $BASE/api/session/ -H "Content-Type: application/json" -d '{}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
curl -s -X POST "$BASE/api/upload/${TOKEN}/target/"    -F "file=@/opt/matchering/data/target.wav"    -o /dev/null
curl -s -X POST "$BASE/api/upload/${TOKEN}/reference/" -F "file=@/opt/matchering/data/reference.wav" -o /dev/null
while :; do
  CODE=$(curl -s "$BASE/api/session/${TOKEN}/" | python3 -c "import sys,json;print(json.load(sys.stdin)['code'])")
  [ "$CODE" = "2010" ] && break
  case "$CODE" in 4*) echo "FAILED: $CODE"; exit 1;; esac
  sleep 5
done
RESULT=$(curl -s "$BASE/api/session/${TOKEN}/" | python3 -c "import sys,json;print(json.load(sys.stdin)['result16'])")
curl -s -o master_16bit.wav "$BASE${RESULT}"
echo "done: master_16bit.wav"

要点：错误码首位是 4，脚本据 4* 直接判失败；成功分支下载 result16。批量任务并行提交多个会话即可——每个会话独立排队，worker 串行消费（默认单 worker，见 B2 篇内部构成）。

七、状态码与警告码手册

code 与 warnings 数组中的四位码由 Matchering 算法日志体系透传（官方 LOG_CODES.md 全量收录，Web 层原样转发），是排障的第一入口：

Info 码（会话进度，code 字段）：

Warning 码（warnings 数组，不阻断任务）：

Error 码（任务失败，code 字段为 4xxx）：

排障对照：上传阶段 400 = 重复上传或会话状态不对；轮询 404 = token 失效（60 分钟过期）；轮询出现 4002/4102 = 音轨超过 15 分钟默认上限（Web 版不可调，需 Python 库改 max_length，见 C1 篇）；4004/4104 = 声道数超限，先转双声道再传；3002 警告在本环境实测出现过一次（合成音周期包络触发的保守判断），对照真实素材听测判断是否采纳其建议。

八、常见问题

Q1：token 丢失了怎么办？ 无找回接口（token 只在创建响应中出现一次）。重新 POST /api/session/ 开新会话即可；旧会话 60 分钟后自动清理。

Q2：能并行提交多个会话吗？ 能。会话之间相互独立，并行 POST 即可；但内置处理 worker 默认单进程，任务实际串行执行，大批量请控制并发或扩容 worker（B2 篇内部构成）。

Q3：为什么 result16 是 /media/ 开头的相对路径？ Django FileField 序列化输出媒体相对路径，它本身就是相对 URL：把 http://<host>:<port> 拼在前面即得下载地址（6.3 实测演示）。文件名带随机后缀、媒体目录无目录浏览，不构成跨会话枚举面（token 32 位随机）。

Q4：HTTP API 能调采样率/限制器参数吗？ 不能。Web 版把算法参数写死为默认值（44100 Hz、pcm16/pcm24 双输出）。需要参数化母带请走 Python 库（C1 篇全量参数）。

Q5：上传后 404 了？ 会话已过期（60 分钟）或服务重启时数据卷未挂载导致 SQLite 重置。检查部署篇的持久化配置；生产自动化场景建议把轮询超时设为小于 60 分钟的窗口。

Q6：API 路径 404？ 检查是否带了 /api/ 前缀（第三节）。官方镜像 DEBUG=True 的 404 调试页会列出全部路由，可用来核对当前版本的路径表。

九、参考链接

1. API 路由源码：https://github.com/sergree/matchering-web/blob/master/mgw_back/urls.py
2. 视图与上传逻辑源码：https://github.com/sergree/matchering-web/blob/master/mgw_back/views.py
3. 异步任务源码：https://github.com/sergree/matchering-web/blob/master/mgw_back/tasks.py
4. 官方日志码文档（状态码全表出处）：https://github.com/sergree/matchering/blob/master/LOG_CODES.md
5. Matchering 主仓库：https://github.com/sergree/matchering
6. 站内部署篇：《Matchering 2.0 Docker Compose 部署指南》