Upload an asset with the Wowza Video REST API

The Wowza Video™ Asset Manager allows users users to ingest, store, and tag video content in order to centralize, reuse, amplify, and provide user-friendly access to assets. See Video CMS: What it is and why you need one for more information.

You must obtain a license for the Asset Manager to add this capability to your new or existing account. Contact sales@wowza.com for more information.

This article demonstrates how to upload .mp4 files to the Wowza Video Asset Manager using the Wowza Video REST API.

Before you start


You should be familiar with the following concepts:

  • API authentication methods. We use JSON web tokens for API authentication. See Authentication for more information.
  • Environment variables. We use environment variables for the API version and your JWT in the cURL API request examples in this topic to make it easier for you to copy, paste, and run commands in your Terminal or Command Prompt window. If you don't set environment variables for these values, you'll need to manually enter the correct values in the code samples throughout this tutorial. See Tools for testing the API for instructions.

1. Create an asset

Add assets to the Wowza Video Asset Manager by sending a POST request to the /assets endpoint.

You can update the asset to have a description and tags once the asset has finished transcoding.

You can use the following sample request, making sure to:

  • Set file_name to the name of the .mp4 file you are uploading.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "asset": {
     "file_name": "asset1.mp4"
   } 
}' "${WV_HOST}/api/${WV_VERSION}/assets"

Sample response

The response includes:

  • An id for the asset that you'll use to complete other actions on the asset.
  • An upload_url for the asset that you'll use in step 2 to upload the asset to the Wowza Video Asset Manager.
     
    Note: The URL includes the X-Goog-Expires header which sets the signed URL to expire in 300 seconds. Typically, this is sufficient time when you're running built code, but if you're manually walking through these steps to see the workflow, you might encounter this expiration between this step and the next. If you do, you'll need to make this call again for a new upload URL with a new expiration.
{
    "asset": {
        "created_at": "2020-01-29T17:16:21.956Z"
        "id": "abcntjvl",
        "file_name": "asset1.mp4",
        "upload_url": "https://storage.googleapis.com/qa-wse-recordings/uploads/recording_h4qntp5j/MyFile.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=wcl-transcoder%40useful-figure-89722.iam.gserviceaccount.com%2F20220214%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20220214T213737Z&X-Goog-Expires=300&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=994fe495425f26ba24e05233c066fdbcd0ab4c5779e1743f118141f61d353edb0eeafb463f766ca69deefb5910a7b29a8436c515f83871b0a4c5786236560bd28407ea9489458c4dc8d685d1601ac96cb71859ff8b5cff0e80a8ce43c5cf838e11b716ec9688138d96a879319b66cf73279cdba2d9a940bde73aa22d2fbb83bedaf8f477c44d65ebe4500fcdc07d4f19b3e40418fc689f48f84f5e96cf04e8f549108cb5ba7f134f8943101f0afe23dd7d38b982510696042f9dabb16cda21c02ed67deae5b752a787cb9dae1012ef772f4c2b3a959afb1fb1cf99f38fd557bedeb41b3399f2ba028b05c009424acf6055420d80f65b30235fec9e57e0bde7ef"
    }
}

2. Upload the asset

You can upload the file with the cURL --upload-file option.

You can use the following sample request, making sure to:

  • Set upload_url to the upload_url returned when you created the asset.
  • Set file_path to the location on your computer for the file you would like to upload.

    For example, ~/Downloads/MyFile.mp4

Sample request

curl -X PUT -H 'Content-Type: video/mp4' --upload-file file_path 'upload_url'

This is the sample request using the file_path and upload_url from the previous step:

curl -X PUT -H 'Content-Type: video/mp4' --upload-file MyFile.mp4 'https://storage.googleapis.com/qa-wse-recordings/uploads/recording_h4qntp5j/MyFile.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=wcl-transcoder%40useful-figure-89722.iam.gserviceaccount.com%2F20220214%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20220214T213737Z&X-Goog-Expires=300&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=994fe495425f26ba24e05233c066fdbcd0ab4c5779e1743f118141f61d353edb0eeafb463f766ca69deefb5910a7b29a8436c515f83871b0a4c5786236560bd28407ea9489458c4dc8d685d1601ac96cb71859ff8b5cff0e80a8ce43c5cf838e11b716ec9688138d96a879319b66cf73279cdba2d9a940bde73aa22d2fbb83bedaf8f477c44d65ebe4500fcdc07d4f19b3e40418fc689f48f84f5e96cf04e8f549108cb5ba7f134f8943101f0afe23dd7d38b982510696042f9dabb16cda21c02ed67deae5b752a787cb9dae1012ef772f4c2b3a959afb1fb1cf99f38fd557bedeb41b3399f2ba028b05c009424acf6055420d80f65b30235fec9e57e0bde7ef'

Tip: If you are manually walking through these steps and would like additional error reporting as well as a visual indicator on the command line regarding upload status, you can append a log-to-file command to the cURL request above: >log_file.out

You'll get a log file written locally and upload status in the command line while the file is uploading, like:

3. View the asset to visually confirm the asset is uploaded

