音楽配信APIの連携方法

音楽配信APIを連携するとは、カタログを取り込み、メタデータを検証し、リリースをストリーミングストアへ配信し、ロイヤリティやアナリティクスを読み込むという一連のパイプラインに、自社のシステムをつなぎ込むことを意味します。Webフォームの代わりにHTTP呼び出しでレーベルやリリース、トラックを作成し、各リリースをバリデーションにかけ、DSPへの配信を実行したうえで、再生数や明細を取得して自社の記録と突合します。呼び出し自体は難しくありません。本当に手間がかかるのは、楽曲のメタデータを正しくモデリングすることと、非同期の処理を扱うこと、そしていつか配信がリジェクトされて戻ってくる日に備えて作り込んでおくことです。

このガイドでは、実際に構築する順番、すなわち認証、リリースの作成と配信、バリデーションとエラーへの対応、そして収益や数値の読み込みという流れで連携を解説します。以下に示すエンドポイントの例はLabelGridの公開APIを使っていますが、この構成はほとんどの配信プラットフォームに当てはまります。正確なフィールドやパラメータ、エラーコードは公開APIドキュメントにまとまっているため、本記事はあくまで全体像であり、フィールド単位のリファレンスではありません。

音楽配信APIは実際に何をしているのか？

配信APIは、リリースのライフサイクルをエンドポイントとして公開しています。工程は4段階あり、どの連携でも同じ順番で進みます。まず、カタログの取り込みです。カタログを構成するレーベルやリリース、トラックを作成し、メタデータと音源を紐づけます。次に、バリデーションです。リリースをどこにも送る前に、ストアのルールに沿っているかを確認します。3番目が配信で、バリデーション済みのリリースをストリーミングサービスやストアへ届けます。最後に読み込みです。楽曲が公開された後の状況を自社システムで把握できるよう、アナリティクスとロイヤリティ明細を取得します。

配信の裏側にあるのがDDEXです。ストアがリリースを取り込めるように、リリースとその音源を記述するための業界標準規格です。開発者がDDEXに直接触れることはほとんどありません。プラットフォームが、APIを通じて作成したリリースからDDEXを生成し、各DSPとやり取りしてくれます。これこそが、ストアを1つずつ個別に連携するのではなく配信APIを使う意味です。1つのリリースモデルを入力すれば、DDEX準拠の形式で主要な音楽配信サービスすべてに配信されます。LabelGridの配信APIは、取り込みから明細の取得までの4段階すべてを、1つの認証済みインターフェースの中でカバーしています。

実際によく使うことになるエンドポイントは、これらの工程にそのまま対応しています。

GET   /api/public/me                        # トークンを検証し、自分のアカウント情報を確認
GET   /api/public/releases                  # カタログの一覧を取得
POST  /api/public/releases                  # リリースを作成（取り込み）
POST  /api/public/releases/{id}/validate    # リリースをストアのルールに照らしてチェック
POST  /api/public/releases/{id}/distribute  # DSPへ配信
GET   /api/public/analytics                 # 再生数やリスナーデータを取得
GET   /api/public/statements                # ロイヤリティ明細を取得

このリストを連携全体の骨格だと考えてください。それ以外の要素、つまりメタデータやリトライ、突合処理は、すべてこの7つの呼び出しにぶら下がっているものです。

認証はどのように行うのか？

認証は、すべてのリクエストにBearerトークンを付与する方式です。アカウントを登録してAPI認証情報を発行し、Authorizationヘッダーに設定して送信します。事前にデモの予約を取ったり、営業の審査を通したりする必要はありません。登録はセルフサービスで完結し、ドキュメントも公開されているため、APIプランが有効になればその日の午後には認証付きの呼び出しを始められます。トークンはアカウント設定画面から発行でき、任意で既知のIPアドレスに制限することもできます。最初に呼び出すべきはGET /api/public/meで、トークンが有効かどうかと、どのアカウントに紐づいているかを確認できます。

curl https://api.labelgrid.com/api/public/me \
  -H "Authorization: Bearer <token>"

他の実装に着手する前に、まずこの呼び出しがきれいなレスポンスを返す状態にしておきましょう。meの呼び出しが正しく動けば、認証情報、ベースURL、HTTPクライアントがすべて正しいことの証明になり、以降に何か失敗しても原因がリリース側にあることがわかります。トークンはシークレットとして扱い、ソースコード管理やクライアントのビルド成果物には絶対に含めず、パスワードと同じように扱ってください。漏えいした場合はローテーションし、サンドボックスと本番で別々の認証情報を使い分けることで、テスト実行が本番のカタログに触れることのないようにします。トークンの種類や有効期限の挙動、追加で必要なヘッダーの詳細はAPIリファレンスに記載されているため、推測せずに一度目を通し、小さなクライアントにまとめておきましょう。

