03 接口规格

前缀 /api/snd/v1。匿名可用的接口通过 X-Anon-Id 识别；其余接口需要登录。

1. 上传

方法	路径	说明
POST	`/uploads`	`{"filename","size","content_type","role":"vocal\|backing\|original\|reference\|cover_image"}` → 分片上传地址（16MB 一片）
POST	`/uploads/{id}/complete`	合并并运行 probe → 时长、格式、响度

限制：唱歌模式音频 ≤ 10 分钟、≤ 200MB；说话模式 ≤ 3 小时（音频）/ 2 小时（视频）。

2. 作品

方法	路径	说明
POST	`/works`	创建作品（见下）→ 自动开始处理；额度不足返回 `QUOTA_EXCEEDED` 和升级链接
GET	`/works/{id}`	状态、进度（按步骤）、结果（前后对比试听链接、视频预览、指标）
PATCH	`/works/{id}`	修改参数（曲风、强度、歌词、视频模板）→ 从受影响的步骤开始重新渲染，不重复扣额度
POST	`/works/{id}/export`	`{"formats":["mp3","wav","video","stems","vocal_safe"]}` → 按权益和伴奏来源校验；原曲伴奏作品请求 `mp3/wav/video/stems` 返回 `EXPORT_NOT_ALLOWED_FOR_SOURCE`，只允许 `vocal_safe`；返回下载链接
POST	`/works/{id}/lyrics`	粘贴歌词 → 重新对齐
DELETE	`/works/{id}`	删除作品及文件

// POST /works（唱歌模式）
{
  "mode": "sing",
  "sources": {"vocal": "upl_...", "original": "upl_..."},       // 或 "backing": "upl_..."
  "params": {
    "genre": "pop", "tune_strength": 0.7, "keep_vibrato": true,
    "reference": "original", "timing": false,
    "master_reference": null, "video_template": "cover_blur",
    "title": "...", "artist_display": "..."
  },
  "consent": {"text_version": "2026-09-v1", "own_voice": true, "backing_rights": "original"}
}

own_voice：确认人声是用户本人的声音（必填）
backing_rights：上传伴奏时必填："licensed"（确认有权使用，勾选存证）；上传原曲时为 "original"，系统据此把作品标为 original_separated，只能导出发布安全版人声

3. 工具箱

方法	路径	说明
POST	`/tools/pitch-score`	`{"vocal":"upl_...","original":"upl_..."}` 或 `{"vocal":"upl_...","key":"C major"}` → 任务 ID
POST	`/tools/separate`	`{"source":"upl_...","stems":2}`
POST	`/tools/transpose`	`{"source":"upl_...","semitones":-2,"tempo":1.0}`
POST	`/tools/key-bpm`	`{"source":"upl_..."}`
GET	`/tools/runs/{id}`	结果 + 分享图链接
POST	`/tools/runs/{id}/to-work`	用同样的文件直接创建修音作品（登录后）

4. 说话模式

与唱歌模式共用 /works，mode="talk"；参数见 05 文档：

{"mode":"talk","sources":{"main":"upl_..."},"params":{"edit_level":"standard","loudness":"podcast",
 "subtitles":{"enabled":true,"language":"en","translate_to":null,"burn_in":true,"style":"clean_white"},
 "keep_words":["like"],"speakers":{"S1":"Amy"}}}

用户编辑器接口：

方法	路径	说明
GET	`/works/{id}/workspace`	转写、剪辑表、波形、代理音频
PUT	`/works/{id}/edl`	保存剪辑表新版本（带 `base_version`，冲突返回 409）→ 自动重新渲染

5. 订阅

由底座 core.billing 处理；本产品只读取 core.entitlements。前端通过 GET /me/entitlements 显示额度和权益。

6. 后台 `/api/snd/admin/v1`

路径	说明
`/presets`	曲风预设的版本管理（改动后必须先跑回归）
`/regression`	回归测试结果
`/stats/daily`	作品数、成功率、耗时、免费转付费、水印回流、工具使用、成本
`/exceptions`	异常（通常只有反复失败的作品）

本文档由 03_音频_开发spec/03_接口规格.md 生成 · 2026-09-27 · 打印可用 Ctrl/Cmd+P 另存为 PDF