SOURCE PRESERVATION · MEASURED OUTCOMES
一首原曲,多种听感 · v1.13.2
普通调用方仍只需提交一次七牛链接、轮询、下载一个最终 24-bit WAV,不需要理解或选择 LUFS。现有接口地址、生产 Key、Task ID / User ID 和用户任务上限保持不变。v1.13.2 / v4.8.2 对已响来源优先保持响度、厚度和动态,不据峰值预先整曲降档;普通较轻来源继续智能增响。接近目标的识别与透明路线共用 0.5 LU 边界,最终达标仍为 ±0.3 LU。新增 sourcePreservationReport;utilityReport 区分 source-preserved、source-preservation-limited、level-maintained 和手动 requested-normalization,不把保持或降低响度冒充增响。fallbackApplied 仅表示实际候选失败后的恢复,预选路线另用 plannedRouteSelection 表示。限额后的 EQ 仍按实际恢复强度缩小剂量,完整质量检查及跨模式复用保留。
可选听感:表单 mastering_style / JSON masteringStyle,取值 auto、warm、clear、punch。可选响度:表单 target_lufs / JSON targetLufs,省略或 auto 为智能选择;高级调用方可指定 -14、-11、-10、-9、-8。手动高响度不保证任意来源无损可达,真实风险保护不关闭。
同键不能改变听感或响度意图(auto 与显式 -11 也不同),首次查询及并发创建后的复查均返回 409 idempotency_payload_mismatch;非法值 422。网络重试使用原键,新偏好使用新键。
loudnessReport 记录选择模式、最初目标、实际值、0.3 LU 容差、达成状态与真正响度限制;局部纹理提示在 qualityReport.checks/evidence.localTexture 和 deliveryGate.qualityAdvisories,不是响度失败。context.loudnessPlan 持久化规划供恢复,不静默换目标。
masteringReport.basicActions 与 enhancementReport.retainedInFinal/actions 分别记录基础完成和保留修复。enhancementAttempts 每项是实际阶段快照;reportConsistency 核对保留动作、阶段指标和最终响度。技术分、数值改善和一致性通过均不是主观音质提升证明。after.clipAssessment 区分源输入迹象和本次限幅相符的成品迹象。
performance.stagesMs/renderedCandidateCount 记录实际耗时与候选数。历史完成报告保持原样。
REUSE ORIGINAL · CPU ECI
换模式不用重传
首个任务 completed 且原输入仍保留时,引用它创建新模式;始终复制原输入,不会把上一份母带当作输入。先检查 GET /v1/capabilities 的 retainedSourceVariants.enabled。CPU ECI 生产后端支持此流程,仍校验任务归属与每用户 5 个活动任务的上限;操作台使用既有登录会话,对外调用仍须传 Key、User ID 和新的业务 Task ID。
curl -X POST "$BASE_URL/v1/mastering/jobs/$JOB_ID/variants" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Mastering-Task-ID: $NEW_TASK_ID" \
-H "X-Mastering-User-ID: $USER_ID" \
-H "Content-Type: application/json" \
-d '{"masteringStyle":"warm","targetLufs":"auto"}'
202 返回 job、sourceReused:true;reused:true 表示直接找回符合幂等约束的已有任务。操作台可按原曲、参数和处理修订找回相同模式;服务端调用用新的业务 Task ID 表示新意图,同一次调用重试保持 Task ID、User ID、模式及响度意图不变,改变意图返回 409。省略 targetLufs 继承源任务的响度意图,不继承旧规划或母带音频。
源文件保留在 ECS,原输入未过期时,ECI 释放后仍能换模式而不用重传。分析/兼容的风格前修复缓存只在当前 ECI 会话的私有磁盘上复用;容器释放后缓存随之删除,下次新容器会重新分析,不承诺跨容器缓存命中。过期、损坏、环境/算法修订或不兼容参数变化也会重新计算。所有模式各自完整检测最终成品。报告 reuseReport 和 processingStages 的 reused 明确区分复用与实际执行。原输入过期返回 410;API 重启后的同键重试可恢复未完成的源复制,不重复启动 DSP。已有失败任务不盲目重跑。
01 · FAST PATH
对话产品最短接入流程
生产接口https://mastertape.newpmusic.com/v1/mastering/jobs/from-url
- POST 提交七牛签名链接与业务任务 ID
- GET 轮询任务直到 completed / failed
- GET 读取报告和 deliveryStatus
- GET 下载系统自动选择的最佳安全母带
ready母带已完成,直接向用户返回最终 WAV。
qualityAdvisories源缺陷或有限改善的透明提示,不阻断下载。
blocked只有无法形成技术安全输出时才禁止返回。
OPTIONAL SONIC PREFERENCE
可选母带听感
七牛 URL 接口使用 JSON 字段 masteringStyle;操作台 multipart 接口使用 mastering_style。取值为 auto(默认智能自动)、warm(温暖饱满)、clear(清晰通透)或 punch(有力冲击)。不传时保持自动模式,每次只交付一个通过质量保护的最终母带。
同一用户、同一 Task ID 的重试必须保持相同模式;改变模式时必须使用新的 Task ID。若同一 Task ID 传入不同模式,服务返回 409 idempotency_payload_mismatch。报告中的 styleReport 会如实标明模式已应用、受限或因风险被撤销。
OPERATOR CONSOLE
网页直传兼容接口
受保护的操作台仍可调用 POST /v1/mastering/jobs 上传本地文件,并以稳定的 Idempotency-Key 防止超时重试时重复创建任务。对外产品接入应优先使用上方的生产 URL 接口及 Task ID / User ID 合同。
02 · CREATE
用七牛链接创建任务
curl -X POST "$BASE_URL/v1/mastering/jobs/from-url" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Mastering-Task-ID: order-song-20260921-001" \
-H "X-Mastering-User-ID: product-user-123" \
-H "Content-Type: application/json" \
-d '{
"audioUrl": "https://你的七牛域名/song.m4a?e=...&token=...",
"title": "用户歌曲",
"artist": "歌手名",
"masteringStyle": "warm",
"targetLufs": "auto"
}'
同一业务任务的所有重试必须复用同一个 Task ID。服务只保存链接哈希和域名,不保存七牛签名参数。
03 · POLL
查询与恢复
curl "$BASE_URL/v1/mastering/jobs/$JOB_ID" \
-H "Authorization: Bearer $API_KEY"
# 创建请求超时且没有 JOB_ID 时:
curl "$BASE_URL/v1/mastering/jobs/by-task-id/$TASK_ID" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Mastering-User-ID: $USER_ID"
建议每 5–10 秒轮询。七牛下载和任务处理等待必须使用两个不同的超时。
04 · PYTHON
可直接改造的服务端示例
import time
import requests
headers = {
"Authorization": f"Bearer {API_KEY}",
"X-Mastering-Task-ID": business_task_id,
"X-Mastering-User-ID": user_id,
}
created = requests.post(
f"{BASE_URL}/v1/mastering/jobs/from-url",
headers=headers,
json={"audioUrl": qiniu_signed_url, "title": title, "artist": artist, "masteringStyle": "auto", "targetLufs": "auto"},
timeout=180,
).json()
job_id = created["job"]["jobId"]
while True:
job = requests.get(
f"{BASE_URL}/v1/mastering/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
).json()["job"]
if job["status"] in {"completed", "failed"}:
break
time.sleep(5)
if job["status"] == "completed" and job.get("deliveryStatus") != "blocked":
mastered = requests.get(
f"{BASE_URL}/v1/mastering/jobs/{job_id}/output",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=900,
).content
05 · CONTRACT
核心接口
- GET /v1/capabilities
- 查询格式、处理模式与原输入复用能力
- POST /v1/mastering/jobs/from-url
- Key + Task ID 校验后,从七牛 HTTPS 链接创建任务
- POST /v1/mastering/jobs/{jobId}/variants
- 复用同一用户保留的原输入创建其他模式,不叠加成品
- GET /v1/mastering/jobs/by-task-id/{taskId}
- 创建超时后按业务任务 ID 找回
- GET /v1/mastering/jobs/{jobId}
- 状态、进度、资源准入和耗时
- GET /v1/mastering/jobs/{jobId}/report
- 完整母带、资源与质量报告
- GET /v1/mastering/jobs/{jobId}/output
- 下载允许交付的 WAV
- POST /v1/mastering/jobs/{jobId}/archive-confirmation
- 按输出 SHA256 确认外部归档
- DELETE /v1/mastering/jobs/{jobId}
- 用户主动删除任务和文件
06 · SECURITY & LIMITS
接入底线
- Key、Task ID、User ID 缺少任一项都不会创建任务。
- Key 只保存在调用方服务端,不能写入网页、App、日志或公开文档。
- 七牛地址必须是白名单域名的最终 HTTPS 链接;不跟随重定向,不允许内网地址。
- 支持 WAV、MP3、FLAC、OGG、M4A;8–900 秒、最高 48 kHz、单声道或立体声。
- 同一用户最多 5 个活动任务;同一个 Task ID 只创建一次。
- blocked 永不返回音频。
07 · FAILURE CONTRACT
失败必须按事实处理
失败响应固定返回 code、category、retryable、message 和 userAction。调用方只依据 retryable 决定是否自动重试,不根据错误文字猜测。
input · false源文件不可解码、超 15 分钟、超 48 kHz、过短或静音;提示用户重新导出,不自动重试。
resource · falsecgroup OOM、SIGKILL、RSS 超预算或未知服务退出;禁止盲目重跑,先检查资源证据。
quality advisory母带已完成;残留问题保留在报告中,但调用方照常返回最终音频。
{
"code": "audio_decode_failed",
"category": "input",
"retryable": false,
"message": "The audio file could not be decoded.",
"userAction": "Export a valid audio file and upload it again."
}