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 | ミックスのアップロードとマスタリング1回の開始(4つのマスター)。 |
| GET | /api/mastering/<token> | マスタリング実行のステータスと結果。 |
| GET | /api/mastering/<token>/<variant>.wav | マスター1つを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
マスタリング
完成したミックスをアップロードすると、1回の実行で24ビットWAVのマスターを4つ受け取れます:dynamic, balanced, loud, chart。APIはマスタリングスタジオと同じエンジン、料金、月間のプラン内回数を使います。
- マスタリングはSupporter限定です。UTCの各月に20回が含まれ、その後は1回ごとにトークンを使います。
- 1回の実行で4つのマスターすべてを作成します。プラン内の回数を使い切った後は、1回85トークンかかります。実行に失敗した場合は、そのトークンまたはプラン内の回数が戻ります。
- 各アカウントで同時に実行できるのは1回だけです。この制限はマスタリングスタジオと共通です。
- 「自分のマスター」で保持した実行を除き、マスターは実行完了から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 | いいえ | 4つのラウドネスターゲットをまとめて動かします(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ヘッダーを送信し、ミックスごとに新しいキーを使ってください。実行がまだ存在する間に同じアカウントから同じキーを再送しても、課金も実行の開始も繰り返されません。元のレスポンス本文に"replayed": trueを加えたものが200で返ります。最初のリクエストがまだ開始中の場合、再送には429 busyが返ります。503 failedが返ったら、新しいキーで再試行してください。
開始時のレスポンス
新しい実行は202を返します:
Supporterのプラン内回数で実行した場合は、"billed": "included"と"charged": 0が含まれます。Supporterには、used, cap, reset_dateを含むincludedオブジェクトも返されます。
マスタリングのステータスとダウンロード
GET/api/mastering/<token>
ステータスがdoneまたはerrorになるまで、キーのレート制限の範囲内で3〜5秒ごとにポーリングしてください。
- pending:マスターを作成中です。
- settling:実行に失敗し、トークンまたはプラン内の回数を返却中です。ポーリングを続けてください。
- done:4つのマスターが完成しました。
- 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も含まれます。
URLのトークンが不明・期限切れ、または他のアカウントのものである場合は、404と{"status": "expired"}を返します。
ダウンロード
GET/api/mastering/<token>/<variant>.wav
マスターを24ビットWAVの添付ファイルとして返します。ファイル名はアップロードしたファイル名をもとにします(例:My Mix - balanced.wav)。variantはdynamic, balanced, loud, chartのいずれかです。
不明なバリアント、他のアカウントのトークン、期限切れまたは未完了の実行には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 | キーの1分、1時間、または1日あたりの上限に達しました。どれに達したかはメッセージに示されます。 |
| 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には、再試行とバックオフで対応してください。
- 有効期間の長い本番環境のキーを、公開バンドルに含めないでください。