API Referencelink

概要link

ImageFlux Live StreamingのAPIは最新のSora SFU APIと互換性を保っています。 対応するSora SFUのバージョンは更新履歴をご確認ください。

APIの仕様は次の通りです。

  • APIのエンドポイントは https://live-api.imageflux.jp/ です。
  • エンドポイントのパスは / です。
  • APIは X-Sora-Target ヘッダで指定します。
  • すべてのリクエストはHTTP POSTメソッドを使用します。
  • リクエストボディにはJSONフォーマットでパラメータを指定します。

curl コマンドを使ってリクエストする場合は次のようになります。

curl -XPOST \
-H "Content-Type: application/json" \
-H "X-Sora-Target: ImageFlux_20180905.CreateChannel" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "hls": [
    {
      "durationSeconds": 1,
      "startTimeOffset": -2,
      "video": {
        "width": 640,
        "height": 480,
        "fps": 30,
        "bps": 1000000
      },
      "audio": {
        "bps": 64000
      }
    }
  ]
}' \
https://live-api.imageflux.jp/

認証link

すべてのAPIはAuthorizationヘッダのBearerトークンを利用して認証します。 $ACCESS_TOKEN には事前に共有したアクセストークンを指定します。

    Authorization: Bearer $ACCESS_TOKEN

ImageFlux_20180905.CreateChannellink

クライアントが接続するシングルストリームのチャンネルを作成します。 HLS変換を行います。

Requestlink

{
  "hls": [
    {
      "durationSeconds": 1,
      "startTimeOffset": -2,
      "video": {
        "width": 640,
        "height": 480,
        "fps": 12,
        "bps": 2465792
      },
      "audio": {
        "bps": 64000
      },
      "archive": {
        "archive_destination_id": "<archive_destination_id>"
      }
    }
  ],
  "encrypt_key_uri": "https://example.com/api/encrypt_key_uri",
  "auth_webhook_url": "https://example.com/api/auth_webhook_url",
  "event_webhook_url": "https://example.com/api/event_webhook_url"
}
  • hls HLS変換のときのトランスコードの設定です。マルチビットレートにするには配列で複数個指定します。
    • durationSeconds
      • HLS配信でのセグメント時間を指定します。短く設定するほど遅延を減らすことができますが、配信あたりの転送量が増加します。
    • startTimeOffset
      • HLS配信でのEXT-X-START:TIME-OFFSETパラメータを指定します。TIME-OFFSETの値は、符号付き10進の浮動小数点数の秒数です。正の数は、プレイリストの先頭からの時間オフセットを示します。負の数は、プレイリストの最後のメディアセグメントの終わりからの負の時間オフセットを示します。推奨値は -2 です。
    • video
      • width
        • 出力する幅のピクセル数を指定します。最小値は160です。最大値は4096です。
      • height
        • 出力する高さのピクセル数を指定します。最小値は160です。最大値は4096です。
      • fps
        • 秒間フレーム数(frames per second)を指定します。最小値は3です。最大値は60です。
      • bps
        • 映像の最大ビットレートを指定します。最小値は15000です。最大値は15000000です。単位はbpsです。(kbpsではありませんので注意してください)
      • codec
        • 映像のコーデックを指定します。有効な値は下記を参照してください。
    • audio
      • bps
        • 音声のビットレートを指定します。デフォルト値は96000です。最小値は32000です。最大値は320000です。単位はbpsです。(kbpsではありませんので注意してください)
    • archive
      • archive_destination_id
  • encrypt_key_uri
    • 会員認証APIのURLを指定します。httpsスキームのみです。
    • 未指定または空文字列を指定した場合、暗号化処理はされません。
    • auth_webhook_url, event_webhook_urlと少し似ていますが、encrypt_key_uriの末尾はURI(ユー・アール・アイ)です。
    • 会員限定配信および会員認証APIの詳細はこちらのページを参照してください。
  • auth_webhook_url
    • 認証Webhookを送信するURLを指定します。
    • 認証Webhookの仕様はSoraのドキュメントの認証ウェブフックの項目を参照してください。
    • 空文字列を指定した場合、すべての接続が許可されます。
  • event_webhook_url
    • イベントWebhookを送信するURLを指定します。
    • 空文字列を指定した場合、イベントWebhookは送信されません。
    • イベントフックの仕様はSoraのドキュメントのイベントウェブフックの項目を参照してください。

利用可能な音声ビットレートlink

以下の値以外が指定された場合、指定されたビットレートを超えない最大の値が選択されます。

ビットレート
32 kbps 32000
40 kbps 40000
48 kbps 48000
56 kbps 56000
64 kbps 64000
80 kbps 80000
(デフォルト) 96 kbps 96000
112 kbps 112000
128 kbps 128000
160 kbps 160000
192 kbps 192000
224 kbps 224000
256 kbps 256000
320 kbps 320000

利用可能な映像コーデックlink

