生产环境

Mixanalytic API 文档

https://mixanalytic.com 的官方 API 参考。使用此 API 上传音频,获取 AI 驱动的混音分析,支持选择模块以及精简/完整响应模式。

基础 URL: https://mixanalytic.com/api

认证

每次请求都需在 X-API-Key 标头中发送您的 API 密钥。

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 401 密钥缺失或无效
  • 403 免费方案密钥,无 API 访问权限
  • 429 超过速率限制

权限范围: write 用于 Mixanalytic 上传/分析。content 读取已隐藏敏感信息的内容研究数据。content_write 保存非公开内容草稿。内容权限范围仅限管理员使用。

端点

方法 路径 用途
GET/api/test-data检查连接/认证。
POST/api/upload上传并分析音频文件。
GET/api/analyze/<file_id>按文件 ID 重新分析(原始文件仍存在时)。
POST/api/mastering上传混音并启动一次母带处理(四个母带)。
GET/api/mastering/<token>母带处理的状态和结果。
GET/api/mastering/<token>/<variant>.wav下载一个 24 位 WAV 格式的母带。
GET/api/content/analysis-feed供内容智能体使用的研究数据流,仅限管理员访问,且已隐藏敏感信息。
POST/api/content/drafts供内容智能体使用的草稿保存/更新端点,仅限管理员访问。
GET/api/ai-stats?days=30AI 分析的使用统计。

上传请求

POST/api/upload

字段 类型 必填 说明
filemultipart file是允许的格式:mp3、wav、flac、m4a、aac、ogg。最大 95MB。
modulesstring/list否省略时默认为所有模块。
detail_levelstring否full(默认)或 summary。

无效的 detail_level 返回 400。超大文件返回 413。

模块选择

使用 modules 控制返回哪些分析模块,以及计算哪些模块。

支持的格式:

  • 逗号分隔字符串:modules=frequency_balance,clarity,mood
  • JSON 数组字符串:modules=["frequency_balance","clarity","mood"]
  • 重复键(查询/表单):modules=frequency_balance&modules=clarity
  • 所有模块:modules=all 或 modules=*
模块 描述
frequency_balance7 频段频率和平衡评分。
dynamic_range动态范围、峰值因数、PLR。
stereo_field宽度/相位/相关性指标。
clarity频谱清晰度和轮廓分明度指标。
harmonic_content调性与谐波复杂度。
transients起音、瞬态密度和低频冲击感数据。
3d_spatial高度/深度/宽度的一致性。
surround_compatibility单声道兼容性 + 相位评分。
headphone_optimization耳机播放优化评分。
speaker_optimization扬声器播放优化评分。
genre音乐流派分类与置信度。
voice人声存在感和声音特征。
instruments乐器检测与编曲信息。
mood包含能量/情绪效价的情绪特征。
keywords语义关键词和标签。
loudness测量LUFS、真峰值、削波和流媒体目标,让母带足够响亮,同时避免失真、编码峰值或平台带来的意外变化。
noise测量底噪、电源嗡声、嘶声和伪影,在母带处理让它们变得更响、更亮、更难掩盖之前,先清理录音。
format_quality检查有损编码、频谱截止和位深,避免在发行前误用质量受损的MP3、AAC或经过升采样的音源进行母带处理。
reference参考
visualizations生成的分析可视化素材的 URL。
ai_insightsLLM 生成的摘要和建议。

响应大小控制

使用 detail_level:

  • full(默认):完整载荷
  • summary:供前端/移动客户端使用的精简载荷

示例

1) 上传 + 完整分析

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3"

2) 上传 + 所选模块

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,dynamic_range,genre,mood,keywords"

3) 上传 + 所选模块 + 摘要载荷

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,stereo_field,clarity,ai_insights" \ -F "detail_level=summary"

4) 测试端点

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"

5) 客户端 JavaScript

