Adding Images to Videos with the Media API

Product
Video Cloud
Applies to Roles
Developer
Version
Brightcove 5
Modules
Media API
Edition
Pro, Enterprise
Created by Grant Goodman.

Video Cloud videos can have thumbnail images and video still images associated with them. Video Cloud provides three different approaches to uploading images and assigning them to videos:

This topic describes how to use the Media API's add_image method to assign thumbnails and video stills to existing videos. You can add new image assets (by uploading a file or supplying a remote-asset URL) or you can assign existing image assets to more videos (and optionally update those existing assets). The add_image method returns the Image object that was added to the video (regardless of whether you were creating a new asset, updating an existing one, or just using an existing one without updating it).

For information about creating thumbnail images and video still images, see Using other software to create thumbnails and video stills.

The add_image method

The Media API Reference describes all the parameters used with the add_image method. The Media API Objects Reference describes all the properties of the Image object that is created or updated, and returned, by the add_image method. This method has the following signature:

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

This is a write method, so use the Media API write token for your account.

Note the following aspects of the behavior of the add_image method:

  • Certain parameters are conditionally required:
    • If you are creating a new image asset, you must provide either a file (with maxsize and filename) or a remoteUrl (as a property on the Image).
    • If you are not creating a new asset, you must provide either the id or the reference_id of an existing image asset (as a property on the Image).
    • You must provide either the video_id or the video_reference_id of the video you want to add the image to (and the video must exist).
  • The resize property defaults to true. If you pass "resize" : true, your assets will be resized to the default size for its type (THUMBNAIL or VIDEO_STILL). If you pass "resize" : false, then your image will never be resized, even if it is not an appropriate size for standard Video Cloud players.

Adding remote images

The standard way to create image assets is to upload them the Video Cloud servers. If your account is enabled for remote assets, you can instead keep your image asset on your own server and use the remoteUrl property of the Image to tell Video Cloud where to find the image. For more information about remote assets, see Creating Videos with Remote Video Files.

add_image examples

Here are several examples that demonstrate how to use the add_image method:

In addition, see this complete example using JavaScript.

Uploading and assigning a new thumbnail image

This example assumes that you are uploading an image file using a multipart/form-data POST. The file_checksum is optional; if it is supplied and the checksum of the uploaded file doesn't match, you will get a 308 NonmatchingChecksumError. If the uploaded file is not a JPEG, GIF, or PNG file, you will get a 306 FileFormatError. The video_id property indicates that we want to assign the new thumbnail to the video with 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
    }
}

After you submit the JSON in this example, the add_image method returns the following:

 
{"result": {"displayName":"Wicklow the Bunny","id":30300017070001,
            "referenceId":"wicklow-1","remoteUrl":null,"type":"THUMBNAIL"},
 "error": null, "id": null}

Creating a new video still image with a remote asset

In this case we're supplying a remoteUrl, so we don't have to upload a file. If you try to create a remote asset and that feature is not enabled for your account, you will get a 309 RemoteAssetsDisabledError. For more information about remote assets, see Creating Videos with Remote Video Files.

{
    "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"
    }
}

Updating an existing image asset

In this example, we supply the referenceId of an image asset that already exists and update the existing asset with the file at the new remoteUrl. The type is not required in this case because we already know the type of the asset. In fact, even if we had supplied a type, and changed it to THUMBNAIL, this would have no effect as you can't change the type of an existing asset.

We could also have supplied the Video Cloud id of the asset instead of the referenceId.

Note that we still have to supply a video_id or video_reference_id for the video that this asset is assigned to. This is always required. In this case we don't want to assign the asset to any other video, so we just supply the referenceId of the video that already uses this asset.

{
    "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"
    }
}

Assigning an existing asset to a different video

In this example, we assign the existing VIDEO_STILL to a different video. This does not remove the asset from any other videos that already use it. The video still is now used by two different videos.

{
    "method" : "add_image",
    "params" : {
        "token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
        "image" : {
            "referenceId" : "still-1"
        },
        "video_reference_id" : "video-3"
    }
}
Tags
images, stills, thumbnails