ASMR 音频处理 API

API 服务会在一次同步请求中完成音频上传、声道异常分析、自动接受所有检测片段、降噪、人声增强和整轨处理，并直接返回处理后的 WAV。不会进入人工审核，也不会在 output/ 目录留下结果文件。

机器可读定义：openapi.json。服务启动后也可通过 GET /openapi.json 获取。

启动

Node.js 20+：

npm install
$env:API_TOKEN = "替换为随机长令牌"
npm run dev:api

Linux/macOS：

API_TOKEN="替换为随机长令牌" npm run dev:api

生产环境先执行 npm run build，再使用 npm run start:api。默认监听 127.0.0.1:3001。

建议使用随机令牌，例如：

node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

可在 .env.example 查看所有环境变量。服务不会自动加载 .env 文件，需要由进程管理器、容器或系统环境注入。

鉴权

除 /healthz 和 /openapi.json 外，所有接口都需要：

Authorization: Bearer <API_TOKEN>

令牌比较使用 SHA-256 摘要和定时比较，响应不会回显令牌。生产环境应在 HTTPS 或受信任的反向代理后运行。

处理接口

`POST /api/v1/process`

请求 Content-Type 必须是 multipart/form-data，字段如下：

字段	必需	类型	说明
`audio`	是	file	一个非空音频文件。支持 `.wav`、`.mp3`、`.m4a`、`.aac`、`.ogg`、`.flac`。
`options`	否	JSON string	处理参数对象；省略时使用工作台默认值。

options 参数：

参数	默认值	范围	说明
`sensitivity`	`76`	`40..95`	声道异常检测灵敏度。
`minimumDuration`	`1.2`	`0.2..4.8`	持续异常最短时长，单位秒；短促峰值检测独立运行。
`fallbackSensitivity`	`30`	`0..100`	单侧响度兜底灵敏度；`0` 关闭。
`noiseReduction`	`{ enabled: true, strength: 72 }`	strength `0..100`	第一阶段自适应降噪。
`voiceEnhancement`	`{ enabled: false, strength: 55 }`	strength `0..100`	第一阶段人声增强。
`secondStage`	见下方	见下方	整轨精细处理。

secondStage 的默认值为：

{
  "enabled": true,
  "mergeChannels": true,
  "noiseReduction": 64,
  "voiceRepair": 48,
  "voicePresence": 42,
  "loudnessCompensation": 42
}

示例请求：

curl --fail-with-body \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "audio=@input/test.wav;type=audio/wav" \
  -F 'options={"sensitivity":82,"minimumDuration":0.6,"noiseReduction":{"enabled":true,"strength":65},"secondStage":{"mergeChannels":true,"loudnessCompensation":35}};type=application/json' \
  http://127.0.0.1:3001/api/v1/process \
  -o processed.wav

成功响应为 200 OK，响应体是 WAV 二进制流：48 kHz、16-bit、双声道 PCM。响应头包括：

响应头	说明
`Content-Disposition`	固定为 `attachment; filename="processed.wav"`。
`X-Request-Id`	请求标识，可用于服务日志定位。
`X-Audio-Duration`	源音频时长，单位秒。
`X-Detected-Segments`	自动接受并修复的检测片段数。

处理完成后，上传文件和结果文件会被删除。API 不返回项目路径，也不复用网页端的本地文件接口。

公共接口

`GET /healthz`

无需鉴权，返回：

{ "status": "ok" }

该接口只表示 HTTP 服务存活，不会启动 FFmpeg。

`GET /openapi.json`

无需鉴权，返回 OpenAPI 3.0.3 文档，可导入 Swagger UI、Postman 或其他 API 客户端。

错误响应

错误统一返回 JSON，并带有 X-Request-Id：

{
  "error": {
    "code": "INVALID_OPTIONS",
    "message": "Invalid processing options.",
    "requestId": "...",
    "details": []
  }
}

常见状态码和错误码：

HTTP	code	触发条件
`400`	`INVALID_MULTIPART` / `MISSING_AUDIO` / `INVALID_OPTIONS`	multipart、文件字段或参数错误。
`401`	`UNAUTHORIZED`	缺少或错误的 Bearer Token。
`408`	`UPLOAD_TIMEOUT`	上传超时。
`413`	`UPLOAD_TOO_LARGE` / `OPTIONS_TOO_LARGE` / `AUDIO_TOO_LONG`	超过上传、参数或时长限制。
`415`	`UNSUPPORTED_MEDIA_TYPE` / `UNSUPPORTED_AUDIO_FORMAT`	请求媒体类型或文件扩展名不支持。
`422`	`INVALID_AUDIO`	文件无法由 FFmpeg 解码。
`503`	`SERVER_BUSY`	并发处理槽已满；响应带 `Retry-After: 5`。
`504`	`PROCESSING_TIMEOUT`	音频处理超时。

默认资源限制为：单文件 512 MiB、单音频 4 小时、同时处理 2 个任务。可通过环境变量调整，但服务仍会校验合理上限；详见 .env.example。

验证

npm run test:api
npm run build

测试覆盖鉴权顺序、参数校验、multipart 边界、上传和时长限制、并发、超时、断开连接后的 FFmpeg 终止、临时文件清理以及 WAV 输出格式。

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls