SMSmart MasteringDeveloper Center · API v1

SERVER-TO-SERVER INTEGRATION

传入七牛链接,等待任务,
安全返回母带。

正式接口只允许产品后端调用。Bearer Key、业务任务 ID、用户 ID 三项缺一不可;浏览器、App 和公开页面不得保存生产 Key。

API v1服务 v1.13.2算法 v4.8.2已响来源保持七牛 HTTPSKey + Task/User 必填四种母带听感原音频复用M4A24-bit WAV幂等恢复

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

  1. POST 提交七牛签名链接与业务任务 ID
  2. GET 轮询任务直到 completed / failed
  3. GET 读取报告和 deliveryStatus
  4. 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 · false

cgroup 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."
}