いつめん Music API
開発者ドキュメント

library_music概要

この API は、いつめん Music のローカルライブラリ（サーバー上に実ファイルがある曲）だけを対象にします。Spotify の曲は対象外です（外部サイトでの同期利用が規約上できないため）。

ベース URL は次の1つだけです。すべてのリクエストはこの入口を通ります。

https://apis.shohs.net/itumen/music/index.php

できることは2種類だけです。

• search：タイトル・アーティストでカタログを検索し、曲のメタデータ（ID・タイトル・アーティスト・長さ）を取得する。
• play：再生セッションを作り、暗号化された HLS ストリームとしてブラウザで再生する。

ダウンロード、ファイル取得、カタログ全件取得、歌詞やアートワークの取得といった機能は存在しません。詳しくは「許可される機能」と「利用ルール」を参照してください。

rocket_launchクイックスタート

投稿に曲を付けて再生するまでの流れは、次の5ステップです。ステップ1〜2は連携サイトのサーバー側（認証必須）、ステップ3〜4はブラウザ側です。

実際に叩いてみる

ステップ0：キーを用意する。SHOHS Cloud Console でプロジェクトを開き、ライブラリで「いつめん Music API」を有効にして、「認証情報」から API キーを作成します（詳しくは「認証」）。キーは作成時に一度だけ表示されます。

ステップ1：曲を探す（サーバー側）。

curl -X POST "https://apis.shohs.net/itumen/music/index.php?action=search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer shk_（作成したキー）" \
  -d '{"q":"BURNOUT","limit":20}'

{
  "results": [
    { "id": 2, "title": "FLY HIGH!!", "artist": "BURNOUT SYNDROMES", "duration": 246 },
    { "id": 3, "title": "ヒカリアレ", "artist": "BURNOUT SYNDROMES", "duration": 245 }
  ],
  "count": 2
}

ステップ2：再生セッションを作る（サーバー側）。探した曲の id を track_id に渡します。

curl -X POST "https://apis.shohs.net/itumen/music/index.php?action=session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer shk_（作成したキー）" \
  -d '{"track_id":2,"ref":"post-12345"}'

{
  "token": "（ランダムな文字列）",
  "expires_in": 426,
  "playlist_url": "https://apis.shohs.net/itumen/music/index.php?action=playlist&t=（トークン）",
  "track": { "id": 2, "title": "FLY HIGH!!", "artist": "BURNOUT SYNDROMES", "duration": 246 }
}

ステップ3：ブラウザで再生する。返ってきた playlist_url をプレイヤーに渡すだけです（サーバー側で作った URL を、そのまま使います）。

<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<audio id="player" controls></audio>
<script>
  const hls = new Hls();
  hls.loadSource(playlistUrl);  // ステップ2で受け取った playlist_url
  hls.attachMedia(document.getElementById('player'));
</script>

あとは、トークンの期限（expires_in 秒）が切れたらステップ2をやり直すだけです。そのまま使えるコードは「PHP（サーバー側）」と「JavaScript（ブラウザ再生）」にもあります。

menu_book用語集

fingerprint認証（API キー / 署名）

search と session は、連携サイトのサーバーからのみ呼べます。認証は2通りあります。通常は方法A（コンソールの API キー）を使ってください。方法B（HMAC 署名）は、管理者が発行した専用キーを使う連携向けです。どちらの方法でも、認証情報をブラウザの JavaScript に置くことは禁止です（「利用ルール」参照）。

方法A：コンソールの API キー（通常はこちら）

1. SHOHS Cloud Console で、プロジェクトのライブラリから「いつめん Music API」を有効にする
2. 「認証情報」→「API キーを作成」で、使う機能（再生セッション / 楽曲検索）を選んでキーを作成する。キーの文字列（shk_...）は作成時に一度だけ表示される
3. リクエストに Authorization: Bearer shk_... ヘッダーを付けて送る

curl -X POST "https://apis.shohs.net/itumen/music/index.php?action=search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer shk_（作成したキー）" \
  -d '{"q":"BURNOUT","limit":20}'

キーで許可した機能だけが使えます。キーの「許可する IP」に登録がある場合はその IP からだけ、「許可するオリジン」に登録がある場合は、再生がそのオリジンからだけに制限されます。コンソールでキーを削除する、またはプロジェクトでこの API を無効にすると、そのキーは即座に使えなくなります。

方法B：HMAC 署名（専用連携向け）の必須ヘッダー

署名の計算

signature = HMAC-SHA256( secret, timestamp + "." + nonce + "." + リクエストボディの生文字列 )