リリースの作成と配信はどう行うのか？

リリースを何もない状態から公開まで持っていくのに必要なのは、3つの呼び出しです。作成し、バリデーションを行い、配信します。

POST  /api/public/releases                  # 1. リリースとそのメタデータを作成
POST  /api/public/releases/{id}/validate    # 2. ストアのルールに照らしてチェック
POST  /api/public/releases/{id}/distribute  # 3. DSPへ配信

作成ステップに、エンジニアリングの大半の労力がかかります。リリースには、タイトル、アーティストやクレジット対象者、リリース日、レーベル、アートワーク、そして各トラック固有のタイトルやクレジット、音源など、多くのメタデータが含まれます。正確なフィールド、フォーマット、必須項目はすべてドキュメントに記載されているので、おおよそで済ませず、その通りに厳密にモデリングしてください。メタデータの不備は、後になってリリースが失敗する最も多い原因なので、送信する前に自分の側で入力を検証しましょう。アートワークのサイズを確認し、すべてのトラックに音源とISRCが揃っているかを確かめ、アーティスト名は自社側で正規化しておいてください。問題を自分のコードで見つけるほうが、ストアでのリジェクトで見つけるよりもはるかにコストが低いためです。

作成処理はべき等にしておきましょう。ネットワーク呼び出しは途中で失敗することがあり、リトライによって同じリリースの複製が作られてしまうのは避けたいところです。冪等性キーを使うか、新規作成の前に自社側の参照情報で既存リリースの有無を確認することで、同じリクエストが繰り返されても複製ではなく同一のリリースが返るようにします。これは特に、数千件規模のカタログを一括インポートする際に重要です。不安定な接続では、どこかで必ずリトライが発生します。

配信は非同期です。distributeを呼び出した時点では、即座に結果が返るのではなく、ジョブがキューに入るだけです。APIはリクエストを受け付け、その後プラットフォームがバックグラウンドでDDEXをパッケージングして各ストアへ送信するため、時間がかかることがあります。最初からそれを前提に設計してください。distributeの呼び出しを送信し、依頼したことを記録したうえで、レスポンスを待って処理をブロックするのではなく、配信ステータスをポーリングするようにします。配信が同期的に完了すると想定しているコードは、実際の配信に1秒以上かかった時点で必ず破綻します。

バリデーションとエラーはどう扱うのか？

バリデーションが独立したステップになっているのには理由があります。POST /api/public/releases/{id}/validateを呼び出すと、配信を確定する前に、リリースがストアの要件を満たしているかをチェックし、問題点を返してくれます。配信の前には必ずバリデーションを行ってください。バリデーションに失敗したまま送信してしまうと、配信サイクルを無駄にするだけでなく、最悪の場合、事前に直せたはずのバリデーションエラーよりもずっと手間のかかるストアでのリジェクトを招きかねません。作成、バリデーション、修正、再度バリデーションというループを組み、バリデーションが通ってから初めて配信するようにしましょう。

エラー処理は、対応の仕方が正反対になるため、種類ごとに分けて扱ってください。4xx系は自社側の問題です。フィールドの形式誤り、ISRCの欠落、小さすぎるアートワークなどが該当します。データを変えずにリトライしても再び失敗するだけなので、エラーを表面化させ、データを修正してから再送してください。5xx系やネットワークタイムアウトは一時的なものなので、リトライして構いませんが、APIを叩き続けるタイトなループではなく、指数バックオフと上限を設けたリトライにします。これを作成ステップの冪等性キーと組み合わせておけば、タイムアウト後のリトライが誤って処理を重複させることもありません。実際のエラーコードとその意味は、推測せずにドキュメントで確認し、それぞれをリトライ、修正して再送、人による対応へのエスカレーションといった、自社システム内での明確なアクションに対応づけてください。

すべてのリクエストとレスポンスを、相関IDとともにログに残しておきましょう。3週間後にリリースが止まってしまったとき、何を送り何が返ってきたかのログがあるかどうかで、5分で直せるか、午後いっぱい推測を続けるはめになるかが決まります。

ロイヤリティとアナリティクスはどう読み込むのか？

配信は、全体の流れの半分にすぎません。楽曲が公開された後は、実績と収益を読み込んで、自社システムに実態を反映させます。これをカバーするのが2つのエンドポイントです。

