Documentation Powered by ReDoc

ULIZA En-Cluster (Cloud) API 仕様書 (1.12.0)

本書は ULIZA En-Cluster (Cloud) が提供する API 仕様について記述しています。ULIZA En-Cluster (Cloud) の機能や制限、管理画面の操作方法については ULIZA En-Cluster (Cloud) ユーザーガイド を参照してください。

なお、本書に掲載しているコードサンプル（Request samples）は、具体的な実装例を示すことで開発者を支援することを目的としていますが、掲載しているコードがすべての環境において正常に動作することを保証するものではありません。また、コードサンプル内で使用している関数やライブラリの安全性に関して、弊社は何ら責任を負うものではありません。

string 型のパラメータに使用可能な文字は、特記のない限り半角英数字およびハイフン、アンダースコアのみです。

注意

本書に記述している API を利用するには、対応するオプション（「ULIZA FLEX II - マルチ WebAPI オプション」など）のご契約が必要となります。詳細については お問い合わせ ください。

CHANGELOG

バージョン 改版日 改版内容
v1.0.0 2018/05/31 初版
v1.1.0 2019/04/12 a. プリセット管理系 API に license_server_account プロパティを追加
b. タスク登録 API に upload_type プロパティを追加
v1.2.0 2019/09/30 a. ULIZA VMS (Cloud) へのコンテンツ登録のプロパティを追加
b. タスク取得 API に format が HLS 関連の新たなプロパティを追加
c. タスク登録 API にプリセット・オーバーライド機能関連のプロパティを追加
v1.2.1 2019/11/28 a. プロファイル管理系 APIの vms_config に seek_preview プロパティを追加
v1.3.0 2020/02/25 a. プリセット管理系 API の destination プロパティにおいて 任意のAWS S3 バケットの指定に対応
b. プリセット管理系 API の destination_settingsプロパティを追加
c. プリセット管理系 API の poster に destination および filename_prefix プロパティを追加
d. プリセット管理系 API の streams に watermarks プロパティを追加
e. プリセット管理系 API の format プロパティにおいて PASSTHROUGH の指定に対応
f. AWS 外部 ID 取得 API を追加
g. タスク登録 API に poster_filename_prefix プロパティを追加
h. タスク取得 API およびタスク詳細取得 APIに poster プロパティを追加
v1.5.0 2021/03/15 a. プリセット管理系 API の hls_config に multi_audio_flag プロパティを追加
v1.5.4 2021/06/28 a. トップページの説明文を変更
b. API 全体に403エラーのレスポンスを追加
c. タスク削除 API の名称をタスクキャンセル/削除 API に変更
d. タスク登録 API 、タスク全削除 API、タスクキャンセル/削除 API、プリセット登録 API、プロファイル登録 API に説明文を追加
v1.5.5 2021/07/12 a. タスク登録 API の説明文を変更
v1.6.0 2021/10/05 a. 通知設定系 API を追加
v1.7.0 2021/11/22 a. 通知設定系 API に notify_imported_tasks プロパティを追加
b. CSV インポートジョブ管理系 API を追加
v1.8.0 2022/02/22 a. タスク登録 API に trim プロパティを追加
v1.9.0 2022/03/16 a. タスク登録 API に multi_angles プロパティと multi_angle_labels プロパティを追加
v1.10.0 2022/06/07 a. プリセット管理系 API に dynamic_streams プロパティを追加
b. プリセット管理系 API の video に height プロパティを追加
v1.11.0 2022/10/04 a. 入力ファイル詳細取得 API に説明文を追加
b. タスク登録 API の vms_config プロパティに説明文を追加
v1.11.1 2023/04/05 a. タスク登録 API の input_filepath プロパティと output_filename のプロパティの最大文字数を 70 に変更
v1.12.0 2024/04/03 a. 共有プロファイル全取得 API を追加
b. プロファイル管理系 API に share プロパティを追加

Authentication

特に断りのない限り、本書に記載されている全ての API に対するリクエストの Authorization ヘッダに下記の形式で有効な API 認証キーを含める必要があります。API 認証キーの取得方法については ULIZA プロダクトアカウントユーザーガイド を参照してください。リクエストに有効な API 認証キーが含まれていない場合は、401 Unauthorized が返却されます。

Authorization: Bearer <api-credential>

Authorization

ユーザー認証系 API について以下に記述します。

AWS 外部 ID 取得 API

任意の S3 バケットにアップロードするために必要な IAM ロールの作成時に使用する外部 ID を取得します。

Responses

Response Schema: application/json
external_id
string [ 2 .. 96 ] characters

外部 ID

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/external_id'

Response samples

Content type
application/json
{
  • "external_id": "4c4d59cf271f4f99060bb91630558c36f1c8566f14fe6494ea62874429771c79"
}

Tasks

タスク管理系 API について以下に記述します。

タスク件数取得 API

ステータスごとのタスク件数を取得します。リクエスト送信者が タスクの取得 権限を持っていない場合は、403 Forbidden が返却されます。

Responses

Response Schema: application/json
waiting
integer >= 0

ステータスが準備中のタスク件数

encoding
integer >= 0

ステータスがエンコード中のタスク件数

uploading
integer >= 0

ステータスがアップロード中のタスク件数

ready
integer >= 0

ステータスが完了のタスク件数

canceling
integer >= 0

ステータスがキャンセル中のタスク件数

canceled
integer >= 0

ステータスがキャンセル済みのタスク件数

