To enable the Video Stitcher API for your project, please reach out to your Account Representative or contact Sales to learn more.

Create a live session

Using the Video Stitcher API, you create a live session each time you start playback of a live stream in which ads served by Google Ad Manager are dynamically stitched during ad breaks. The response specifies the playback URL and the configuration of the live session.

This document describes how to create and manage a live session. For more details, see the REST documentation .

Before you begin

Create a live config . For the integration with Google Ad Manager, ensure that the gamLiveConfig object is set.
If you are specifying a slate, ensure that the gamSlate object is set on the slate you register.

Create a live session

To create a live session using the API directly, use the projects.locations.liveSessions.create method.

The liveConfig field is the only required field in the JSON body. You can set or override the following optional parameters per live session (as shown in the following REST example):

manifestOptions : specifies which video renditions are generated in the stitched video manifest and the ordering of the renditions; see the manifest options documentation
adTracking : select either client-side ad tracking or server-side ad tracking; this overrides the value in the live config for the session
targetingParameters : a Google Ad Manager ad tag can contain targeting parameters that can be updated per session; provide a mapping in this field (for example, to replace the [my_key] macro with the string my_value , see the REST example)

REST

Before using any of the request data, make the following replacements:

PROJECT_NUMBER : your Google Cloud project number located in the Project number field on the IAM Settings page
LOCATION : the location in which to create your session; use one of the supported regions
Show locations
- us-central1
- us-east1
- us-west1
- asia-east1
- asia-south1
- asia-southeast1
- europe-west1
- southamerica-east1
LIVE_CONFIG_ID : the user-defined identifier for the live config

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell , which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list .

Save the request body in a file named request.json . Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "liveConfig": "projects/ PROJECT_NUMBER 
/locations/ LOCATION 
/liveConfigs/ LIVE_CONFIG_ID 
",
  "manifestOptions": {
    "includeRenditions": [
      {
        "bitrateBps": 150000,
        "codecs": "hvc1.1.4.L126.B0"
      },
      {
        "bitrateBps": 440000,
        "codecs": "hvc1.1.4.L126.B0"
      }
    ],
    "bitrateOrder": "DESCENDING"
  },
  "adTracking": "SERVER",
  "gamSettings": {
    "targetingParameters": {
      "my_key": "my_value",
    },
  }
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://videostitcher.googleapis.com/v1/projects/ PROJECT_NUMBER 
/locations/ LOCATION 
/liveSessions"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list .

Save the request body in a file named request.json . Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "liveConfig": "projects/ PROJECT_NUMBER 
/locations/ LOCATION 
/liveConfigs/ LIVE_CONFIG_ID 
",
  "manifestOptions": {
    "includeRenditions": [
      {
        "bitrateBps": 150000,
        "codecs": "hvc1.1.4.L126.B0"
      },
      {
        "bitrateBps": 440000,
        "codecs": "hvc1.1.4.L126.B0"
      }
    ],
    "bitrateOrder": "DESCENDING"
  },
  "adTracking": "SERVER",
  "gamSettings": {
    "targetingParameters": {
      "my_key": "my_value",
    },
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://videostitcher.googleapis.com/v1/projects/ PROJECT_NUMBER 
/locations/ LOCATION 
/liveSessions" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/ PROJECT_NUMBER 
/locations/ LOCATION 
/liveSessions/ SESSION_ID 
",
  "playUri": " PLAY_URI 
",
  "manifestOptions": {
    "includeRenditions": [
      {
        "bitrateBps": 150000,
        "codecs": "hvc1.1.4.L126.B0"
      },
      {
        "bitrateBps": 440000,
        "codecs": "hvc1.1.4.L126.B0"
      }
    ],
    "bitrateOrder": "DESCENDING"
  },
  "gamSettings": {
    "streamId": " STREAM_ID 
"
  },
  "liveConfig": "projects/ PROJECT_NUMBER 
/locations/ LOCATION 
/liveConfigs/ LIVE_CONFIG_ID 
",
  "adTracking": "SERVER"
}

C#

