Replacing an Asset

Content replacement enables you to replace old content with new content. For example, you might have a video with technical issues or you might need to change your logo on multiple videos.

Note: For more information about Backlot REST API commands, see the Backlot API Reference.

If the old asset and new asset are nearly identical, replacing content can save you time over deleting the old asset and uploading its replacement—you do not need to update labels, syndication settings, publishing rules, and so on. However, replacing content can affect analytics. For example, if you replace a 5 minute video with a 15 minute video, the average time watched becomes less meaningful and your engagement report will be inaccurate. Content replacement does not create a new movie profile. Instead, the system transcodes a new video file and links it to already existing asset the with same embed code.

Note:

Content replacement is intended primarily for use with video assets. If you want to replace content for remote assets or live streams, simply change their settings.

If you are using the default preview images, they are automatically replaced. If you are using a custom preview image (uploaded or via remote URL), it continues to be associated with the new asset.

To replace content:

  1. Use POST with the /v2/assets route, the asset ID, the /replacement qualifier, with properties in the body of the request. The following example replaces the content of the the Y1dTdvMjq9QtOMGrP-H59OIgiZ6-_Mrl asset.
    Note:
    • To upload the entire file at once, do not specify a chunk_size.
    • For VR 360 videos, be sure to add the vr360type parameter. See Uploading VR 360 Content for details.
    [POST]/v2/assets/Y1dTdvMjq9QtOMGrP-H59OIgiZ6-_Mrl/replacement{
       "file_size": 199895,
       "chunk_size": 100000
    }

    Backlot returns a response similar to the following.

    {
       "asset_type": "video",
       "duration": 0,
       "name": "My Video",
       "preview_image_url": null,
       "created_at": "2011-07-22T18:54:19+00:00",
       "embed_code": "Y1dTdvMjq9QtOMGrP-H59OIgiZ6-_Mrl",
       "time_restrictions": null,
       "updated_at": "2011-07-22T18:54:19+00:00",
       "external_id": null,
       "description": null,
       "status": "uploading"
    }
    Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.
  2. Retrieve the URLs for uploading your file with GET to the /v2/assets route, the asset ID, the /replacement qualifier, and the /uploading_urls qualifier.
    [GET]/v2/assets/Y1dTdvMjq9QtOMGrP-H59OIgiZ6-_Mrl/replacement/uploading_urls
    The URLs are returned in the response body.
  3. Upload each chunk.
    Note: If you didn't specify a chunk_size, do not specify a chunk range.
    The following example uploads the first chunk of the Y1dTdvMjq9QtOMGrP-H59OIgiZ6-_Mrl asset.
    [PUT] https://uploader-v2.ooyala.com/send?filename=Y1dTdvMjq9QtOMGrP-H59OIgiZ6-_Mrl/0000000000000-0000000099999
    &filesize=100000
    &expires=1311447448
    &signature=tUp+iEUq9O9oP6khuasvZVFecoECcoej0gycG/ZTZr0
    <file>
  4. Mark the status of the replacement asset as uploaded with the /replacement/upload_status qualifiers.
    [PUT]/v2/assets/Y1dTdvMjq9QtOMGrP-H59OIgiZ6-_Mrl/replacement/upload_status{
       "status": "uploaded"
    }

The asset is marked as uploaded. Once processed, it replaces the current asset and its status becomes live.

Cancellation

You can cancel a content replacement request as long as the replacement request has not yet completed (you must cancel before the status of the replacement asset is live) using the following API:
url:  "/assets/:id/replacement"
body: {"status":"canceled"}
type: PATCH
The following table describes the conditions when canceling content replacement is allowed:
Replacement Asset Status Description Cancelation allowed (Yes/No)? Notes
uploading Content replacement has been initated but the replacement content is not yet fully uploaded. Yes If content replacement is canceled at this stage, then Backlot will not move the asset into transcoding.
uploaded The replacement content has been completely uploaded. Yes The uploaded asset is ready for transcoding. However, if content replacement is canceled at this stage, then Backlot will not move the asset into transcoding.
in-progress Transcoding is in-progress. Yes Content replacement can still be cancelled, but the transcoding process will not be canceled.
live Content replacement has completed. No Cancelation is not allowed. Attempting to cancel content replacement returns a 400 response with the message "Content Replacement is already completed."

Was this article helpful?