ボディは JSON を送信するバイト列そのまま使います（再整形すると署名が一致しません）。検証に失敗したリクエストは、理由を開示せず一律 401 unauthorized を返します。失敗が続くと送信元 IP が一時ブロックされることがあります。

key許可される機能（play / search）

この API の機能は次の2つだけです。キーごとに、どちらの機能を使えるかが決まっています（コンソールの API キーでは、キーの作成・編集時に選びます。リクエスト側で権限を広げることはできません）。

許可されていない機能を呼ぶと 403 feature_not_allowed になります。そして重要な点として、ダウンロード・書き出し・ファイル取得にあたる機能は、権限以前に API として存在しません。未知の action はすべて 404 unknown_action です。

search楽曲検索

タイトルとアーティストを対象に、部分一致（大文字小文字を区別しない）で検索します。ファイルの場所や URL は一切含まれません。

リクエストボディ

{
  "q": "BURNOUT",
  "limit": 20
}

リクエスト例

curl -X POST "https://apis.shohs.net/itumen/music/index.php?action=search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer shk_（コンソールで作成したキー）" \
  -d '{"q":"BURNOUT","limit":20}'

方法B（HMAC 署名）の場合は、Authorization の代わりに署名ヘッダーを使います（「認証」参照）。

レスポンス

{
  "results": [
    { "id": 2, "title": "FLY HIGH!!", "artist": "BURNOUT SYNDROMES", "duration": 246 },
    { "id": 3, "title": "ヒカリアレ", "artist": "BURNOUT SYNDROMES", "duration": 245 }
  ],
  "count": 2
}

レート制限はキーごとに60回/分です。

play_circle再生セッション

指定した曲の再生セッションを作成し、短命の再生トークンとプレイリスト URL を返します。

リクエストボディ

{
  "track_id": 2,
  "ref": "post-12345"
}

リクエスト例

curl -X POST "https://apis.shohs.net/itumen/music/index.php?action=session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer shk_（コンソールで作成したキー）" \
  -d '{"track_id":2,"ref":"post-12345"}'

方法B（HMAC 署名）の場合は、Authorization の代わりに署名ヘッダーを使います（「認証」参照）。

レスポンス

{
  "token": "（ランダムな文字列）",
  "expires_in": 426,
  "playlist_url": "https://apis.shohs.net/itumen/music/index.php?action=playlist&t=（トークン）",
  "track": { "id": 2, "title": "FLY HIGH!!", "artist": "BURNOUT SYNDROMES", "duration": 246 }
}

トークンの有効期限は「曲の長さ＋180秒」（上限900秒＝15分）です。レート制限はキーごとに30回/分で、このほかキーごとに利用上限があります（「制限について」参照）。

stream再生（playlist / key / seg）

ブラウザのプレイヤー（hls.js 等）が、トークン付きで取得します。署名は不要ですが、トークンがない・期限切れの場合は取得できません。CORS は https://log.itumen.com からのみ許可され、それ以外の Origin は 403 origin_denied になります。

リクエスト例

GET https://apis.shohs.net/itumen/music/index.php?action=playlist&t=（トークン）
GET https://apis.shohs.net/itumen/music/index.php?action=key&t=（トークン）
GET https://apis.shohs.net/itumen/music/index.php?action=seg&t=（トークン）&i=0

セグメントと鍵の取得には、通常の再生に必要な範囲を超えないよう、セッションごとに上限があります。上限に達すると 429 rate_limited になります（上限の詳細は公開していません）。

errorエラーコード

エラーは JSON で { "error": "コード" } の形式で返ります。

shield音源の取り扱いについて

この API で提供される音源は、再生のためだけのものです。

音声は暗号化されたストリーミング形式でのみ配信され、音源ファイルをそのまま取得する機能はありません。search で取得できるのも、曲のメタデータだけです。また、再生には短時間だけ有効なトークンが必要で、トークンの発行は連携サイトのサーバー（認証必須）からしか行えません。

音声の保存・再構成・ダウンロード可能な形での提供は、「利用ルール」で禁止されています。不適切な利用が確認された場合、キーの停止などの措置が取られます。

不正取得への対策の詳細（上限値や検知条件など）は、回避を防ぐため公開していません。通常の再生の範囲で利用する限り、制限に触れることはありません。

speed制限について

実装に必要な範囲の制限だけを公開します。これ以外の上限や、異常検知の条件は公開していません。

通常の利用で上限に触れた場合は、利用状況を添えて管理者に相談してください。

gavel利用ルール