Before trying this sample, follow the C# setup instructions in the Video Stitcher API quickstart using client libraries . For more information, see the Video Stitcher API C# API reference documentation .

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  using 
  
  Google.Cloud.Video.Stitcher.V1 
 
 ; 
 public 
  
 class 
  
 CreateLiveSessionSample 
 { 
  
 public 
  
 LiveSession 
  
 CreateLiveSession 
 ( 
  
 string 
  
 projectId 
 , 
  
 string 
  
 location 
 , 
  
 string 
  
 liveConfigId 
 ) 
  
 { 
  
 // Create the client. 
  
  VideoStitcherServiceClient 
 
  
 client 
  
 = 
  
  VideoStitcherServiceClient 
 
 . 
  Create 
 
 (); 
  
  CreateLiveSessionRequest 
 
  
 request 
  
 = 
  
 new 
  
  CreateLiveSessionRequest 
 
  
 { 
  
 Parent 
  
 = 
  
 $"projects/{projectId}/locations/{location}" 
 , 
  
 LiveSession 
  
 = 
  
 new 
  
  LiveSession 
 
  
 { 
  
 LiveConfig 
  
 = 
  
  LiveConfigName 
 
 . 
  FormatProjectLocationLiveConfig 
 
 ( 
 projectId 
 , 
  
 location 
 , 
  
 liveConfigId 
 ) 
  
 } 
  
 }; 
  
 // Call the API. 
  
  LiveSession 
 
  
 session 
  
 = 
  
 client 
 . 
  CreateLiveSession 
 
 ( 
 request 
 ); 
  
 // Return the result. 
  
 return 
  
 session 
 ; 
  
 } 
 }

Go

Before trying this sample, follow the Go setup instructions in the Video Stitcher API quickstart using client libraries . For more information, see the Video Stitcher API Go API reference documentation .

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 stitcher 
  
 "cloud.google.com/go/video/stitcher/apiv1" 
  
 "cloud.google.com/go/video/stitcher/apiv1/stitcherpb" 
 ) 
 // createLiveSession creates a livestream session in which to insert ads. 
 // Live sessions are ephemeral resources that expire after a few minutes. 
 func 
  
 createLiveSession 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectID 
 , 
  
 liveConfigID 
  
 string 
 ) 
  
 error 
  
 { 
  
 // projectID := "my-project-id" 
  
 // liveConfigID := "my-live-config" 
  
 location 
  
 := 
  
 "us-central1" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 stitcher 
 . 
  NewVideoStitcherClient 
 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "stitcher.NewVideoStitcherClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
  Close 
 
 () 
  
 req 
  
 := 
  
& stitcherpb 
 . 
 CreateLiveSessionRequest 
 { 
  
 Parent 
 : 
  
 fmt 
 . 
 Sprintf 
 ( 
 "projects/%s/locations/%s" 
 , 
  
 projectID 
 , 
  
 location 
 ), 
  
 LiveSession 
 : 
  
& stitcherpb 
 . 
 LiveSession 
 { 
  
 LiveConfig 
 : 
  
 fmt 
 . 
 Sprintf 
 ( 
 "projects/%s/locations/%s/liveConfigs/%s" 
 , 
  
 projectID 
 , 
  
 location 
 , 
  
 liveConfigID 
 ), 
  
 }, 
  
 } 
  
 // Creates the live session. 
  
 response 
 , 
  
 err 
  
 := 
  
 client 
 . 
 CreateLiveSession 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "client.CreateLiveSession: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Live session: %v\n" 
 , 
  
 response 
 . 
 GetName 
 ()) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Play URI: %v" 
 , 
  
 response 
 . 
 GetPlayUri 
 ()) 
  
 return 
  
 nil 
 }

Java

Before trying this sample, follow the Java setup instructions in the Video Stitcher API quickstart using client libraries . For more information, see the Video Stitcher API Java API reference documentation .

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 com.google.cloud.video.stitcher.v1. CreateLiveSessionRequest 
 
 ; 
 import 
  
 com.google.cloud.video.stitcher.v1. LiveConfigName 
 
 ; 
 import 
  
 com.google.cloud.video.stitcher.v1. LiveSession 
 
 ; 
 import 
  
 com.google.cloud.video.stitcher.v1. LocationName 
 
 ; 
 import 
  
 com.google.cloud.video.stitcher.v1. VideoStitcherServiceClient 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 CreateLiveSession 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 String 
  
 projectId 
  
 = 
  
 "my-project-id" 
 ; 
  
 String 
  
 location 
  
 = 
  
 "us-central1" 
 ; 
  
 String 
  
 liveConfigId 
  
 = 
  
 "my-live-config-id" 
 ; 
  
 createLiveSession 
 ( 
 projectId 
 , 
  
 location 
 , 
  
 liveConfigId 
 ); 
  
 } 
  
 // Creates a live session given the parameters in the supplied live config. 
  
 // For more information, see 
  
 // https://cloud.google.com/video-stitcher/docs/how-to/managing-live-sessions. 
  
 public 
  
 static 
  
  LiveSession 
 
  
 createLiveSession 
 ( 
  
 String 
  
 projectId 
 , 
  
 String 
  
 location 
 , 
  
 String 
  
 liveConfigId 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // Initialize client that will be used to send requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. 
  
 try 
  
 ( 
  VideoStitcherServiceClient 
 
  
 videoStitcherServiceClient 
  
 = 
  
  VideoStitcherServiceClient 
 
 . 
 create 
 ()) 
  
 { 
  
  CreateLiveSessionRequest 
 
  
 createLiveSessionRequest 
  
 = 
  
  CreateLiveSessionRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setParent 
 ( 
  LocationName 
 
 . 
 of 
 ( 
 projectId 
 , 
  
 location 
 ). 
 toString 
 ()) 
  
 . 
 setLiveSession 
 ( 
  
  LiveSession 
 
 . 
 newBuilder 
 () 
  
 . 
 setLiveConfig 
 ( 
  LiveConfigName 
 
 . 
 format 
 ( 
 projectId 
 , 
  
 location 
 , 
  
 liveConfigId 
 ))) 
  
 . 
 build 
 (); 
  
  LiveSession 
 
  
 response 
  
 = 
  
 videoStitcherServiceClient 
 . 
 createLiveSession 
 ( 
 createLiveSessionRequest 
 ); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Created live session: " 
  
 + 
  
 response 
 . 
  getName 
 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Play URI: " 
  
 + 
  
 response 
 . 
  getPlayUri 
 
 ()); 
  
 return 
  
 response 
 ; 
  
 } 
  
 } 
 }

