Merci de votre visite. Cette page est disponible en anglais uniquement.

API Reference Overview (VSK MM)

Video skill directives are sent from Alexa to your Lambda function. Directives are JSON messages that contain instructions about performing a specific action, like getting metadata for a video. There are various directives with different names and payloads. Your Lambda function must handle the incoming directives and return a response that conforms with the expected JSON. Overall, the basic model is a request (in JSON) sent from Alexa (the request is called a directive) and a response (also in JSON) sent by your Lambda. JSON in, JSON out.

Supported Utterances on Multimodal Devices

As described in the Introduction, multimodal devices support the following utterances:

Search

Users can search using criteria like VideoName, ActorName, GenreName, etc., by querying the content providers for content to display. Potential utterances include:

  • "Search for movies with Tom Hanks."
  • "Find 'The Big Bang Theory.'"
  • "Find 'The Big Bang Theory' Season 1 episode 4."
  • "Search for Interstellar."
  • "Search for comedy movies."
  • "Search comedy movies with Tom Hanks."
  • "Suche Filme mit Tom Hanks."
  • "Finde The Big Bang Theory."
  • "Finde The Big Bang Theory Staffel 1 Folge 4."
  • "Suche Interstellar."
  • "Suche Filmkomödien."
  • "Suche Filmkomödien mit Tom Hanks."
  • "Recherche des films avec Tom Hanks."
  • "Trouve The Big Bang Theory."
  • "Trouve The Big Bang Theory, saison 1, épisode 4."
  • "Recherche Insterstellar."
  • "Recherche des comédies."
  • "Recherche des comédies avec Tom Hanks."
  • "Cerca film con Tom Hanks."
  • "Cerca The Big Band Theory."
  • "Cerca The Big Band Theory stagione 1 episodio 4."
  • "Cerca Interstellar."
  • "Cerca commedie."
  • "Cerca commedie con Tom Hanks."
  • "Busca películas de Tom Hanks."
  • "Busca The Big Bang Theory."
  • "Busca el episodio 4 de la temporada 1 de The Big Bang Theory."
  • "Busca Interstellar."
  • "Busca películas de comedia."
  • "Busca comedias con Tom Hanks."
  • "Busca películas de Tom Hanks."
  • "Busca The Big Bang Theory."
  • "Busca el episodio 4 de la temporada 1 de The Big Bang Theory."
  • "Busca Interstellar."
  • "Busca películas de comedia."
  • "Busca comedias con Tom Hanks."
  • "トム・ハンクスの映画を検索して."
  • "「ビッグバン・セオリー」を探して."
  • "「ビッグバン・セオリー」のシーズン1のエピソード4を探して."
  • "「インターステラー」を検索して."
  • "コメディー映画を検索して."
  • "トム・ハンクスのコメディー映画を検索して."
  • "Procure filmes com Tom Hanks."
  • "Procure por The Big Bang Theory."
  • "Procure pelo quarto episódio da primeira temporada de The Big Bang Theory."
  • "Procure por Interstellar."
  • "Procure por filmes de comédia."
  • "Procure por filmes de comédia com Tom Hanks."
  • "Tom Hanks की फ़ि‍ल्में सर्च करो."
  • "'The Big Bang Theory' ढूंढो."
  • "'The Big Bang Theory' सीज़न 1 एपिसोड 4 ढूंढो."
  • "Interstellar सर्च करो."
  • "कॉमेडी मूवीज़ सर्च करो."
  • "Tom Hanks की कॉमेडी मूवीज़ सर्च करो."

Browse

Users can browse a watch list, video library, recordings, etc., on the device. Potential utterances include:

  • "Show me my video library."
  • "Show me my watch list."
  • "Show me my recordings."
  • "Zeig meine Videothek an."
  • "Zeig meine Watchlist an."
  • "Zeig meine Aufzeichnungen an."
  • "Montre-moi ma bibliothèque vidéo."
  • "Montre-moi ma liste de favoris."
  • "Montre-moi mes enregistrements."
  • "Mostrami la mia libreria video."
  • "Mostrami la mia watch list."
  • "Mostrami le mie registrazioni."
  • "Muéstrame mi biblioteca de vídeo."
  • "Enséñame la lista de seguimiento."
  • "Enséñame mis grabaciones."
  • "Muéstrame mi biblioteca de vídeo."
  • "Enséñame la lista de seguimiento."
  • "Enséñame mis grabaciones."
  • "ビデオライブラリを見せて."
  • "ウォッチリストを見せて."
  • "録画したビデオを見せて."
  • "Mostre-me a minha biblioteca de vídeo."
  • "Mostre-me a minha lista de itens a assistir."
  • "Mostre-me as minhas gravações."
  • "मुझे मेरी वीडियो लाइब्रेरी दिखाओ."
  • "मुझे मेरी वॉचलिस्ट दिखाओ."
  • "मुझे मेरी रिकॉर्डिंग्स दिखाओ."

Pagination

Users can go to the next page of search results, or scroll beyond the viewable search results on the screen. Sample utterances:

  • "Next page"

