SERVER-TO-SERVER INTEGRATION

上传音频，等待任务，
安全返回母带。

适用于对话式 AI 和其他产品后端。API Key 只能保存在调用方服务端；浏览器和客户端不得直接持有密钥。

API v1异步任务24-bit WAV幂等恢复

01 · FAST PATH

对话产品最短接入流程

POST 上传附件并创建任务
GET 轮询任务直到 completed / failed
GET 读取报告和 deliveryStatus
GET 下载系统自动选择的最佳安全母带

ready

母带已完成，直接向用户返回最终 WAV。

qualityAdvisories

源缺陷或有限改善的透明提示，不阻断下载。

blocked

只有无法形成技术安全输出时才禁止返回。

02 · CREATE

创建任务

curl -X POST "$BASE_URL/v1/mastering/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: chat-message-attachment-sha256" \
  -F "audio=@song.wav;type=audio/wav" \
  -F "title=用户上传的歌曲"

同一消息和同一附件的所有重试必须复用同一个 Idempotency-Key。

03 · POLL

查询与恢复

curl "$BASE_URL/v1/mastering/jobs/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY"

# 创建请求超时且没有 JOB_ID 时：
curl "$BASE_URL/v1/mastering/jobs/by-idempotency/$KEY" \
  -H "Authorization: Bearer $API_KEY"

建议每 5–10 秒轮询。上传超时和任务处理等待必须使用两个不同的超时。

04 · PYTHON

可直接改造的服务端示例

import time
import requests

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Idempotency-Key": stable_key,
}
with open(audio_path, "rb") as audio:
    created = requests.post(
        f"{BASE_URL}/v1/mastering/jobs",
        headers=headers,
        files={"audio": ("song.wav", audio, "audio/wav")},
        timeout=900,
    ).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

核心接口

POST /v1/mastering/jobs: 上传并创建异步任务
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 · LIMITS

接入底线

支持 WAV、MP3、FLAC、OGG、M4A；推荐 WAV/FLAC。
8–900 秒、最高 48 kHz，只接受单声道或立体声。
40 MB 以上上传请求超时至少 600 秒，建议 900 秒。
API Key 不得写入网页、App 或聊天客户端。
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."
}

上传音频，等待任务，安全返回母带。