Mixanalytic API 文档
https://mixanalytic.com 的官方 API 参考。使用此 API 上传音频,获取 AI 驱动的混音分析,支持选择模块以及精简/完整响应模式。
基础 URL: https://mixanalytic.com/api
认证
每次请求都需在 X-API-Key 标头中发送您的 API 密钥。
- 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=30 | AI 分析的使用统计。 |
上传请求
POST/api/upload
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | multipart file | 是 | 允许的格式:mp3、wav、flac、m4a、aac、ogg。最大 95MB。 |
| modules | string/list | 否 | 省略时默认为所有模块。 |
| detail_level | string | 否 | 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_balance | 7 频段频率和平衡评分。 |
| 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_insights | LLM 生成的摘要和建议。 |
响应大小控制
使用 detail_level:
- full(默认):完整载荷
- summary:供前端/移动客户端使用的精简载荷
示例
1) 上传 + 完整分析
2) 上传 + 所选模块
3) 上传 + 所选模块 + 摘要载荷
4) 测试端点
5) 客户端 JavaScript
标准响应元数据
分析成功的响应包含:
- 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 是必填项。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | multipart file | 是 | 允许的格式:mp3、wav、flac、aiff、m4a、aac、ogg。最大 95 MB,时长不超过 12 分钟。文件内容必须与扩展名一致。 |
| tone | number | 否 | 以 1 kHz 为中心的音色倾斜,单位 dB。负值更温暖,正值更明亮。 范围 -2 至 2,步长 0.5。默认值 0。 |
| width | number | 否 | 120 Hz 以上的侧声道电平,单位 dB。负值更窄,正值更宽。低频保持居中。 范围 -3 至 2,步长 0.5。默认值 0。 |
| punch | number | 否 | 粘合压缩量,以混音测量值的倍数表示。0 表示关闭粘合压缩。 范围 0 至 1.5,步长 0.25。默认值 1。 |
| loudness | number | 否 | 同时调整全部四个响度目标,单位 LU。如果再响会压扁鼓的力度,母带会提前停止,并在其改动说明中注明。 范围 -3 至 1.5,步长 0.5。默认值 0。 |
| mono | string | 否 | 将 120 Hz 以下的低频变为单声道。 auto 仅在混音测得需要时才启用。 可选值:auto, on, off。默认值 auto。 |
| deharsh | string | 否 | 只在 4–9 kHz 突出的瞬间将其压低。 auto 仅在混音测得需要时才启用。 可选值:auto, on, off。默认值 auto。 |
| source | string | 否 | 决定高频目标。ai 绝不改动 10 kHz 以上的空气频段,并把高频目标设得更低。recorded 追求更明亮的高频。auto 使用 song_id 报告中的 AI 音乐判定,否则自行检测上传的文件。 可选值:auto, ai, recorded。默认值 auto。 |
| style | string | 否 | 决定低频的分量,以及推荐哪个母带。auto 使用 song_id 报告中的音乐流派。不提供 song_id 时不会应用任何流派:低频保持中性,推荐依据响度范围,因此如需选择流派,请发送一个风格。 可选值:auto, pop, rock, hiphop, electronic, rnb, metal, acoustic。默认值 auto。 |
| song_id | integer | 否 | 您已分析过的歌曲 ID。将复用其已存储的报告,而不再测量上传的文件。请上传同一个混音。 |
| Idempotency-Key | header | 否 | 1–64 个字符:字母、数字、_ 和 -。 |
超出范围的数值会被限制在范围内,并按步长取整。不是数字的值或未知的选项会返回 400 和 invalid_settings。
发送 Idempotency-Key 标头即可安全重试,并为每个混音使用新的键。如果您的账户在处理仍存在时重复使用某个键,不会再次扣费,也不会重新启动处理:您会收到 200,内容为原始响应体加上 "replayed": true。如果重复请求在第一个请求仍在启动时到达,您会收到 429 busy。收到 503 failed 后,请使用新的键重试。
启动响应
新建的处理返回 202:
使用 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": "…"}。
| 状态 | 错误 | 含义 |
|---|---|---|
| 400 | invalid_file | 缺少文件、格式不受支持,或内容与扩展名不符。 |
| 400 | invalid_settings | 某项设置不是数字,或不在可选值之内。 |
| 400 | invalid_idempotency_key | Idempotency-Key 标头不是 1–64 个字母、数字、_ 或 -。 |
| 402 | insufficient_credits | 令牌不足。响应体包含 cost 和 balance。 |
| 403 | Forbidden | 免费账户的密钥,或缺少此端点所需权限范围的密钥。续订付款失败的 Supporter 在付款完成前会按免费方案处理,因此在此期间母带处理只能在母带工作室中使用。不会收取任何费用。 |
| 403 | supporter_only | 目前母带处理仅向 Supporter 账号开放。不会收取任何费用。 |
| 413 | File too large | 文件大于 95 MB,因此请求在到达端点之前就会被拒绝,有时不带 JSON 响应体。仅略微超过上限的文件则会收到 invalid_file。 |
| 429 | busy | 此账户已有一次处理正在进行或正在启动(来自 API 或母带工作室)。响应体包含其 token,在该处理仍在启动时为 null。 |
| 429 | Rate Limit Exceeded | 已达到密钥的每分钟、每小时或每天限制。消息会说明是哪一项。 |
| 503 | failed | 无法启动处理。所扣费用会退还。 |
母带处理示例
1) 启动处理
2) 轮询直到完成
3) 下载母带
错误码
| 状态 | 含义 | 常见原因 |
|---|---|---|
| 400 | 错误请求 | module/detail_level 无效、缺少文件字段或文件为空。 |
| 401 | 未经认证 | API 密钥缺失、无效或已过期。 |
| 403 | 禁止访问 | 账户等级不允许 API 访问。 |
| 404 | 未找到 | /api/analyze/<file_id> 文件已不可用(因隐私保护而删除)。 |
| 413 | 载荷过大 | 文件超过 95MB。 |
| 429 | 超过速率限制 | 每分钟/每小时/每天的请求过多。 |
| 500 | 服务器错误 | 分析/运行时失败。 |
前端说明
- 网页/移动客户端建议使用 detail_level=summary。
- 仅请求首次渲染所需的模块,以减少延迟和载荷大小。
- 对 429 和 500 采用重试与退避机制。
- 不要在公开的打包文件中暴露长期有效的生产环境密钥。