failed
integer >= 0

ステータスがエラーのタスク件数

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/counts'

Response samples

Content type
application/json
{
  • "waiting": 0,
  • "encoding": 2,
  • "uploading": 1,
  • "ready": 34,
  • "canceling": 0,
  • "canceled": 4,
  • "failed": 0
}

タスク取得 API

タスクの情報を取得します。リクエスト送信者が タスクの取得 権限を持っていない場合は、403 Forbidden が返却されます。

query Parameters
page
integer >= 1
Default: 1

取得するページ番号

per_page
integer [ 1 .. 100 ]
Default: 10

1 ページあたりの取得件数

sort
string
Default: "created_at|desc"

ソートする列名および方向（昇順 asc または降順 desc）を | で連結した文字列。使用可能な列名は以下の通りです。

  • id ： タスク ID
  • input_filename ： 入力ファイル名
  • output_filename ： 出力ファイル名
  • preset_id ： プリセット ID
  • preset_name ： プリセット名
  • format ： フォーマット
  • status ： ステータス
  • created_at ： タスク登録日時
  • updated_at ： タスク更新日時

Responses

Response Schema: application/json
Array of objects

タスク情報

total
integer >= 0

タスク総数

per_page
integer [ 1 .. 100 ]

1 ページあたりの取得件数

current_page
integer >= 1

現在のページ番号

last_page
integer >= 1

最終ページ番号

from
integer >= 0

現在のページの開始番号

to
integer >= 0

現在のページの終了番号

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/tasks?page=2&per_page=10&sort=created_at|desc'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 41,
  • "per_page": 10,
  • "current_page": 2,
  • "last_page": 5,
  • "from": 11,
  • "to": 20
}

タスク登録 API

新規のタスクを登録します。リクエスト送信者が タスクの登録 権限を持っていない場合は、403 Forbidden が返却されます。

タスク登録によってタスク登録可能数を超過すると、エラーコード OVER_SERVICE_LIMIT と共に 403 Forbidden が返却され、タスク登録に失敗します。この場合は、登録済みのタスクのステータスが完了、キャンセル済み、エラーのいずれかに変化することで再びタスク登録を行えるようになります。現在のタスク登録可能数はアカウント設定画面の基本情報から確認することができます。

Request Body schema: application/json
input_filepath
string [ 1 .. 70 ] characters

入力ファイルのファイルパス

profile_id
integer >= 1

適用するプロファイル ID

output_filename
string <= 70 characters Nullable

拡張子を除いた出力ファイル名。この項目は profile_id で指定したプロファイルに、出力ファイル名が「任意の文字列（実行時に毎回指定）」であるプリセットが 1 個以上含まれている場合にのみ有効かつ必須となります。

episode_name
string <= 100 characters Nullable

エピソード名。この項目は profile_id で指定したプロファイルに、エピソード名が「任意の文字列（実行時に毎回指定）」であるプリセットが 1 個以上含まれている場合にのみ有効かつ必須となります。この項目には空白文字以外の任意の文字を使用することができます。

poster_filename_prefix
string [ 1 .. 50 ] characters

ポスター画像のファイル名。この項目は profile_id で指定したプロファイルに、ポスター画像のファイル名が「任意の文字列（実行時に毎回指定）」であるプリセットが 1 個以上含まれている場合にのみ有効かつ必須となります。

priority
integer [ 0 .. 99 ] Nullable
Default: 50

タスクの優先度。優先度が高いタスクは優先度が低いタスクよりも可能な限り先にエンコード処理が開始されます。また、優先度が同じタスクは登録順にエンコード処理が開始されます。

seek_preview_filename
string [ 1 .. 50 ] characters

拡張子を除いたシークプレビュー画像のファイル名。この項目は profile_id で指定したプロファイルに、シークプレビュー画像のファイル名が「任意の文字列（実行時に毎回指定）」であるプリセットが 1 個以上含まれている場合にのみ有効かつ必須となります。

upload_type
string Nullable
Default: "internal"
Enum: "internal" "external"

入力ファイルのアップロード方法

  • internal : 管理画面から入力ファイルをアップロード済み
  • external : HTTP (WebDAV)、HTTPS (WebDAV)、FTP、FTPS および SFTP などのプロトコルを使用して入力ファイルをアップロード済み
segment_filename_prefix
string [ 1 .. 30 ] characters Nullable ^[0-9a-zA-Z_]+$

HLS のセグメントファイルのファイル名の接頭辞。この項目は profile_id で指定したプロファイルに、セグメントファイルのファイル名の接頭辞が「任意の文字列（実行時に毎回指定）」であるプリセットが 1 個以上含まれている場合にのみ有効かつ必須となります。

object

トリミングの設定

multi_angles
Array of strings [ 1 .. 7 ] items

マルチアングル動画の設定。配列に追加の入力ファイルのファイル名を指定します。

multi_angle_labels
Array of strings [ 2 .. 8 ] items

マルチアングル動画のラベル名。配列にラベル名を指定します。

object

ULIZA VMS (Cloud) へのコンテンツ登録に関する設定

Array of objects

プリセット・オーバーライド機能。プリセットに登録済みの設定値がオーバーライドされエンコード処理が行われます

Responses

Response Schema: application/json
success_count
integer >= 0

登録成功タスク件数

failure_count
integer >= 0

登録失敗タスク件数

transaction
integer

1 個のプロファイルから同時に登録された複数のタスクをグループ化するための識別子