GET  /api/public/analytics    # 再生数やリスナー、実績データ
GET  /api/public/statements   # ロイヤリティ明細と収益

アナリティクスは、ダッシュボードや意思決定のためのものです。再生数、リスナーデータ、各ストアでのリリースのパフォーマンスがわかります。明細は会計のためのもので、その期間に実際どれだけ収益があったかを示し、アーティストへの分配や支払いと突合できる状態になっています。どちらも定期的に取得し、自社のカタログに紐づけて自社データベースに保存し、1回の取得結果を鵜呑みにせず突合するようにしてください。レポートデータはストアからの報告が遅れることで時間とともに確定していくため、1回ごとの取得結果は最終値ではなく、その時点で最新の見え方だと考え、後から取得したデータで以前の推定値を修正するようにしましょう。

これらのレスポンスはページネーションされている前提で、最初のページだけ読んで終わりにせず、最後まで読み進めてください。データの鮮度については、必要に応じてポーリングとwebhookのどちらを使うか判断します。夜間バッチで突合するだけなら、ポーリングで十分です。配信が公開された瞬間や明細が届いた瞬間に反応する必要があり、webhookが利用できるなら、毎分ポーリングする代わりにイベントを購読しましょう。両エンドポイントの正確なクエリパラメータ、日付範囲、レスポンスの形式はAPIリファレンスにまとまっているので、必要な期間だけを正確に取得できます。

本番の前にサンドボックスでどうテストすべきか？

配信の連携を、いきなり本番環境に対して構築してはいけません。LabelGridが公開ドキュメントとあわせてサンドボックス環境を用意しているのは、実際のストアに何も送ることなく、作成からバリデーション、配信までの一連のライフサイクルを試せるようにするためです。初日から、専用の認証情報を使って統合テストをサンドボックスにつなぎ、テスト実行が誤って未完成のリリースをSpotifyに配信してしまうことのないようにしましょう。

きれいなハッピーパスだけでなく、意図的に崩したデータでもテストしてください。ISRCが欠けていたり、アートワークが小さすぎたり、アーティスト名が空だったり、日付が不正だったりするリリースをサンドボックスに投入し、バリデーションとリトライのロジックがそれぞれに対して正しく動くかを確認します。きれいなリリースはパイプラインがつながっていることを証明するだけで、壊れたデータこそがエラー処理が実際に機能していることを証明します。そして、実際のカタログにはそうしたエラー処理が欠かせません。サンドボックスでのライフサイクル確認をテストスイートに組み込み、クライアント側の変更のたびにエンドツーエンドで検証してからリリースするようにしましょう。

最初に何を作るべきか？

幅広く作り込む前に、まずは最小限に動く骨格を作りましょう。最初のマイルストーンのゴールは、1件のリリースがサンドボックス内で一連の流れをエンドツーエンドで通ることです。これによって、どこか一部を最適化する前に、経路全体が機能することを証明できます。順番は次の通りです。

• 認証を行い、GET /api/public/meが正常に返ることを確認する。
• 実際に近い形のメタデータで、POST /api/public/releasesを使って1件のリリースを作成する。
• バリデーションを行い、エラー内容を確認し、データを修正しながら、通るまでバリデーションを繰り返す。
• サンドボックスで配信し、配信完了が報告されるまでリリースをポーリングする。
• アナリティクスと明細を読み込み、自社のカタログに紐づけて保存する。

この骨格がうまく動くようになったら、意図的に範囲を広げていきます。冪等性を備えた一括カタログ取り込み、適切なバックオフとエラーのルーティング、アナリティクスと明細の定期同期、そして低遅延が必要な場合はwebhookです。サンドボックスで1件のリリースすら公開できていないうちに、カタログインポーター全体を作り込みたくなる気持ちは抑えてください。期限通りにリリースできる連携は、まず1件のリリースを最後まで通し、すでにうまくいっているパターンをそこから拡張していったものです。

残りの構築がどれだけスムーズに進むかは、2つの要素で決まります。1つは、メタデータモデルを正しく作り、リリースが最初のバリデーションで通るようにすること。もう1つは、配信とレポーティングを最初から非同期のものとして扱い、コードのどこにも即座に結果が返るという前提を残さないことです。この2つさえ押さえておけば、配信APIの連携はよく理解された、見通しの立つエンジニアリング課題になります。プラットフォームを比較検討しているのであれば、開発者向けの概要とホワイトレーベルとAPIのドキュメントで、公開されている範囲を確認でき、エンドポイントのリファレンスはapi.labelgrid.com/docs/apiで公開されています。

よくある質問