生产环境

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 用于 Mix Analyzer 上传/分析。content 读取已隐藏敏感信息的内容研究数据。content_write 保存非公开内容草稿。内容权限范围仅限管理员使用。

端点

方法	路径	用途
GET	/api/test-data	检查连接/认证。
POST	/api/upload	上传并分析音频文件。
GET	/api/analyze/<file_id>	按文件 ID 重新分析（原始文件仍存在时）。
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。最大 100MB。
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) 上传 + 完整分析

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

错误码

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

前端说明

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