Array of objects

Request samples

Content type
application/json
{
  • "input_filepath": "cat.mp4",
  • "profile_id": 18,
  • "output_filename": "sample_cat",
  • "episode_name": "sample_cat",
  • "poster_filename_prefix": "sample_poster",
  • "priority": 50,
  • "seek_preview_filename": "sample_seek_preview_file",
  • "upload_type": "internal",
  • "segment_filename_prefix": "sample_segment_file",
  • "trim": {
    },
  • "multi_angles": [
    ],
  • "multi_angle_labels": [
    ],
  • "vms_config": {
    },
  • "preset_overrides": [
    ]
}

Response samples

Content type
application/json
{
  • "success_count": 1,
  • "failure_count": 0,
  • "transaction": 123,
  • "tasks": [
    ]
}

タスク全削除 API

ステータスが完了、キャンセル済み、エラーのいずれかであるタスクをすべて削除します。リクエスト送信者が タスクの削除 権限を持っていない場合は、403 Forbidden が返却されます。

この操作はタスクリストから削除するのみであり、ULIZA VMS (Cloud) のコンテンツや出力ファイルは削除されません。

Responses

Request samples 

curl \
  -X DELETE \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/tasks'

Response samples

Content type
application/json
{
  • "code": "REQUEST_UNAUTHORIZED",
  • "message": "Invalid credentials."
}

タスク詳細取得 API

指定したタスクの詳細情報を取得します。リクエスト送信者が タスクの取得 権限を持っていない場合は、403 Forbidden が返却されます。

path Parameters
task-id
required
integer >= 1

取得するタスク ID

Responses

Response Schema: application/json
id
integer >= 1

タスク ID

transaction
integer

1 個のプロファイルから同時に登録された複数のタスクをグループ化するための識別子

status
string
Enum: "waiting" "encoding" "uploading" "ready" "canceling" "canceled" "failed"

タスクのステータス

  • waiting ： 準備中
  • encoding ： エンコード中
  • uploading ： アップロード中
  • ready ： 完了
  • canceling ： キャンセル中
  • canceled ： キャンセル済み
  • failed ： エラー
error_code
integer >= 0

エラーコード（正常なタスクでは 0 となります）

input_filename
string non-empty

入力ファイル名

multi_angles
Array of strings [ 1 .. 7 ] items

マルチアングル動画用の入力ファイル名

output_filename
string non-empty

出力ファイル名

profile_id
integer >= 1

プロファイル ID

profile_name
string non-empty

プロファイル名

preset_id
integer >= 1

プリセット ID

preset_name
string non-empty

プリセット名

format
string
Enum: "MP4" "HLS" "DASH"

出力フォーマット

destination
string non-empty

アップロード先

object Nullable

ポスター画像

object Nullable

シークプレビュー画像

encode_start
string <yyyy-mm-dd hh:mm:ss> Nullable

エンコード開始日時

encode_end
string <yyyy-mm-dd hh:mm:ss> Nullable

エンコード終了日時

episode_name
string Nullable

エピソード名（ULIZA VMS G4 に登録しないタスクでは null となります）

publish_start
string <yyyy-mm-dd hh:mm:ss> Nullable

エピソード公開開始日時（ULIZA VMS G4 に登録しないタスクでは null となります）

publish_end
string <yyyy-mm-dd hh:mm:ss> Nullable

エピソード公開終了日時（ULIZA VMS G4 に登録しないタスクでは null となります）

object Nullable

ULIZA VMS (Cloud) へのコンテンツ登録に関する設定（ULIZA VMS (Cloud) に登録しないタスクでは null となります）

created_at
string <yyyy-mm-dd hh:mm:ss>

タスク登録日時

updated_at
string <yyyy-mm-dd hh:mm:ss>

タスク最終更新日時

Array of objects

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/tasks/186'

Response samples

Content type
application/json
{
  • "id": 186,
  • "transaction": 439,
  • "status": "ready",
  • "error_code": 0,
  • "input_filename": "cat.mp4",
  • "multi_angles": [
    ],
  • "output_filename": "sample_cat.mp4",
  • "profile_id": 268,
  • "profile_name": "sample_profile",
  • "preset_id": 68,
  • "preset_name": "sample_preset",
  • "format": "HLS",
  • "destination": "/output",
  • "poster": {
    },
  • "seek_preview": {
    },
  • "encode_start": "2017-01-01 00:00:00",
  • "encode_end": "2017-01-01 00:00:00",
  • "episode_name": "サンプルエピソード",
  • "publish_start": "1970-01-01 00:00:00",
  • "publish_end": "2100-12-31 00:00:00",
  • "vms_config": {
    },
  • "created_at": "2017-01-01 00:00:00",
  • "updated_at": "2017-01-01 00:00:00",
  • "streams": [
    ]
}

タスクキャンセル/削除 API

指定したタスクをキャンセルまたは削除します。リクエスト送信者が タスクの削除 権限を持っていない場合は、403 Forbidden が返却されます。

指定したタスクのステータスが準備中、エンコード中のいずれかである場合は、タスクの処理をキャンセルします。タスクのキャンセルに成功すると、タスクのステータスはキャンセル中に変化します。ステータスがキャンセル中であるタスクは、一定時間が経過するとステータスがキャンセル済みに変化します。

指定したタスクのステータスが完了、キャンセル済み、エラーのいずれかである場合は、タスクを削除します。なお、この操作はタスクリストから削除するのみであり、ULIZA VMS (Cloud) のコンテンツや出力ファイルは削除されません。