Quick Play

Users can search for movies, TV shows, recording, etc., using criteria such as VideoName, ActorName, or GenreName by querying content providers for the content to play on the device. Then, they can go directly into playback of that content (instead of showing search results, etc.). Potential utterances include:

  • "Play a movie with Tom Hanks."
  • "Play Interstellar." 
  • "Play a comedy movie."
  • "Play 'The Big Bang Theory'."
  • "Play 'The Big Bang Theory' Season 1, episode 6."
  • "Play a movie." 
  • "Spiel einen Film mit Tom Hanks."
  • "Spiel Interstellar."
  • "Spiel eine Filmkomödie."
  • "Spiel The Big Bang Theory."
  • "Spiel The Big Bang Theory Staffel 1 Folge 6."
  • "Spiel einen Film."
  • "Mets un film avec Tom Hanks."
  • "Mets Interstellar."
  • "Mets une comédie."
  • "Mets The Big Bang Theory."
  • "Mets The Big Bang Theory, saison 1, épisode 6."
  • "Mets un film."
  • "Riproduci un film con Tom Hanks."
  • "Riproduci Interstellar."
  • "Riproduci una commedia."
  • "Riproduci The Big Band Theory."
  • "Riproduci The Big Band Theory stagione 1 episodio 6."
  • "Riproduci un film."
  • "Pon una película de Tom Hanks."
  • "Pon Interstellar."
  • "Pon una película de comedia."
  • "Pon The Big Bang Theory."
  • "Pon el episodio 6 de la temporada 1 de The Big Bang Theory."
  • "Pon una película."
  • "Pon una película de Tom Hanks."
  • "Pon Interstellar."
  • "Pon una película de comedia."
  • "Pon The Big Bang Theory."
  • "Pon el episodio 6 de la temporada 1 de The Big Bang Theory."
  • "Pon una película."
  • "トム・ハンクスの映画を再生して."
  • "「インターステラー」を再生して."
  • "コメディー映画を再生して."
  • "「ビッグバン・セオリー」を再生して."
  • "「ビッグバン・セオリー」のシーズン1のエピソード6を再生して."
  • "映画を再生して."
  • "Coloque um filme com Tom Hanks."
  • "Coloque Interstellar."
  • "Coloque um filme de comédia.
  • "Coloque The Big Bang Theory."
  • "Coloque o sexto episódio da primeira temporada de The Big Bang Theory."
  • "Coloque um filme."
  • "Tom Hanks की मूवी चलाओ."
  • "Interstellar चलाओ."
  • "कॉमेडी मूवी चलाओ."
  • "'The Big Bang Theory' चलाओ."
  • "'The Big Bang Theory' सीज़न 1, एपिसोड 6 चलाओ."
  • "एक मूवी चलाओ."

Channel Navigation

users can play a live stream or recording of a channel for the user. Potential utterances include:

  • "Tune to CNN."
  • "Tune to ESPN."
  • "Gehe zu CNN."
  • "Gehe zu ESPN."
  • "Mets CNN."
  • "Mets ESPN."
  • "Metti RAI 1."
  • "Metti RAI Sport."
  • "Pon Televisión Española."
  • "Pon Antena 3."
  • "Pon Televisa."
  • "Pon TV Azteca."
  • "CNNをつけて."
  • "ESPNをつけて."
  • "Coloque na CNN."
  • "Coloque na ESPN."
  • "CNN पर ट्यून करो."
  • "ESPN पर ट्यून करो."

Play from Search Results

Users can play a video from the search results shown on the device. The user can play using voice or simply by tapping on an item on the screen. Potential utterances include:

  • "Play number 1."
  • "Play the second one."
  • "Select number 1."
  • "Select the second one."
  • "Spiel Nummer 1."
  • "Spiel den zweiten."
  • "Wähle Nummer 1."
  • "Wähle den zweiten."
  • "Mets le numéro 1."
  • "Mets le deuxième."
  • "Sélectionne le numéro 1."
  • "Sélectionne le second."
  • "Riproduci il numero 1."
  • "Riproduci il secondo."
  • "Seleziona il numero 1."
  • "Seleziona il secondo."
  • "Pon el número 1."
  • "Pon el segundo."
  • "Selecciona el número 1."
  • "Selecciona el segundo."
  • "Pon el número 1."
  • "Pon el segundo."
  • "Selecciona el número 1."
  • "Selecciona el segundo."
  • "1番を再生して."
  • "2番目のを再生して."
  • "1番を再生して選択."
  • "2番目のを選択."
  • "Coloque no número 1."
  • "Coloque no segundo."
  • "Selecione o número 1."
  • "Selecione o segundo."
  • "नंबर 1 चलाओ."
  • "दूसरा चलाओ."
  • "नंबर 1 चुनो."
  • "दूसरा चुनो."

Recommendations

