Update Video ANS Programmatically

You can create videos in Arc XP programmatically by sending video ANS to Video Center API or to Migration Center API. You can use the same API endpoints to edit the non-binary metadata of a video, change video circulations, change the image for the promo item, or add a new video binary file to the video object.

To perform any of these changes, you must edit the video’s ANS and then POST the full ANS object to the same API URL that you use to import a new video. If the edits involve a change to the video’s canonical URL, you must use a second POST to another endpoint to cause a new URL to be associated with the video, described below.

Fetch the video’s ANS from either Content API or Video Center API and make the changes to the fields you need. We recommend removing certain keys from the ANS as well, and then POST the entire modified ANS back to the Video Center API /import/ans endpoint or the Migration Center API.

Changing a Video’s Circulations

To change a video’s circulations, you must rewrite the taxonomy.primary_section, taxonomy.sections, and websites.{site id} keys in the video ANS. Other keys contain duplicate circulation data in the ANS that Content API or Video Center API returns for backwards compatibility; however, the system automatically populates those keys.

We recommend including only the taxonomy.primary_section, taxonomy.sections, and websites.{site id} circulation keys in video ANS that you send into the system for a create or update request.

Refer to the explanation about how these keys create a video’s circulations in How to write the minimum ANS for a viable video document.

If changing the video circulation includes a change to the video’s canonical URL, you must send a request to the Video Center API /goldfish/video/v2/url/update endpoint after you update the video ANS. This endpoint invokes the Canonical URL service and generates a new URL or associates the URL added in the websites.{site id}.website_url field, according to the URL format rules.

Changing a Video’s Promotional Item

Content API returns two ANS keys with promotional image data; however, when creating or updating a video, only the promo_items.basic key is valid. The promo_image key contains duplicate promotional image data, for backwards compatibility.

You can update promo_items.basic to create a new promotional image or to update an existing promotional image. You cannot remove a promotional image completely from the video, leaving it empty. After it’s set, a promotional image always returns in video ANS. Similarly, you cannot set the promotional image to an image that has already been created in Photo Center.

Refer to the explanation about how promo_items.basic creates a video’s promotional image in How to write the minimum ANS for a viable video document.

Adding a new video binary

To replace a video, you can send a new binary file through the streams key. This action adds a new video version and sets that version as the active video version, moving the previous binary down in a list of versions that is visible in the Video Center application.

When you request the video ANS from Content API, the active version is the information that is populated in the streams key in the ANS. Inactive versions aren’t represented in the video ANS at all. However, in the Video Center application, a Versions tab lists all the video binary files associated with the video object. You can switch between these versions in the Video Center application. The version you select in the application is the version that appears in the ANS streams key.

A warning about the streams key

Unless you specifically want to create a new binary file version, we recommend removing the streams key from the video ANS during an ANS update. Leaving the streams key while performing an update to an existing video record can lead to unintentional billing costs or a corrupted streams data.

When a video object has multiple video binary files associated to it, the additional video versions affect the Arc XP binary file storage calculations and add to your per-cycle storage billing costs. When you add a new video version and set the Video API ?encode=true query parameter or Migration Center arcAdditionalProperties.video.encode: true property, the newly imported binary runs through the encode and transcode process, which adds another transcoding billing event. Do not allow unnecessary scripted processes to send the same binary file through an API request and create duplicate versions and cause duplicate transcoding processes.

Additionally, if the same video binary is added to the same video multiple times—either through inattention or accident—creating many versions and transcoded copies of the same file, then the streams data could become unpredictably corrupted, requiring a support ticket to resolve.

Editing video metadata

Remove the streams key from the ANS when making updates other than creating a new video version. The existing imported video is not affected when you send video ANS updates without the streams key. You can avoid unintended transcoding, duplicate versions, and the costs associated with transcoding and video storage by leaving off the streams key. Therefore, it’s best practice to format the ANS for a video update and leave off the streams key unless necessary as metadata updates process faster and more cleanly.

Other keys exist in the video ANS that you cannot update because the system automatically generates their values. You can remove these fields from the updated ANS so as to be intentional about what data you are passing and reduce uncertainty. However, if these keys remain in the ANS that is sent to an update, they are ignored.

ANS Keys To Remove When Updating A Video

streams	Unless intentionally updating to add a new video binary version, remove this key from the ANS.
promo_image	This key is set to the same value as promo_items.basic
taxonomy.primary_site taxonomy.sites	Arc XP sets these keys to be the same values as taxonomy.primary_section and taxonomy.sections
canonical_url	Arc XP sets this key to the URL that the Canonical URL Service creates
created_date last_updated_date first_publish_date	The system automatically generates the values for these keys
embed_html	The system automatically generates the HTML code in this key
duration	The system automatically sets the value for this key the first time a video binary is created
tracking	The system automatically sets this key’s value