連携するサイトの運用者が守るべきルールです。違反が確認された場合、キーは停止されます。

codePHP（サーバー側・署名）

連携サイトのサーバー側からリクエストする例です。まず方法A（コンソールの API キー）、次に方法B（HMAC 署名）を示します。キーやシークレットは環境変数から読む前提です。

方法A：コンソールの API キー

// コンソールで作成した API キー（shk_...）で送る
function music_api_post_key(string $action, array $payload): array {
    $key  = getenv('SHOHS_MUSIC_API_KEY');  // コンソールで作成したキー
    $body = json_encode($payload, JSON_UNESCAPED_UNICODE);
    $ch = curl_init('https://apis.shohs.net/itumen/music/index.php?action=' . $action);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $key,
        ],
    ]);
    $res  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    return [$code, json_decode((string) $res, true)];
}

[$code, $data] = music_api_post_key('search', ['q' => 'BURNOUT', 'limit' => 20]);
[$code, $ses]  = music_api_post_key('session', ['track_id' => 2, 'ref' => 'post-12345']);

方法B：HMAC 署名（専用連携向け）

// 署名付き POST を送る共通関数
function music_api_post(string $action, array $payload): array {
    $keyId  = getenv('SHOHS_MUSIC_KEY_ID');     // 例: log-main
    $secret = getenv('SHOHS_MUSIC_SECRET');     // 管理者から受け取ったシークレット
    $body   = json_encode($payload, JSON_UNESCAPED_UNICODE);
    $ts     = (string) time();
    $nonce  = bin2hex(random_bytes(16));
    $sig    = hash_hmac('sha256', $ts . '.' . $nonce . '.' . $body, $secret);

    $ch = curl_init('https://apis.shohs.net/itumen/music/index.php?action=' . $action);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-Api-Key-Id: ' . $keyId,
            'X-Timestamp: ' . $ts,
            'X-Nonce: ' . $nonce,
            'X-Signature: ' . $sig,
        ],
    ]);
    $res  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    return [$code, json_decode((string) $res, true)];
}

// 曲を検索する（機能: search）
[$code, $data] = music_api_post('search', ['q' => 'BURNOUT', 'limit' => 20]);
foreach ($data['results'] as $track) {
    echo $track['id'] . ': ' . $track['title'] . ' / ' . $track['artist'] . PHP_EOL;
}

// 再生セッションを作る（機能: play）
[$code, $ses] = music_api_post('session', ['track_id' => 2, 'ref' => 'post-12345']);
$playlistUrl = $ses['playlist_url'];  // これをブラウザのプレイヤーへ渡す

javascriptJavaScript（ブラウザ再生）

サーバー側で作ったセッションの playlist_url を、hls.js で再生する例です。Safari は HLS にネイティブ対応しているため、その場合はそのまま渡せます。

<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<audio id="player" controls></audio>
<script>
  const playlistUrl = // サーバー側で action=session を呼んで得た playlist_url '...';
  const audio = document.getElementById('player');
  if (window.Hls && Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(playlistUrl);
    hls.attachMedia(audio);
  } else if (audio.canPlayType('application/vnd.apple.mpegurl')) {
    audio.src = playlistUrl;  // Safari
  }
</script>

再生中に 401 invalid_or_expired_token になったら、トークンの期限切れです。サーバー側で新しいセッションを作り直し、新しい playlist_url を読み込んでください。トークンや URL をブラウザ側に保存（localStorage 等）しないでください。

helpFAQ

Q. 再生中に止まって 401 が返ってきた

再生トークンの期限切れです。有効期限は最長15分なので、長い曲の付け替えやポーズを挟む場合は、サーバー側でセッションを作り直してください。

Q. プレイヤーから 403 origin_denied が返る

再生が許可されているのは https://log.itumen.com だけです。別ドメイン（開発環境を含む）から再生したい場合は、管理者に相談してください。

Q. 曲の一覧を全部取得したい

できません。search はキーワード検索のみで、空検索による全件取得はできない設計です。

Q. Spotify の曲は使える？

使えません。この API の対象はローカルライブラリの曲だけです。

Q. コンソールの API キー（shk_...）で呼べる？

呼べます。それが標準の方法です（方法A）。プロジェクトでこの API を有効にして、認証情報からキーを作成し、Authorization: Bearer で送ってください。キーで許可した機能（play / search）だけが使えます。再生できるオリジンは、キーの「許可するオリジン」に登録したものになります。

Q. 上限を増やしてほしい

利用状況を添えて管理者に相談してください。通常の利用範囲であれば、キーごとに調整できる場合があります。

history変更履歴