Node.js

Before trying this sample, follow the Node.js setup instructions in the Video Stitcher API quickstart using client libraries . For more information, see the Video Stitcher API Node.js API reference documentation .

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  /** 
 * TODO(developer): Uncomment these variables before running the sample. 
 */ 
 // projectId = 'my-project-id'; 
 // location = 'us-central1'; 
 // liveConfigId = 'my-live-config-id'; 
 // Imports the Video Stitcher library 
 const 
  
 { 
 VideoStitcherServiceClient 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/video-stitcher 
' 
 ). 
 v1 
 ; 
 // Instantiates a client 
 const 
  
 stitcherClient 
  
 = 
  
 new 
  
  VideoStitcherServiceClient 
 
 (); 
 async 
  
 function 
  
 createLiveSession 
 () 
  
 { 
  
 // Construct request 
  
 const 
  
 request 
  
 = 
  
 { 
  
 parent 
 : 
  
 stitcherClient 
 . 
  locationPath 
 
 ( 
 projectId 
 , 
  
 location 
 ), 
  
 liveSession 
 : 
  
 { 
  
 liveConfig 
 : 
  
 stitcherClient 
 . 
  liveConfigPath 
 
 ( 
  
 projectId 
 , 
  
 location 
 , 
  
 liveConfigId 
  
 ), 
  
 }, 
  
 }; 
  
 const 
  
 [ 
 session 
 ] 
  
 = 
  
 await 
  
 stitcherClient 
 . 
 createLiveSession 
 ( 
 request 
 ); 
  
 console 
 . 
 log 
 ( 
 `Live session: 
 ${ 
 session 
 . 
 name 
 } 
 ` 
 ); 
  
 console 
 . 
 log 
 ( 
 `Play URI: 
 ${ 
 session 
 . 
 playUri 
 } 
 ` 
 ); 
 } 
 createLiveSession 
 (). 
 catch 
 ( 
 err 
  
 = 
>  
 { 
  
 console 
 . 
 error 
 ( 
 err 
 . 
 message 
 ); 
  
 process 
 . 
 exitCode 
  
 = 
  
 1 
 ; 
 });

PHP

Before trying this sample, follow the PHP setup instructions in the Video Stitcher API quickstart using client libraries . For more information, see the Video Stitcher API PHP API reference documentation .

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  use Google\Cloud\Video\Stitcher\V1\Client\VideoStitcherServiceClient; 
 use Google\Cloud\Video\Stitcher\V1\CreateLiveSessionRequest; 
 use Google\Cloud\Video\Stitcher\V1\LiveSession; 
 /** 
 * Creates a live session. Live sessions are ephemeral resources that expire 
 * after a few minutes. 
 * 
 * @param string $callingProjectId     The project ID to run the API call under 
 * @param string $location             The location of the session 
 * @param string $liveConfigId         The live config ID to use to create the 
 *                                     live session 
 */ 
 function create_live_session( 
 string $callingProjectId, 
 string $location, 
 string $liveConfigId 
 ): void { 
 // Instantiate a client. 
 $stitcherClient = new VideoStitcherServiceClient(); 
 $parent = $stitcherClient->locationName($callingProjectId, $location); 
 $liveConfig = $stitcherClient->liveConfigName($callingProjectId, $location, $liveConfigId); 
 $liveSession = new LiveSession(); 
 $liveSession->setLiveConfig($liveConfig); 
 // Run live session creation request 
 $request = (new CreateLiveSessionRequest()) 
 ->setParent($parent) 
 ->setLiveSession($liveSession); 
 $response = $stitcherClient->createLiveSession($request); 
 // Print results 
 printf('Live session: %s' . PHP_EOL, $response->getName()); 
 }