Users can search for recommendations by explicitly asking for them. Potential utterances include:

  • "Show me recommended movies"
  • "Open Amazon Video"
  • "Zeig mir Filmempfehlungen"
  • "Öffne Amazon Video"
  • "Montre-moi des films recommandés."
  • "Ouvre Amazon Video."
  • "Mostrami il film consigliati."
  • "Apri Prime Video."
  • "Enséñame películas recomendadas."
  • "Abre Prime Video."
  • "Enséñame películas recomendadas."
  • "Abre Prime Video."
  • "おすすめの映画を見せて."
  • "Amazon Videoを開いて."
  • "Mostre-me recomendações de filmes."
  • "Abra o Amazon Video."
  • "मुझे सुझाई गई फ़ि‍ल्में दिखाओ."
  • "Amazon वीडियो खोलो."

The utterance "Open Amazon Video" translates to searching for recommendations.

Landing Page

Users can go to a landing page for your content (analogous to an app home screen). Alexa provides a landing page template that gets populated by your response. Potential utterances include:

  • "Open your app name."
  • "Öffne App-Name"
  • "Ouvre ton application."
  • "Apri your app name"
  • "Abre your app name."
  • "Abre your app name."
  • "<your app name>を開いて."
  • "Abra o seu aplicativo app name."
  • "अपना ऐप नाम खोलो."

Directives Alexa Sends

When users say any of above utterances, Alexa converts these utterances into directives that it sends to your Lambda function. Utterances that users say for browse, search, channel change, quick play, recommendations, etc., might use similar directives (populated in different ways).

Despite the variety of utterances and scenarios, there are only a handful of directives that your Lambda must respond to. As such, when you code your Lambda for a multimodal device, focus on handling the six directives listed in the following table.

Directives Description
GetPlayableItems Alexa sends this directive when the user requests to play a video on the device. You can search content based on the criteria in the directive and return entity ID for the video corresponding to the request. Your Lambda's response should favor videos that the user is entitled to play through their subscription (if applicable). If there are no videos for that request, then an appropriate error response code should be returned. 
GetPlayableItems (Channel Navigation) Alexa sends this directive when the user requests to go to a specific channel. When the view changes to the channel, content from the channel begins playing. 
GetPlayableItemsMetadata Alexa sends this directive to obtain additional metadata for results you previously returned through GetPlayableItems for a set of entity IDs. The metadata contains information required for playing the video as well as to render an appropriate prompt to the user. 
GetDisplayableItems Alexa sends this directive when the user requests to search videos and view results on the device. You can search content based on the criteria in the directive and return entity IDs for the videos corresponding to the search request. If there is no content found for the request, then an appropriate error response should be returned.
GetDisplayableItemsMetadata Alexa sends this directive to obtain additional metadata for results you previously returned via GetDisplayableItems for a set of entity IDs. The metadata contains information required by Alexa to display the entity IDs as search results on the device. 
GetBrowseNodeItems Alexa sends this directive to get grouped content in search results. Search results on multimodal devices can be merged into browse nodes with multiple layers. Users can choose to drill down on those grouped result items by clicking on them to see more results under that grouping. Your Lambda's response to a GetBrowseNodeItems directive should return items that are part of the specified group in the request.
GetNextPage Alexa sends this directive when the user tries to view more results on the screen by scrolling than are currently displayed on the screen. This directive is called to dynamically fetch more results to show on the screen, once the metadata for those results has been fetched. 

Expected Lambda Responses

When Alexa sends one of the directives (a JSON message) described above to your Lambda, your Lambda must respond with a JSON message that provides the needed info (usually content IDs) and which conforms to the expected response fields and schema. The following diagrams show the Alexa directives and expected Lambda responses.

GetPlayableItems Directive and Lambda GetPlayableItemsResponse
GetPlayableItemsMetadataItems Directive and Lambda GetPlayableItemsMetadataResponse
GetDisplayableItems Directive and Lambda GetDisplayableItemsResponse
GetDisplayableItemsMetadata Directive and Lambda GetDisplayableItemsMetadataResponse
GetBrowseNodeItems Directive and Lambda GetBrowseNodeItemsResponse
GetNextPage Directive and Lambda GetNextPageResponse

Comparison with Fire TV Directives

Implementing the Video Skills Kit for Fire TV also involves interpreting and responding to directives from Alexa, as described in Directives and Responses (VSK FTV). The directives aren't the same as those used for multimodal devices, but they are similar:

However, note that multimodal devices have two directives that are made for each play and search utterance type (GetPlayableItems and GetPlayableItemsMetadata, and GetDisplayableItems and GetDisplayableItemsMetadata), because the fundamental interaction model is different. With multimodal devices, your Lambda feeds the information back to Alexa in the response. With Fire TV apps, your Lambda pushes the needed information directly to your app through Amazon Device Messaging.

Terminology – Requests versus Directives

The term "request" and "directive" are mostly synonymous in the video skills documentation here. Request is a more general term for any message Alexa sends to your Lambda. With video skills, the messages are labeled as a directive, in the code so we refer to the requests as "directives." This aligns with terminology used in other Alexa Skills Kit documentation.

Additionally, the term "directive" provides some differentiation between the user's utterance (e.g., a request to play a movie) and the information that Alexa sends to your Lambda.