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, take the following steps:

1. Fetch the video’s ANS from either Content API or Video Center API.
2. Edit the video’s ANS according to the sections on this page.
3. Remove unnecessary ANS keys. See ANS keys to remove when updating a video
4. POST the full ANS object to the /import/ans endpoint of the Video Center API.

Changing a video’s circulations

To change a video’s circulations, you must rewrite the following keys in the video ANS:

• taxonomy.primary_section
• taxonomy.sections
• websites.{site id}

Tip

See How to write the minimum ANS for a viable video document for more information about the ANS keys that create a video’s circulations.

Note

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 to 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, only the promo_items.basic key is valid when creating or updating a video. The promo_image key contains duplicate promotional image data for backward compatibility.

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

See How to write the minimum ANS for a viable video document for more information about the promo_items.basic ANS key.

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 visible in the Video Center application.

When you request the video ANS from the 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.

warning

Warning about the streams key

Unless you 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 updating 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 with 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. This creates duplicate versions and causes 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 stream 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 of transcoding and video storage by leaving off the streams key. Therefore, it is 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 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