指定されたタスクのステータスがアップロード中、キャンセル中のいずれかである場合は、キャンセルも削除もされず 403 Forbidden が返却されます。

path Parameters
task-id
required
integer >= 1

削除するタスク ID

Responses

Request samples 

curl \
  -X DELETE \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/tasks/186'

Response samples

Content type
application/json
{
  • "code": "REQUEST_UNAUTHORIZED",
  • "message": "Invalid credentials."
}

入力ファイル詳細取得 API

指定した入力ファイルの詳細情報を取得します。リクエスト送信者が アップロード済ファイルの取得 権限を持っていない場合は、403 Forbidden が返却されます。

path Parameters
filename
required
string

取得する入力ファイル名（値は URL エンコードする必要があります）

query Parameters
readable
boolean
Default: 0

ファイルサイズの表示方法

  • 0 : バイト単位で表示
  • 1 : ファイルサイズに単位をつけて表示

Responses

Response Schema: application/json
filename
string

入力ファイル名

filesize
string

入力ファイルのファイルサイズ

filetime
string <yyyy-mm--dd hh:mm:ss>

入力ファイルの最終更新日時

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/upload/sample_file?readable=0'

Response samples

Content type
application/json
{
  • "filename": "sample_filename.mp4",
  • "filesize": 1433902201,
  • "filetime": "2017-01l-01 00:00:00"
}

Task Imports

CSV インポートジョブ管理系 API について以下に記述します。

CSV インポートジョブ取得 API

すべての CSV インポートジョブの情報を取得します。リクエスト送信者が タスクの取得 権限を持っていない場合は、403 Forbidden が返却されます。

Responses

Response Schema: application/json
Array of objects

CSV インポートジョブ情報

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/task-imports'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

CSV インポートジョブ詳細取得 API

指定した CSV インポートジョブの詳細情報を取得します。リクエスト送信者が タスクの取得 権限を持っていない場合は、403 Forbidden が返却されます。

path Parameters
task-import-id
required
integer >= 1

取得する CSV インポートジョブ ID

Responses

Response Schema: application/json
id
integer >= 1

CSV インポートジョブ ID

name
string [ 1 .. 30 ] characters

CSV インポートジョブ名

object

タスク登録進捗状況

object

タスク進捗状況

created_at
string <yyyy-mm-dd hh:mm:ss>

CSV インポートジョブ登録日時

updated_at
string <yyyy-mm-dd hh:mm:ss>

CSV インポートジョブ最終更新日時

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/task-imports/64'

Response samples

Content type
application/json
{
  • "id": 64,
  • "name": "job-2021-11-22-17-14-01",
  • "import_status": {
    },
  • "task_status": {
    },
  • "created_at": "2021-11-22 00:00:00",
  • "updated_at": "2021-11-22 00:00:00"
}

CSV インポートジョブ削除 API

指定した CSV インポートジョブを削除します。リクエスト送信者が タスクの削除 権限を持っていない場合は、403 Forbidden が返却されます。

path Parameters
task-id
required
integer >= 1

削除する CSV インポートジョブ ID

Responses

Request samples 

curl \
  -X DELETE \
  -H 'Authorization: Bearer {your-token}' \
    'https://encluster-api.p.uliza.jp/v1/task-imports/64'

Response samples

Content type
application/json
{
  • "code": "REQUEST_UNAUTHORIZED",
  • "message": "Invalid credentials."
}

Presets

プリセット管理系 API について以下に記述します。

プリセット全取得 API

すべてのプリセットの情報を取得します。リクエスト送信者が プリセットの取得 権限を持っていない場合は、403 Forbidden が返却されます。

Responses

Response Schema: application/json
Array of objects

プリセット情報

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/presets'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

プリセット登録 API

プリセットを登録します。リクエスト送信者が プリセットの登録 権限を持っていない場合は、403 Forbidden が返却されます。

プリセット登録によってプリセット登録可能数を超過すると、エラーコード OVER_SERVICE_LIMIT と共に 403 Forbidden が返却され、プリセット登録に失敗します。この場合は、プリセットを削除することで再びプリセット登録を行えるようになります。現在のプリセット登録可能数はアカウント設定画面の基本情報から確認することができます。

Request Body schema: application/json
name
string [ 1 .. 30 ] characters ^[0-9a-zA-Z-_]+$

プリセット名

description
string <= 150 characters Nullable

プリセットの説明

destination
string [ 1 .. 150 ] characters

出力ファイルのアップロード先。任意の S3 バケットにアップロードする場合は、destination_settings.s3.authentication_method を指定する必要があります。

  • ULIZA VMS (Cloud) に登録する場合は ulizavms5:// の形式で指定します。
  • ULIZA VMS G4 に登録する場合は ulizavms4://<事業者ID>:<フォルダID> の形式で指定します。
  • 任意の URL にアップロードする場合は、http(s):// または ftp(s):// で始まる URL を指定します。
  • 任意の S3 バケット にアップロードする場合は、s3://<バケット名>/<オブジェクトのキーの接頭辞> の形式で指定します。
object

アップロード先に関する設定

format
string
Enum: "MP4" "HLS" "HLS_ENCRYPTED" "DASH" "DASH_ENCRYPTED" "PASSTHROUGH"

