Brightcove の動画に、サムネイル画像や動画静止画像を割り当てることができます。画像をアップロードして動画に割り当てるために、Brightcove には次の 3 種類の方法があります。
add_image メソッドこのトピックでは、Media API の add_image メソッドを使用して、サムネイルや動画静止画を既存の動画に割り当てる方法について説明します。新しい画像アセットを追加すること（ファイルをアップロードするか、リモート アセットの URL を入力）や、既存の画像アセットを他の動画にも割り当てることができます（任意で、既存の画像アセットを更新することもできます）。add_image メソッドは、動画に追加された Image オブジェクトを返します（新しい画像アセットを作成した場合、既存の画像アセットを更新した場合、既存の画像アセットを更新せずに使用した場合、いずれも同様）。
サムネイル画像や動画静止画像の作成について、詳細は他のソフトウェアを使用してサムネイル画像と静止画像を作成するを参照してください。
add_image メソッドMedia API リファレンスに、add_image メソッドで使用されている全パラメータの説明があります。Media API オブジェクト リファレンスには、add_image によって作成または更新され、返される Image オブジェクトの全プロパティの説明があります。このメソッドのシグネチャは以下のとおりです。
add_image(token:String, image:Image, filename:String, maxSize:Long, file:InputStream, file_checksum:String, video_id:Long, video_reference_id:String, resize:Boolean):Image
書き込みメソッドなので、お持ちのアカウントの Media API 書き込みトークンを使用してください。
add_image メソッドの動作について、以下の点に注意してください。
file（maxsize と filename を設定）または remoteUrl（Image のプロパティとして）を指定する必要があります。id か reference_id を指定する必要があります（Image のプロパティとして）。video_id または video_reference_id を指定する必要があります（また、動画が存在する必要があります）。resize プロパティのデフォルトは true です。"resize" : true を渡すと、画像アセットはタイプ（THUMBNAIL または VIDEO_STILL）に応じてデフォルト サイズにリサイズされます。"resize" : false を渡すと、画像のサイズが標準 Brightcove プレーヤに合っていなくても、リサイズはされません。画像アセットを作成する標準的な方法は、画像を Brightcove サーバーへアップロードすることです。アカウントでリモート アセットを有効にしている場合は、画像アセットを自社のサーバー上に置き、Image の remoteUrl プロパティを使用して画像の場所を指定することもできます。リモート アセットついて詳細は、リモート動画ファイルで動画を作成するを参照してください。
add_image例add_image メソッドの使用方法の具体例をいくつか示します。
また、JavaScript による完全な例も参照してください。
この例では、multipart/form-data の POST で画像ファイルをアップロードすることを前提としています。file_checksum はオプションです。このチェックサムが指定され、アップロードされたファイルのチェックサムと一致しない場合は、308 NonmatchingChecksumError になります。アップロードされたファイルが JPEG、GIF、PNG のいずれでもない場合は、306 FileFormatError になります。この例の video_id プロパティは、id が 17035 の動画に新しいサムネイルを割り当てようとしていることを示しています。
{
"method" :"add_image",
"params" : {
"token" :"riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
"image" : {
"referenceId" :"wicklow-1",
"displayName" :"Wicklow the Bunny",
"type" :"THUMBNAIL"
},
"file_checksum" :"d1c9c2b112993a0079a0128ecb9b36dd",
"video_id" : 17035
}
}
上記の例の JSON を送信すると、add_image メソッドから次の内容が返されます。
{"result":{"displayName":"Wicklow the Bunny","id":30300017070001,
"referenceId":"wicklow-1","remoteUrl":null,"type":"THUMBNAIL"},
"error":null, "id":null}
この例では remoteUrl を指定しているので、ファイルをアップロードする必要はありません。リモート アセットを作成しようとしたときに、この機能がアカウントで有効になっていなければ、309 RemoteAssetsDisabledError になります。リモート アセットついて詳細は、リモート動画ファイルで動画を作成するを参照してください。
{
"method" :"add_image",
"params" : {
"token" :"riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
"image" : {
"referenceId" :"still-1",
"displayName" :"first remote still",
"type" :"VIDEO_STILL",
"remoteUrl" :"http://www.example.com/images/still1.jpg"
},
"video_reference_id" :"video-2"
}
}
この例では、既存の画像アセットの referenceId を指定し、新しい remoteUrl のファイルで既存の画像アセットを更新します。この場合、アセットのタイプは既にわかっているので、type は不要です。実際のところ、type を指定して THUMBNAIL に変えたとしても、既存の画像アセットの type を変えることはできないので、何の影響もありません。
また、画像アセットの referenceId. の代わりに、Brightcove の id を指定することもできます。
ただし、この画像アセットを割り当てる動画の video_id または video_reference_id は指定する必要があります。これは常に必須です。このケースでは、画像アセットを他の動画に割り当てないので、すでにこの画像アセットを使用している動画の referenceId を指定します。
{
"method" :"add_image",
"params" : {
"token" :"riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
"image" : {
"referenceId" :"still-1",
"remoteUrl" :"http://www.example.com/public/images/still1.jpg"
},
"video_reference_id" :"video-2"
}
}
この例では、既存の VIDEO_STILL を別の動画に割り当てます。これによって、この VIDEO_STILL を使用している既存の他の動画から、画像アセットが削除されることはありません。この動画静止画は、2 本の動画で使用されるようになります。
{
"method" :"add_image",
"params" : {
"token" :"riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
"image" : {
"referenceId" :"still-1"
},
"video_reference_id" :"video-3"
}
}