const formData = new FormData(); formData.append('file', fileInput.files[0]); formData.append('modules', 'frequency_balance,dynamic_range,mood,ai_insights'); formData.append('detail_level', 'summary'); const res = await fetch('https://mixanalytic.com/api/upload', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY' }, body: formData }); const data = await res.json(); console.log(data.analysis, data.returned_modules);

标准响应元数据

分析成功的响应包含:

  • requested_modules
  • returned_modules
  • detail_level
  • available_modules

母带处理

上传完成的混音,一次处理即可获得四个 24 位 WAV 母带:dynamic, balanced, loud, chart。API 使用与母带工作室相同的引擎、价格和每月额度。

  • 母带处理仅限 Supporter:每个 UTC 月包含 20 次处理,之后每次处理使用令牌。
  • 一次处理会生成全部四个母带。包含次数用完后,每次处理消耗 85 个令牌。如果处理失败,所扣的令牌或包含的处理次数会退还。
  • 每个账户同一时间只能进行一次处理,与母带工作室共用此限制。
  • 处理完成 24 小时后母带会被删除(Supporter 账户为 30 天),除非该处理已在“我的母带”中保留。请在状态响应中的 expires_at 之前下载。
  • 启动处理需要 write 权限范围。查询状态和下载需要 read。

母带处理请求

POST/api/mastering

以 multipart/form-data 格式发送混音。只有 file 是必填项。

字段 类型 必填 说明
filemultipart file是允许的格式:mp3、wav、flac、aiff、m4a、aac、ogg。最大 95 MB,时长不超过 12 分钟。文件内容必须与扩展名一致。
tonenumber否以 1 kHz 为中心的音色倾斜,单位 dB。负值更温暖,正值更明亮。 范围 -2 至 2,步长 0.5。默认值 0。
widthnumber否120 Hz 以上的侧声道电平,单位 dB。负值更窄,正值更宽。低频保持居中。 范围 -3 至 2,步长 0.5。默认值 0。
punchnumber否粘合压缩量,以混音测量值的倍数表示。0 表示关闭粘合压缩。 范围 0 至 1.5,步长 0.25。默认值 1。
loudnessnumber否同时调整全部四个响度目标,单位 LU。如果再响会压扁鼓的力度,母带会提前停止,并在其改动说明中注明。 范围 -3 至 1.5,步长 0.5。默认值 0。
monostring否将 120 Hz 以下的低频变为单声道。 auto 仅在混音测得需要时才启用。 可选值:auto, on, off。默认值 auto。
deharshstring否只在 4–9 kHz 突出的瞬间将其压低。 auto 仅在混音测得需要时才启用。 可选值:auto, on, off。默认值 auto。
sourcestring否决定高频目标。ai 绝不改动 10 kHz 以上的空气频段,并把高频目标设得更低。recorded 追求更明亮的高频。auto 使用 song_id 报告中的 AI 音乐判定,否则自行检测上传的文件。 可选值:auto, ai, recorded。默认值 auto。
stylestring否决定低频的分量,以及推荐哪个母带。auto 使用 song_id 报告中的音乐流派。不提供 song_id 时不会应用任何流派:低频保持中性,推荐依据响度范围,因此如需选择流派,请发送一个风格。 可选值:auto, pop, rock, hiphop, electronic, rnb, metal, acoustic。默认值 auto。
song_idinteger否您已分析过的歌曲 ID。将复用其已存储的报告,而不再测量上传的文件。请上传同一个混音。
Idempotency-Keyheader否1–64 个字符:字母、数字、_ 和 -。

超出范围的数值会被限制在范围内,并按步长取整。不是数字的值或未知的选项会返回 400 和 invalid_settings。

发送 Idempotency-Key 标头即可安全重试,并为每个混音使用新的键。如果您的账户在处理仍存在时重复使用某个键,不会再次扣费,也不会重新启动处理:您会收到 200,内容为原始响应体加上 "replayed": true。如果重复请求在第一个请求仍在启动时到达,您会收到 429 busy。收到 503 failed 后,请使用新的键重试。

启动响应

新建的处理返回 202:

{ "token": "3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "status": "pending", "status_url": "/api/mastering/3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "billed": "tokens", "charged": 85, "balance": 415, "expires_in_hours": 720 }

使用 Supporter 额度的处理包含 "billed": "included" 和 "charged": 0。Supporter 还会收到一个 included 对象,其中包含 used, cap, reset_date。

母带处理状态与下载

GET/api/mastering/<token>

每 3–5 秒轮询一次(不超过密钥的速率限制),直到状态变为 done 或 error。

  • pending:正在制作母带。
  • settling:处理失败,正在退还所扣的令牌或包含的处理次数。请继续轮询。
  • done:四个母带已就绪。
  • error:处理失败,所扣费用已退还。error 字段说明原因:too_long, too_short, too_quiet, failed。

完成响应包含 recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename。masters 中的每一项都包含 key, url, target_lufs, ceiling, metrics, changes, peaks。

完成和错误响应还包含 access:处理后您的余额和包含的处理次数。

未知、已过期或属于其他账户的 token 会返回 404 和 {"status": "expired"}。

下载

GET/api/mastering/<token>/<variant>.wav

以 24 位 WAV 附件形式返回母带,文件名取自您上传的文件,例如 My Mix - balanced.wav。variant 为 dynamic, balanced, loud, chart 之一。

未知的 variant、属于其他账户的 token,或已过期、尚未完成的处理,都会返回 404。

所有母带处理响应都带有 Cache-Control: private, no-store。

母带处理错误

错误会返回 {"error": "invalid_file", "message": "…"}。

状态 错误 含义
400invalid_file缺少文件、格式不受支持,或内容与扩展名不符。
400invalid_settings某项设置不是数字,或不在可选值之内。
400invalid_idempotency_keyIdempotency-Key 标头不是 1–64 个字母、数字、_ 或 -。
402insufficient_credits令牌不足。响应体包含 cost 和 balance。
403Forbidden免费账户的密钥,或缺少此端点所需权限范围的密钥。续订付款失败的 Supporter 在付款完成前会按免费方案处理,因此在此期间母带处理只能在母带工作室中使用。不会收取任何费用。
403supporter_only目前母带处理仅向 Supporter 账号开放。不会收取任何费用。
413File too large文件大于 95 MB,因此请求在到达端点之前就会被拒绝,有时不带 JSON 响应体。仅略微超过上限的文件则会收到 invalid_file。
429busy此账户已有一次处理正在进行或正在启动(来自 API 或母带工作室)。响应体包含其 token,在该处理仍在启动时为 null。
429Rate Limit Exceeded已达到密钥的每分钟、每小时或每天限制。消息会说明是哪一项。
503failed无法启动处理。所扣费用会退还。

母带处理示例

1) 启动处理

curl -X POST "https://mixanalytic.com/api/mastering" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_MIX" \ -F "file=@/path/to/mix.wav" \ -F "style=electronic" \ -F "loudness=0.5"

2) 轮询直到完成

curl "https://mixanalytic.com/api/mastering/TOKEN" \ -H "X-API-Key: YOUR_API_KEY"

3) 下载母带

curl -o "mix - balanced.wav" "https://mixanalytic.com/api/mastering/TOKEN/balanced.wav" \ -H "X-API-Key: YOUR_API_KEY"

错误码

状态 含义 常见原因
400错误请求module/detail_level 无效、缺少文件字段或文件为空。
401未经认证API 密钥缺失、无效或已过期。
403禁止访问账户等级不允许 API 访问。
404未找到/api/analyze/<file_id> 文件已不可用(因隐私保护而删除)。
413载荷过大文件超过 95MB。
429超过速率限制每分钟/每小时/每天的请求过多。
500服务器错误分析/运行时失败。

前端说明

  • 网页/移动客户端建议使用 detail_level=summary。
  • 仅请求首次渲染所需的模块,以减少延迟和载荷大小。
  • 对 429 和 500 采用重试与退避机制。
  • 不要在公开的打包文件中暴露长期有效的生产环境密钥。