出力フォーマット。 HLS または HLS_ENCRYPTED を指定した場合は hls_config を指定する必要があります。DASH または DASH_ENCRYPTED を指定した場合は dash_config を指定する必要があります。

  • MP4 : MP4
  • HLS : HLS (暗号化なし)
  • HLS_ENCRYPTED : HLS (暗号化あり)
  • DASH : DASH (暗号化なし)
  • DASH_ENCRYPTED : DASH (暗号化あり)
  • PASSTHROUGH : PASSTHROUGH。トランスコードを行わず、入力ファイルを出力ファイルのアップロード先にアップロードします。
output_filename
string non-empty

拡張子を除いた出力ファイル名。以下のプレースホルダーが使用可能です。ULIZA VMS (Cloud) にコンテンツを登録する場合は、%VMS_OUTPUT_FILENAME% を指定します。

  • %INPUT_FILENAME% : 入力ファイル名
    • このプレースホルダーはタスクの登録時に入力ファイル名で置換されます。また、任意の接頭辞または接尾辞と連結することができます。例えば %INPUT_FILENAME%_encoded と指定した場合は、入力ファイル名に接尾辞 _encoded を付与したファイル名で出力されます。ただし、接頭辞と接尾辞を両方含む出力ファイル名を指定することはできません。
  • %OUTPUT_BASENAME% : 任意の文字列 (実行時に毎回指定)
    • この値を指定した場合はタスクの登録時に毎回出力ファイル名を指定する必要があります。また、この値に接頭辞や接尾辞を付与することはできません。
dynamic_streams
boolean

自動的にストリームの数を調整する

object Nullable

DASH 出力に関する設定

object Nullable

HLS 出力に関する設定

object

ポスター画像の出力に関する設定

object

シークプレビュー画像の出力に関する設定

Array of objects

ストリームに関する設定

object Nullable

ULIZA VMS G4 登録に関する設定

object

プロファイルに関する設定

Responses

Response Schema: application/json
id
integer >= 1

登録されたプリセット ID

Request samples

Content type
application/json
{
  • "name": "sample_preset",
  • "description": "My Preset",
  • "destination": "ftp://www.example.com/destination",
  • "destination_settings": {
    },
  • "format": "HLS_ENCRYPTED",
  • "output_filename": "%INPUT_FILENAME%",
  • "dynamic_streams": false,
  • "dash_config": {
    },
  • "hls_config": {
    },
  • "poster": {
    },
  • "seek_preview": {
    },
  • "streams": [
    ],
  • "vms_config": {
    },
  • "profile_config": {
    }
}

Response samples

Content type
application/json
{
  • "id": 28
}

プリセット取得 API

指定したプリセットの情報を取得します。リクエスト送信者が プリセットの取得 権限を持っていない場合は、403 Forbidden が返却されます。

path Parameters
preset-id
required
integer >= 1

取得するプリセット ID

Responses

Response Schema: application/json
id
integer >= 1

プリセット ID

name
string [ 1 .. 30 ] characters ^[0-9a-zA-Z-_]+$

プリセット名

description
string <= 150 characters Nullable

プリセットの説明

destination
string [ 1 .. 150 ] characters

出力ファイルのアップロード先。任意の S3 バケットにアップロードする場合は、destination_settings.s3.authentication_method を指定する必要があります。

  • ULIZA VMS (Cloud) に登録する場合は ulizavms5:// の形式で指定します。
  • ULIZA VMS G4 に登録する場合は ulizavms4://<事業者ID>:<フォルダID> の形式で指定します。
  • 任意の URL にアップロードする場合は、http(s):// または ftp(s):// で始まる URL を指定します。
  • 任意の S3 バケット にアップロードする場合は、s3://<バケット名>/<オブジェクトのキーの接頭辞> の形式で指定します。
object

アップロード先に関する設定

format
string
Enum: "MP4" "HLS" "HLS_ENCRYPTED" "DASH" "DASH_ENCRYPTED" "PASSTHROUGH"

出力フォーマット。 HLS または HLS_ENCRYPTED を指定した場合は hls_config を指定する必要があります。DASH または DASH_ENCRYPTED を指定した場合は dash_config を指定する必要があります。

  • MP4 : MP4
  • HLS : HLS (暗号化なし)
  • HLS_ENCRYPTED : HLS (暗号化あり)
  • DASH : DASH (暗号化なし)
  • DASH_ENCRYPTED : DASH (暗号化あり)
  • PASSTHROUGH : PASSTHROUGH。トランスコードを行わず、入力ファイルを出力ファイルのアップロード先にアップロードします。
output_filename
string non-empty

拡張子を除いた出力ファイル名。以下のプレースホルダーが使用可能です。ULIZA VMS (Cloud) にコンテンツを登録する場合は、%VMS_OUTPUT_FILENAME% を指定します。

  • %INPUT_FILENAME% : 入力ファイル名
    • このプレースホルダーはタスクの登録時に入力ファイル名で置換されます。また、任意の接頭辞または接尾辞と連結することができます。例えば %INPUT_FILENAME%_encoded と指定した場合は、入力ファイル名に接尾辞 _encoded を付与したファイル名で出力されます。ただし、接頭辞と接尾辞を両方含む出力ファイル名を指定することはできません。
  • %OUTPUT_BASENAME% : 任意の文字列 (実行時に毎回指定)
    • この値を指定した場合はタスクの登録時に毎回出力ファイル名を指定する必要があります。また、この値に接頭辞や接尾辞を付与することはできません。
dynamic_streams
boolean

自動的にストリームの数を調整する