If you want to visually confirm the file is uploaded as you're buildling code, you can shorten the upload_url to remove the header information parameters and open the URL in a web browser.

  1. Shorten the upload_url to remove the header information parameters. You'll remove everything after the file name.

    For example:

    https://storage.googleapis.com/qa-wse-recordings/uploads/recording_h4qntp5j/MyFile.mp4

     
  2. Paste the shortened URL into a web browser.

You should now be able to view the asset in the browser so you know the upload was successful.

4. Notify the Wowza Video Asset Manager that the upload has completed

Once the upload has completed, you need to notify the Wowza Video Asset Manager by sending a PATCH request to the /assets/{id}/upload_completed endpoint.

You can use the following sample request, making sure to:

  • Set file_size to the size of the asset.
  • Set duration to the length of the asset.

Sample request

Endpoint Reference

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "asset": {
     "file_size": 1570024,
     "duration": 30
   } 
}' "${WV_HOST}/api/${WV_VERSION}/assets/{id}/upload_completed"

5. Check the status of your asset

Once you notify the Wowza Video Asset Manager that your upload has completed, your asset will begin transcoding. This may take several minutes. You'll need to check that the state of your asset is "complete" before you can add tags and a description to your asset. Send a GET request to the /assets/{id} endpoint to check the state of the asset.

You can use the following sample request, making sure to:

  • Set id to the ID of the asset returned in Step 1.

Sample request

Endpoint Reference

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/assets/{id}"

Sample response

The response includes:

  • The state of the asset of the asset. The state can be returned as "uploading," "processing," "removing," "completed," or "failed." The state must be returned as completed before you can add a description and tags to your asset.
{
    "asset": {
        "id": "abcntjvl",
        "name": "asset1.mp4",
        "created_at": "2020-01-29T17:16:21.956Z",
        "updated_at": "2022-03-30T16:44:46.499Z",
        "playback_enabled": false,
        "thumbnail_url": "https://storage.googleapis.com/qa-wse-recordings/frP7Drv3/recording_hw07v2r9/hw07v2r9_thumbnail.jpg",
        "state": "processing",
        "processing_percentage": 0.0,
        "file_size": 1570024,
        "playback_url": "https://cdn3-qa.wowza.com/2/aXo2QTd0Y05WMGkw/M2gyUWVV/hls/cfvvbphl/playlist.m3u8",
        "download_url": "https://storage.googleapis.com/qa-wse-recordings/frP7Drv3/recording_hw07v2r9/asset1.mp4",
        "file_name": "test1.mp4",
        "description": null,
        "available_renditions": [],
        "duration": 30,
        "tags": [],
        "unique_viewers": 0,
        "total_viewing_time": 0,
        "average_view_time": 0,
        "total_storage_size": 1570024,
        "vod_stream_id": "cfvvbphl",
        "recording_id": "hw07v2r9"
    }
}

6. Set your asset to enable playback

Once your asset is uploaded and transcoding has completed, you can set your asset to enable playback by sending a PATCH request to the /assets/{id} endpoint.

You can use the following sample request, making sure to:

  • Set playback_enabled to true.
  • (Optional) Set description to a descriptive string for the asset. Descriptions can be up to 255 characters long.
  • (Optional) Set tags to any descriptive tags you choose for the asset.

Sample request

Endpoint Reference

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "asset": {
     "playback_enabled": true,
     "description": "This is my new asset.",
     "tags": ["new"]
   } 
}' "${WV_HOST}/api/${WV_VERSION}/assets/{id}"

Sample response

{
    "asset": {
        "id": "abcntjvl",
        "name": "new name",
        "created_at": "2020-01-29T17:16:21.956Z",
        "updated_at": "2022-03-30T17:20:01.421Z",
        "playback_enabled": true,
        "thumbnail_url": "https://storage.googleapis.com/qa-wse-recordings/frP7Drv3/recording_9zkmrv1b/9zkmrv1b_thumbnail.jpg",
        "state": "completed",
        "processing_percentage": 100.0,
        "file_size": 1570024,
        "playback_url": "https://cdn3-qa.wowza.com/2/ZFVwZk1DNGRmZi9s/SFk3R0lZ/hls/1t2vvfhn/playlist.m3u8",
        "download_url": "https://storage.googleapis.com/qa-wse-recordings/frP7Drv3/recording_9zkmrv1b/test1.mp4",
        "file_name": "test1.mp4",
        "description": "This is my new asset.",
        "available_renditions": [
            {
                "height": 720,
                "width": 1280,
                "bitrate_kbps": 48486
            },
            {
                "height": 360,
                "width": 640,
                "bitrate_kbps": 17616
            },
            {
                "height": 432,
                "width": 768,
                "bitrate_kbps": 22070
            },
            {
                "height": 1080,
                "width": 1920,
                "bitrate_kbps": 102440
            },
            {
                "height": 540,
                "width": 960,
                "bitrate_kbps": 30778
            }
        ],
        "duration": 30,
        "tags": ["new"],
        "unique_viewers": 0,
        "total_viewing_time": 0,
        "average_view_time": 0,
        "total_storage_size": 1570024,
        "vod_stream_id": "1t2vvfhn",
        "recording_id": "9zkmrv1b"
    }
}

Related transcoder API requests