H264のHighプロファイル、Mainプロファイル、Baselineプロファイルを指定できます。デフォルトはHighプロファイルです。
有効な値は以下の通りです。

  • "h264_high": H264のHighプロファイル
  • "h264_main": H264のMainプロファイル
  • "h264_baseline": H264のBaselineプロファイル

Responselink

{
    "channel_id": "<channel_id>",
    "sora_url": "ws://example.com:5000/signaling",
    "playlist_url": "https://example.com/hls/XXXX/XXXXXXXX.m3u8"
}
  • channel_id
    • 作成されたチャンネルの channel_id
  • sora_url
    • 配信者が接続するSoraサーバのURL
  • playlist_url
    • HLSプレイリストファイルのURL

ImageFlux_20200316.CreateMultistreamChannellink

クライアントが接続するマルチストリームのチャンネルを作成します。 HLS変換は行いません。

Requestlink

{
  "auth_webhook_url": "https://example.com/api/auth_webhook_url",
  "event_webhook_url": "https://example.com/api/event_webhook_url"
}
  • auth_webhook_url
    • 認証Webhookを送信するURLを指定します。
    • 認証Webhookの仕様はSoraのドキュメントの認証ウェブフックの項目を参照してください。
    • 空文字列を指定した場合、すべての接続が許可されます。
  • event_webhook_url
    • イベントWebhookを送信するURLを指定します。
    • 空文字列を指定した場合、イベントWebhookは送信されません。
    • イベントフックの仕様はSoraのドキュメントのイベントウェブフックの項目を参照してください。

Responselink

{
    "channel_id": "<channel_id>",
    "sora_url": "ws://example.com:5000/signaling",
}
  • channel_id
    • 作成されたチャンネルの channel_id
  • sora_url
    • 配信者が接続するSoraサーバのURL

ImageFlux_20200316.CreateMultistreamChannelWithHLSlink

クライアントが接続するマルチストリームのチャンネルを作成します。 HLS変換を行います。

Requestlink

{
  "hls": [
    {
      "durationSeconds": 1,
      "startTimeOffset": -2,
      "video": {
        "width": 640,
        "height": 480,
        "fps": 12,
        "bps": 2465792
      },
      "audio": {
        "bps": 64000
      },
      "archive": {
        "archive_destination_id": "<archive_destination_id>"
      }
    }
  ],
  "encrypt_key_uri": "https://example.com/api/encrypt_key_uri",
  "auth_webhook_url": "https://example.com/api/auth_webhook_url",
  "event_webhook_url": "https://example.com/api/event_webhook_url"
}

RequestはImageFlux_20180905.CreateChannelのものと同じです。

Responselink

{
    "channel_id": "<channel_id>",
    "sora_url": "ws://example.com:5000/signaling",
}
  • channel_id
    • 作成されたチャンネルの channel_id
  • sora_url
    • 配信者が接続するSoraサーバのURL

HLSのプレイリストURLを取得する方法link

マルチストリームのチャンネルのHLS変換ではHLSのプレイリストURLは配信開始後に決まります。 それを取得するのに2つの方法があります。

イベントWebhookによる通知link

チャンネルの作成時にイベントWebhookを登録してください。 HLSのプレイリストURLが利用可能になったとき"type": "notify.playlist_url" のイベントで通知されます。 その際、イベントの内容は以下のようになります。

{
  "channel_id": "<channel_id>",
  "connection_id": "<connection_id>",
  "timestamp": "2020-01-02T12:34:56.12345Z",
  "type": "notify.playlist_url",
  "playlist_url": "https://example.com/hls/XXXX/XXXXXXXX.m3u8"
}

APIによる取得link

配信開始した後に数秒待ってからImageFlux_20200207.ListPlaylistURLs を使用してHLSのプレイリストURLの一覧を取得してください。早すぎた場合にはその配信の情報が一覧にまだ含まれません。

ImageFlux_20200207.ListPlaylistURLslink

指定したチャンネルにあるHLSのプレイリストURLの一覧を取得します。

Requestlink

{
    "channel_id": "<channel_id>"
}
  • channel_id
    • チャンネルの channel_id

Responselink

{
    "channel_id": "<channel_id>",
    "hls": [
        {
            "connection_id": "<connection_id>",
            "playlist_url": "https://example.com/hls/XXXX/XXXXXXXX.m3u8"
        },...
    ]
}
  • channel_id
    • チャンネルの channel_id
  • connection_id
    • 配信の connection_id
  • playlist_url
    • HLSプレイリストファイルのURL

ImageFlux_20180501.DeleteChannellink

指定したチャンネルを削除します。 チャンネルに接続しているクライアントは強制的に切断され、HLSの生成も終了します。 以降はこのチャンネルを使用しての接続はできません。

Requestlink

{
    "channel_id": "<channel_id>"
}
  • channel_id
    • 削除するチャンネルの channel_id

ImageFlux_20200729.ListChannelIDslink

作成済みのチャンネルのchannel_idの一覧を取得します。 不要になったchannelはDeleteChannel APIで削除してください。

Requestlink