object Nullable

DASH 出力に関する設定

object Nullable

HLS 出力に関する設定

object

ポスター画像の出力に関する設定

object

シークプレビュー画像の出力に関する設定

Array of objects

ストリームに関する設定

object Nullable

ULIZA VMS G4 登録に関する設定

created_at
string <yyyy-mm-dd hh:mm:ss>

プリセット登録日時

updated_at
string <yyyy-mm-dd hh:mm:ss>

プリセット更新日時

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/presets/28'

Response samples

Content type
application/json
{
  • "id": 28,
  • "name": "sample_preset",
  • "description": "My Preset",
  • "destination": "ftp://www.example.com/destination",
  • "destination_settings": {
    },
  • "format": "HLS_ENCRYPTED",
  • "output_filename": "%INPUT_FILENAME%",
  • "dynamic_streams": false,
  • "dash_config": {
    },
  • "hls_config": {
    },
  • "poster": {
    },
  • "seek_preview": {
    },
  • "streams": [
    ],
  • "vms_config": {
    },
  • "created_at": "2017-01-01 00:00:00",
  • "updated_at": "2017-01-01 00:00:00"
}

プリセット更新 API

指定したプリセットを更新します。リクエスト送信者が プリセットの更新 権限を持っていない場合は、403 Forbidden が返却されます。

path Parameters
preset-id
required
integer >= 1

更新するプリセット ID

Request Body schema: application/json
name
string [ 1 .. 30 ] characters ^[0-9a-zA-Z-_]+$

プリセット名

description
string <= 150 characters Nullable

プリセットの説明

destination
string [ 1 .. 150 ] characters

出力ファイルのアップロード先。任意の S3 バケットにアップロードする場合は、destination_settings.s3.authentication_method を指定する必要があります。

  • ULIZA VMS (Cloud) に登録する場合は ulizavms5:// の形式で指定します。
  • ULIZA VMS G4 に登録する場合は ulizavms4://<事業者ID>:<フォルダID> の形式で指定します。
  • 任意の URL にアップロードする場合は、http(s):// または ftp(s):// で始まる URL を指定します。
  • 任意の S3 バケット にアップロードする場合は、s3://<バケット名>/<オブジェクトのキーの接頭辞> の形式で指定します。
object

アップロード先に関する設定

format
string
Enum: "MP4" "HLS" "HLS_ENCRYPTED" "DASH" "DASH_ENCRYPTED" "PASSTHROUGH"

出力フォーマット。 HLS または HLS_ENCRYPTED を指定した場合は hls_config を指定する必要があります。DASH または DASH_ENCRYPTED を指定した場合は dash_config を指定する必要があります。

  • MP4 : MP4
  • HLS : HLS (暗号化なし)
  • HLS_ENCRYPTED : HLS (暗号化あり)
  • DASH : DASH (暗号化なし)
  • DASH_ENCRYPTED : DASH (暗号化あり)
  • PASSTHROUGH : PASSTHROUGH。トランスコードを行わず、入力ファイルを出力ファイルのアップロード先にアップロードします。
output_filename
string non-empty

拡張子を除いた出力ファイル名。以下のプレースホルダーが使用可能です。ULIZA VMS (Cloud) にコンテンツを登録する場合は、%VMS_OUTPUT_FILENAME% を指定します。

  • %INPUT_FILENAME% : 入力ファイル名
    • このプレースホルダーはタスクの登録時に入力ファイル名で置換されます。また、任意の接頭辞または接尾辞と連結することができます。例えば %INPUT_FILENAME%_encoded と指定した場合は、入力ファイル名に接尾辞 _encoded を付与したファイル名で出力されます。ただし、接頭辞と接尾辞を両方含む出力ファイル名を指定することはできません。
  • %OUTPUT_BASENAME% : 任意の文字列 (実行時に毎回指定)
    • この値を指定した場合はタスクの登録時に毎回出力ファイル名を指定する必要があります。また、この値に接頭辞や接尾辞を付与することはできません。
dynamic_streams
boolean

自動的にストリームの数を調整する

object Nullable

DASH 出力に関する設定

object Nullable

HLS 出力に関する設定

object

ポスター画像の出力に関する設定

object

シークプレビュー画像の出力に関する設定

Array of objects

ストリームに関する設定

object Nullable

ULIZA VMS G4 登録に関する設定

Responses

Request samples

Content type
application/json
{
  • "name": "sample_preset",
  • "description": "My Preset",
  • "destination": "ftp://www.example.com/destination",
  • "destination_settings": {
    },
  • "format": "HLS_ENCRYPTED",
  • "output_filename": "%INPUT_FILENAME%",
  • "dynamic_streams": false,
  • "dash_config": {
    },
  • "hls_config": {
    },
  • "poster": {
    },
  • "seek_preview": {
    },
  • "streams": [
    ],
  • "vms_config": {
    }
}

Response samples

Content type
application/json
{
  • "code": "REQUEST_UNAUTHORIZED",
  • "message": "Invalid credentials."
}

プリセット削除 API

指定したプリセットを削除します。リクエスト送信者が プリセットの削除 権限を持っていない場合は、403 Forbidden が返却されます。

削除しようとしているプリセットのみを含むプロファイルが存在する場合は、そのプロファイルも同時に削除されます。

path Parameters
preset-id
required
integer >= 1

削除するプリセット ID

Responses

Request samples 

curl \
  -X DELETE \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/presets/28'

Response samples