Python

Before trying this sample, follow the Python setup instructions in the Video Stitcher API quickstart using client libraries . For more information, see the Video Stitcher API Python API reference documentation .

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  import 
  
 argparse 
 from 
  
 google.cloud.video 
  
 import 
 stitcher_v1 
 from 
  
 google.cloud.video.stitcher_v1.services.video_stitcher_service 
  
 import 
 ( 
 VideoStitcherServiceClient 
 , 
 ) 
 def 
  
 create_live_session 
 ( 
 project_id 
 : 
 str 
 , 
 location 
 : 
 str 
 , 
 live_config_id 
 : 
 str 
 ) 
 - 
> stitcher_v1 
 . 
 types 
 . 
 LiveSession 
 : 
  
 """Creates a live session. Live sessions are ephemeral resources that expire 
 after a few minutes. 
 Args: 
 project_id: The GCP project ID. 
 location: The location in which to create the session. 
 live_config_id: The user-defined live config ID. 
 Returns: 
 The live session resource. 
 """ 
 client 
 = 
 VideoStitcherServiceClient 
 () 
 parent 
 = 
 f 
 "projects/ 
 { 
 project_id 
 } 
 /locations/ 
 { 
 location 
 } 
 " 
 live_config 
 = 
 ( 
 f 
 "projects/ 
 { 
 project_id 
 } 
 /locations/ 
 { 
 location 
 } 
 /liveConfigs/ 
 { 
 live_config_id 
 } 
 " 
 ) 
 live_session 
 = 
 stitcher_v1 
 . 
 types 
 . 
 LiveSession 
 ( 
 live_config 
 = 
 live_config 
 ) 
 response 
 = 
 client 
 . 
 create_live_session 
 ( 
 parent 
 = 
 parent 
 , 
 live_session 
 = 
 live_session 
 ) 
 print 
 ( 
 f 
 "Live session: 
 { 
 response 
 . 
 name 
 } 
 " 
 ) 
 return 
 response

Ruby

Before trying this sample, follow the Ruby setup instructions in the Video Stitcher API quickstart using client libraries . For more information, see the Video Stitcher API Ruby API reference documentation .

To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  require 
  
 "google/cloud/video/stitcher" 
 ## 
 # Create a live stream session. Live sessions are ephemeral resources 
 # that expire after a few minutes. 
 # 
 # @param project_id [String] Your Google Cloud project (e.g. `my-project`) 
 # @param location [String] The location (e.g. `us-central1`) 
 # @param live_config_id [String] Your live config name (e.g. `my-live-config`) 
 # 
 def 
  
 create_live_session 
  
 project_id 
 :, 
  
 location 
 :, 
  
 live_config_id 
 : 
  
 # Create a Video Stitcher client. 
  
 client 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
 Video 
 :: 
 Stitcher 
 . 
 video_stitcher_service 
  
 # Build the resource name of the parent. 
  
 parent 
  
 = 
  
 client 
 . 
 location_path 
  
 project 
 : 
  
 project_id 
 , 
  
 location 
 : 
  
 location 
  
 # Build the resource name of the live config. 
  
 live_config_name 
  
 = 
  
 client 
 . 
 live_config_path 
  
 project 
 : 
  
 project_id 
 , 
  
 location 
 : 
  
 location 
 , 
  
 live_config 
 : 
  
 live_config_id 
  
 # Set the session fields. 
  
 new_live_session 
  
 = 
  
 { 
  
 live_config 
 : 
  
 live_config_name 
  
 } 
  
 response 
  
 = 
  
 client 
 . 
 create_live_session 
  
 parent 
 : 
  
 parent 
 , 
  
 live_session 
 : 
  
 new_live_session 
  
 # Print the live session name. 
  
 puts 
  
 "Live session: 
 #{ 
 response 
 . 
 name 
 } 
 " 
 end

The Video Stitcher API generates a unique session ID for each request. A session expires if the playUri is not requested within the past 5 minutes.

You can use the returned STREAM_ID to inspect the live session .

Inspect live sessions enabled by Google Ad Manager

To see ad tag details for sessions, use the Stream activity monitor in Ad Manager to see details about ad requests. You can use the STREAM_ID to debug the stream session. To find the STREAM_ID for a live session, see Get a session .

Create a live session Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Create a live session

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

C#

Go

Java

Node.js

PHP

Python

Ruby

Inspect live sessions enabled by Google Ad Manager

Create a live session