This page describes how to manage VOD configs. VOD configs are used to configure VOD sessions. For more details, see the REST documentation.
Before you begin
To create a VOD session, you must first configure an encoder which generates a source HLS or DASH manifest for the VOD asset. These manifests contain certain ad markers at ad break boundaries which are identified by the Video Stitcher API for ad stitching purposes. You can use the Transcoder API to create a transcoding job to generate the manifest files from media file types such as MP4 or MOV.
For more details on the supported HLS and DASH ad markers, see the ad markers documentation.
Define a VOD config
When you define a VOD config, the following fields are required:
sourceUri
adTagUri
sourceUri
specifies the URL to the source VOD asset's HLS or DASH
manifest to insert ads into. The Video Stitcher API returns an HLS playback URL
if the provided URL references an HLS manifest and a DASH playback URL if the
provided URL references a DASH manifest. You can use an existing manifest file
or you can
create your own VOD source files.
adTagUri
specifies the URL of the ad server that returns the ad metadata.
The VOD config contains an optional field for defining custom headers.
Register a VOD config
To register a VOD config, use the
projects.locations.vodConfigs.create
method.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location in which to create your VOD config; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: a user-defined identifier for the VOD config. This ID can only contain lower-case letters, numbers, and hyphens. The first character must be a letter, the last character must be a letter or a number, and the entire ID has a 63 character maximum.VOD_CONFIG_ID
: the URI of the media to stitch. This URI must reference either an MPEG-DASH manifest (MPD) file or an HLS manifest (M3U8) file. Use a public URI or an unsigned URI for which you registered a CDN key.VOD_URI the public URI of the ad tag; if you don't have one, you can use a VMAP Pre-roll sampleAD_TAG_URI
Request JSON body:
{ "sourceUri": "VOD_URI ", "adTagUri": "AD_TAG_URI " }
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
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' { "sourceUri": "VOD_URI ", "adTagUri": "AD_TAG_URI " } 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 /vodConfigs?vodConfigId=VOD_CONFIG_ID "
PowerShell (Windows)
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:
@' { "sourceUri": "VOD_URI ", "adTagUri": "AD_TAG_URI " } '@ | 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 /vodConfigs?vodConfigId=VOD_CONFIG_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.common.OperationMetadata", "createTime":CREATE_TIME , "target": "projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID ", "verb": "create", "cancelRequested": false, "apiVersion": "v1" }, "done": false }
OPERATION_ID
,
which is the last part of the name
field, to use in the next section.
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.
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.
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.
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.
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.
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.
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.
Check for the result
To check if the VOD config has been created, use the
projects.locations.operations.get
method. If the response contains "done: false"
, repeat the command until the
response contains "done: true"
.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the data; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: the identifier for the operationOPERATION_ID
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID "
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.common.OperationMetadata", "createTime":CREATE_TIME , "endTime":END_TIME , "target": "projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID ", "verb": "create" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.video.stitcher.v1.VodConfig", "name": "projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID ", "sourceUri": "VOD_URI ", "adTagUri": "AD_TAG_URI ", "state": "READY" } }
Get a VOD config
To get the details for a specific VOD config, use the
projects.locations.vodConfigs.get
method.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the VOD config; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: the user-defined identifier for the VOD configVOD_CONFIG_ID
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID "
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID ", "sourceUri": "VOD_URI ", "adTagUri": "AD_TAG_URI ", "state": "READY" }
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.
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.
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.
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.
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.
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.
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.
Update a VOD config
To update a VOD config, use the
projects.locations.vodConfigs.patch
method. The following example updates the sourceUri
field.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the VOD config; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: the user-defined identifier for the VOD configVOD_CONFIG_ID
: the updated URI of the media to stitchVOD_URI
Request JSON body:
{ "sourceUri": "VOD_URI " }
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
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' { "sourceUri": "VOD_URI " } EOF
Then execute the following command to send your REST request:
curl -X PATCH \
-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 /vodConfigs/VOD_CONFIG_ID ?updateMask=sourceUri"
PowerShell (Windows)
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:
@' { "sourceUri": "VOD_URI " } '@ | 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 PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID ?updateMask=sourceUri" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.common.OperationMetadata", "createTime":CREATE_TIME , "target": "projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID ", "verb": "update" }, "done": false }
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.
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.
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.
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.
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.
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.
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.
List all registered VOD configs
To list all of the VOD configs registered for a given location in a project,
use the
projects.locations.vodConfigs.list
method.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the VOD configs; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs"
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "vodConfigs": [ { "name": "projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID ", "sourceUri": "VOD_URI ", "adTagUri": "AD_TAG_URI ", "state": "READY" }, { "name": "projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/my-other-vod-config ", "sourceUri": "my-other-vod-stream-uri ", "adTagUri": "my-other-ad-tag-uri ", "state": "READY" } }
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.
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.
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.
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.
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.
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.
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.
Additional results
The curl
response may include a nextPageToken
, which you can use to retrieve
additional results:
{ "vodConfigs": [ ... ], "nextPageToken": "NEXT_PAGE_TOKEN " }
You can send another curl
request, including the value of
NEXT_PAGE_TOKEN, to list the additional configs. Append the following
to the URL in the preceding API call:
?pageToken=NEXT_PAGE_TOKEN
See the relevant client library for more information on using this token.
Delete a VOD config
If a registered VOD config is no longer needed, delete it using the
projects.locations.vodConfigs.delete
method.
Before using any of the request data, make the following replacements:
: your Google Cloud project number; this is located in the Project number field on the IAM Settings pagePROJECT_NUMBER
: the location of the VOD config; use one of the supported regionsLOCATION Show locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
: the user-defined identifier for the VOD configVOD_CONFIG_ID
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID "
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER /locations/LOCATION /operations/OPERATION_ID ", "metadata": { "@type": "type.googleapis.com/google.cloud.common.OperationMetadata", "createTime":CREATE_TIME , "target": "projects/PROJECT_NUMBER /locations/LOCATION /vodConfigs/VOD_CONFIG_ID ", "verb": "delete" }, "done": false }
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.
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.
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.
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.
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.
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.
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.