Content type
application/json
{
  • "code": "REQUEST_UNAUTHORIZED",
  • "message": "Invalid credentials."
}

Profiles

プロファイル管理系 API について以下に記述します。

プロファイル全取得 API

すべてのプロファイルの情報を取得します。リクエスト送信者が プロファイルの取得 権限を持っていない場合は、403 Forbidden が返却されます。

Responses

Response Schema: application/json
Array of objects

プロファイル情報

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/profiles'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

プロファイル登録 API

プロファイルを登録します。リクエスト送信者が プロファイルの登録 権限を持っていない場合は、403 Forbidden が返却されます。

プロファイル登録によってプロファイル登録可能数を超過すると、エラーコード OVER_SERVICE_LIMIT と共に 403 Forbidden が返却され、プロファイル登録に失敗します。この場合は、プロファイルを削除することで再びプロファイル登録を行えるようになります。現在のプロファイル登録可能数はアカウント設定画面の基本情報から確認することができます。

Request Body schema: application/json
name
string [ 1 .. 30 ] characters ^[0-9a-zA-Z-_]+$

プロファイル名

description
string <= 150 characters Nullable

プロファイルの説明

presets
Array of integers

プロファイルに含まれるプリセット ID

share
string
Enum: "not_shared" "shared_subs"

プロファイルの共有状態。サブアカウントではプロファイルを共有できないためこの項目は not_share となります。

  • not_share ： 共有なし
  • shared_subs ： サブアカウントに共有
object

ULIZA VMS (Cloud) へのコンテンツ登録に関する設定。この項目は presets で指定したプリセットに、実行後処理が「ULIZA VMS (Cloud) に登録」であるプリセットが 1 個以上含まれている場合のみ有効かつ必須となります。

Responses

Response Schema: application/json
id
integer >= 1

登録されたプロファイル ID

Request samples

Content type
application/json
{
  • "name": "sample_profile",
  • "description": "My Profile",
  • "presets": [
    ],
  • "share": "not_shared",
  • "vms_config": {
    }
}

Response samples

Content type
application/json
{
  • "id": 18
}

プロファイル取得 API

指定したプロファイルの情報を取得します。リクエスト送信者が プロファイルの取得 権限を持っていない場合は、403 Forbidden が返却されます。

path Parameters
profile-id
required
integer >= 1

取得するプロファイル ID

Responses

Response Schema: application/json
id
integer >= 1

プロファイル ID

name
string [ 1 .. 30 ] characters ^[0-9a-zA-Z-_]+$

プロファイル名

description
string <= 150 characters Nullable

プロファイルの説明

presets
Array of integers

プロファイルに含まれるプリセット ID

share
string
Enum: "not_shared" "shared_subs"

プロファイルの共有状態。サブアカウントではプロファイルを共有できないためこの項目は not_share となります。

  • not_share ： 共有なし
  • shared_subs ： サブアカウントに共有
created_at
string <yyyy-mm-dd hh:mm:ss>

プロファイル登録日時

updated_at
string <yyyy-mm-dd hh:mm:ss>

プロファイル更新日時

object

ULIZA VMS (Cloud) へのコンテンツ登録に関する設定。この項目は presets で指定したプリセットに、実行後処理が「ULIZA VMS (Cloud) に登録」であるプリセットが 1 個以上含まれている場合のみ有効かつ必須となります。

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/profiles/18'

Response samples

Content type
application/json
{
  • "id": 18,
  • "name": "sample_profile",
  • "description": "My Profile",
  • "presets": [
    ],
  • "share": "not_shared",
  • "created_at": "2017-01-01 00:00:00",
  • "updated_at": "2017-01-01 00:00:00",
  • "vms_config": {
    }
}

プロファイル更新 API

指定したプロファイルを更新します。リクエスト送信者が プロファイルの更新 権限を持っていない場合は、403 Forbidden が返却されます。

path Parameters
profile-id
required
integer >= 1

更新するプロファイル ID

Request Body schema: application/json
name
string [ 1 .. 30 ] characters ^[0-9a-zA-Z-_]+$

プロファイル名

description
string <= 150 characters Nullable

プロファイルの説明

presets
Array of integers

プロファイルに含まれるプリセット ID

share
string
Enum: "not_shared" "shared_subs"

プロファイルの共有状態。サブアカウントではプロファイルを共有できないためこの項目は not_share となります。

  • not_share ： 共有なし
  • shared_subs ： サブアカウントに共有
object

ULIZA VMS (Cloud) へのコンテンツ登録に関する設定。この項目は presets で指定したプリセットに、実行後処理が「ULIZA VMS (Cloud) に登録」であるプリセットが 1 個以上含まれている場合のみ有効かつ必須となります。

Responses

Request samples

Content type
application/json
{
  • "name": "sample_profile",
  • "description": "My Profile",
  • "presets": [
    ],
  • "share": "not_shared",
  • "vms_config": {
    }
}

Response samples

Content type
application/json
{
  • "code": "REQUEST_UNAUTHORIZED",
  • "message": "Invalid credentials."
}

プロファイル削除 API

指定したプロファイルを削除します。リクエスト送信者が プロファイルの削除 権限を持っていない場合は、403 Forbidden が返却されます。

プロファイルに含まれるプリセットは削除されません。

path Parameters
profile-id
required
integer >= 1

削除するプロファイル ID

Responses

Request samples 

curl \
  -X DELETE \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/profiles/18'

Response samples