{}

Responselink

{
    "channel_ids": [
        "<channel_id>"
        ...
    ]
}
  • channel_ids
    • 作成済みのチャンネルのchannel_idの配列

ImageFlux_20190205.CreateArchiveDestinationlink

アーカイブ保存先を新たに作成します。

Requestlink

{
    "bucket_uri": "<bucket_uri>",
    "aws_region": "<aws_region>",
    "aws_access_key_id": "<aws_access_key_id>",
    "aws_secret_access_key": "<aws_secret_access_key>",
    "gcp_credential_json": "<gcp_credential_json>"
}
  • bucket_uri
    • 保存先バケットのURIを指定します。
    • Amazon S3を指定する場合、 s3:// スキームを用いて s3://<my-bucket-name>/<path>/ のように入力します。
    • Google Cloud Storageを指定する場合、 gs:// スキームを用いて gs://<my-bucket-name>/<path> のように入力します。
  • aws_region
    • Amazon Web Servicesのリージョン名を指定します。S3以外のときは不要です。
  • aws_access_key_id
    • AWSのアクセスキーIDを指定します。S3以外のときは不要です。
  • aws_secret_access_key
    • AWSのシークレットアクセスキーを指定します。S3以外のときは不要です。
  • gcp_credential_json
    • GCP(Google Cloud Platform)のクレデンシャルJSONを文字列で指定します。オブジェクトではなく、文字列として指定する必要があります。Google Cloud Storage以外のときは不要です。

Responselink

{
    "archive_destination_id": "<archive_destination_id>"
}
  • archive_destination_id
    • 作成されたアーカイブ保存先のIDです。

ImageFlux_20190205.DeleteArchiveDestinationlink

作成されているアーカイブ保存先を削除します。

Requestlink

{
    "archive_destination_id": "<archive_destination_id>"
}
  • archive_destination_id
    • アーカイブ保存先のIDを指定します。

ImageFlux_20190205.ListArchiveDestinationslink

アーカイブ保存先の一覧を取得します。

Requestlink

{}

Responselink

{
    "archive_destinations": [
        {
                "archive_destination_id": "<archive_destination_id>",
                "bucket_uri": "<bucket_uri>"
        },...
    ]
}

SoraのAPIlink

以下のSoraのAPIを利用できます。 詳細はSoraのAPIドキュメントを参照してください。

自分のアクセストークンで作成された channel_id 以外は指定できません。

(非推奨) とついているものは廃止予定のAPIです。

シグナリングAPIlink

  • Sora_20151104.DisconnectChannel
  • Sora_20151104.DisconnectClient
  • Sora_20151104.DisconnectConnection
  • Sora_20151104.ListConnections(非推奨)
  • Sora_20170814.ListChannelClients(非推奨)
  • Sora_20201013.ListChannelConnections
  • Sora_20201120.DisconnectChannelByRole

プッシュAPIlink

  • Sora_20160711.PushChannel
  • Sora_20160711.PushClient
  • Sora_20160711.PushConnection
  • Sora_20160711.PushUpstream(非推奨)
  • Sora_20160711.PushDownStream(非推奨)
  • Sora_20201120.PushChannelByRole

統計APIlink

  • Sora_20170529.GetStatsClient
  • Sora_20170529.GetStatsConnection

スポットライトレガシーAPIlink

  • Sora_20180404.CastSpotlight(非推奨)
  • Sora_20180404.CastAlwaysSpotlight(非推奨)
  • Sora_20180404.CancelSpotlight(非推奨)
  • Sora_20181023.DowngradeSpotlightBitRate(非推奨)
  • Sora_20181023.ResetSpotlightBitRate(非推奨)

スポットライトAPIlink

  • Sora_20200807.FocusSpotlightFixed
  • Sora_20200807.FocusSpotlight
  • Sora_20200807.UnfocusSpotlight
  • Sora_20200807.ChangeSpotlightNumber

サイマルキャストAPIlink

  • Sora_20180820.ChangeSimulcastQuality(非推奨)
  • Sora_20201005.RequestRtpStream
  • Sora_20201005.ResetRtpStream

シグナリング通知メタデータ拡張APIlink

  • Sora_20201124.ListSignalingNotifyMetadata
  • Sora_20201124.GetSignalingNotifyMetadata
  • Sora_20201124.PutSignalingNotifyMetadata
  • Sora_20201124.DeleteSignalingNotifyMetadata
  • Sora_20201124.PutSignalingNotifyMetadataItem
  • Sora_20201124.DeleteSignalingNotifyMetadataItem

RTPストリーム停止/再開APIlink

  • Sora_20200401.PauseRtpStream
  • Sora_20200401.ResumeRtpStream
  • Sora_20200401.ListPauseRtpStreams

リモート統計情報APIlink

  • Sora_20200225.GetChannelRemoteStats
  • Sora_20200225.GetConnectionRemoteStats

そのほかのAPIlink

  • Sora_20190327.ChangeUpstreamVideoBitRate