Content type
application/json
{
  • "code": "REQUEST_UNAUTHORIZED",
  • "message": "Invalid credentials."
}

共有プロファイル全取得 API

すべての共有プロファイルの情報を取得します。リクエスト送信者が プロファイルの取得 権限を持っていない場合は、403 Forbidden が返却されます。

他のアカウントから共有されたプロファイルを使用して ULIZA VMS (Cloud) に登録するタスクを登録する場合は、タスク登録 API の vms_config.config_overrides.category_id からカテゴリ ID をオーバーライドする必要があります。また、ULIZA VMS (Cloud) へのコンテンツ登録に関する以下の設定は無視されます。

  • ラベル
  • コンテンツフォワードポリシー（デフォルトポリシーが適用されます）
  • ストリーミングポリシー（デフォルトポリシーが適用されます）
  • 配信ネットワーク（ULIZA VMS (Cloud) により自動的に決定されます）

Responses

Response Schema: application/json
Array of objects

共有プロファイル情報

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/profiles'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Notifications

通知設定系 API について以下に記述します。

通知設定取得 API

通知設定を取得します。リクエスト送信者が タスクの取得 権限を持っていない場合は、403 Forbidden が返却されます。

Responses

Response Schema: application/json
notify_error
boolean

タスクのステータスがエラーになった際に通知

notify_ready
boolean

タスクのステータスが完了になった際に通知

notify_imported_tasks
boolean

CSV インポートジョブによって登録されたタスクの処理がすべて完了した際に通知

updated_at
string <yyyy-mm-dd hh:mm:ss>

通知設定更新日時

Request samples 

curl \
  -H 'Authorization: Bearer {your-token}' \
  'https://encluster-api.p.uliza.jp/v1/notifications'

Response samples

Content type
application/json
{
  • "notify_error": true,
  • "notify_ready": false,
  • "notify_imported_tasks": true,
  • "updated_at": "2017-01-01 00:00:00"
}

通知設定更新 API

通知設定を更新します。リクエスト送信者が タスクの取得 権限を持っていない場合は、403 Forbidden が返却されます。

Request Body schema: application/json
notify_error
boolean

タスクのステータスがエラーになった際に通知

notify_ready
boolean

タスクのステータスが完了になった際に通知

notify_imported_tasks
boolean

CSV インポートジョブによって登録されたタスクの処理がすべて完了した際に通知

Responses

Request samples

Content type
application/json
{
  • "notify_error": true,
  • "notify_ready": false,
  • "notify_imported_tasks": true
}

Response samples

Content type
application/json
{
  • "code": "INVALID_REQUEST",
  • "message": null
}

Error Codes

すべてのエラーレスポンスにはエラーの種類を示すエラーコードが与えられます。返却されうるエラーコードの一覧とそれぞれの意味は下表の通りです。

エラーコード 原因となる操作 意味
CSV_EMPTY_TASKS CSV インポート CSV ファイルにタスクが 1 件も記述されていない
CSV_INVALID_COLUMNS CSV インポート CSV ファイルに必須の列が記述されていない
CSV_TOO_MANY_TASKS CSV インポート CSV ファイルの行数が多すぎる
DISTRIBUTOR_NOT_FOUND プリセットの登録／更新 指定された事業者 ID が登録されていない
EPISODE_NAME_NOT_FOUND タスクの登録 エピソード名が指定されていない
FULL_PROFILE プロファイルの更新 これ以上プロファイルにプリセットを追加できない
HLS_NETWORK_ID_NOT_SPECIFIED プリセットの登録 指定した事業者 ID に HLS 配信ネットワーク ID が指定されていない
INPUT_FILE_NOT_FOUND CSV インポート 指定した入力ファイルが見つからない
INPUT_FILE_NOT_SUPPORTED CSV インポート サポートされない形式の入力ファイルを指定している
INVALID_PRIORITY CSV インポート 優先度が正しく記述されていない
INVALID_REQUEST すべての操作 不正なリクエスト形式
METHOD_NOT_ALLOWED すべての操作 指定されたリクエストメソッドが存在しないか許可されていない
MODEL_ALREADY_EXISTS すべての操作 指定したリソースが既に存在している
MODEL_NOT_FOUND すべての操作 指定したリソースが見つからない
MP4_NETWORK_ID_NOT_SPECIFIED プリセットの登録 指定した事業者 ID に MP4 配信ネットワーク ID が指定されていない
OUTPUT_FILE_NAME_NOT_FOUND CSV インポート 出力ファイル名が記述されていない
OVER_SERVICE_LIMIT すべての操作 サービス利用制限を超過している
POSTER_FILENAME_PREFIX_NOT_FOUND タスクの登録 ポスター画像のファイル名の接頭辞が指定されていない
PRESET_ALREADY_EXISTS プリセットの登録 同名のプリセットが既に存在している
PROFILE_ALREADY_EXISTS プロファイルの登録 同名のプロファイルが既に存在している
PROFILE_NOT_FOUND CSV インポート 指定したプロファイルが見つからない
REQUEST_UNAUTHORIZED すべての操作 認証エラーまたは認可されていないリクエスト
SEEK_PREVIEW_FILENAME_NOT_FOUND タスクの登録 シークプレビュー画像のファイル名が指定されていない
SEGMENT_FILENAME_PREFIX_NOT_FOUND タスクの登録 セグメントファイルのファイル名の接頭辞が指定されていない
UNKNOWN_ERROR すべての操作 サーバ内部エラー